HTTP API: session_domain

Where an episode is: minted, open, detached from the connection that held it, or closed into the immutable record.

use majordomus_cli::session::EpisodeState;

assert!(EpisodeState::Open.may_move_to(EpisodeState::Closed));
assert!(!EpisodeState::Closed.may_move_to(EpisodeState::Open), "a record is immutable");
assert!(EpisodeState::Open.may_move_to(EpisodeState::Open), "a resume is not a move");
assert!(EpisodeState::Closed.is_final());

One identity of this checkout, as this executable computes it and as each store spells it. What session.identity answers, and the direct projection of the audit's table.

use majordomus_cli::session::{identities, IdentityFacet};

let dir = tempfile::tempdir().unwrap();
let facets: Vec<IdentityFacet> = identities(dir.path());
let repository = facets.iter().find(|f| f.subject == "repository").expect("a facet");
assert!(repository.spellings.len() >= 2, "one word, two writers, two values");

The identities of this checkout: one facet per subject, with a standing note about what a reader must not do with them.

use majordomus_cli::capability::builtin::IdentityReport;
use majordomus_cli::session::identities;

let dir = tempfile::tempdir().unwrap();
let report = IdentityReport {
    checkout: dir.path().display().to_string(),
    facets: identities(dir.path()),
    findings: Vec::new(),
};
let subjects: Vec<&str> = report.facets.iter().map(|f| f.subject.as_str()).collect();
assert_eq!(subjects, ["repository", "checkout", "episode", "provider_session"]);

The lifecycle machine, with the decision it implements, so that a reader meeting it in a projection can go and read why it is shaped this way.

use majordomus_cli::capability::builtin::MachineReport;
use majordomus_cli::session::Machine;

// the report is the machine plus one citation; the machine itself is derived from the
// types and carries no second list
let report = MachineReport { machine: Machine::describe(), decision: "adr-0047".into() };
assert!(report.machine.transitions.iter().any(|t| !t.moves_state), "a checkpoint is an event");
assert!(report.decision.contains("0047"));

One store's spelling of one subject. Which half of the layer wrote it, what wrote it, and the value it would have here.

use majordomus_cli::session::{RecordedSpelling, Spelling};

let local = RecordedSpelling {
    spelling: Spelling::Local,
    writer: "mj_git_repo_id (lib/common.sh)".into(),
    value: "/src/repo/.git".into(),
};
// knowing which half a string came from is what stops a path being compared with a URL
assert_eq!(local.spelling.as_str(), "local");
assert!(local.value.starts_with('/'));

Which store a recorded identity was read from, kept beside the value.

The point is not to choose between mj_git_repo_id and mj_repository_id, or between worktree: and worktree_id:. It is to stop pretending they are one value. A reader that knows a string is the local spelling can compare it with other local spellings and can refuse to compare it with a shared one, which is precisely the comparison that produced "these two records are about different repositories" for records of the same repository written four minutes apart.

use majordomus_cli::session::Spelling;
// the two halves are different answers to one question, and are never compared
assert_ne!(Spelling::Local, Spelling::Shared);
assert_eq!(Spelling::Canonical.as_str(), "canonical");

One state of the machine: its word, whether an episode ever leaves it, and where it may go from there.

use majordomus_cli::session::{EpisodeState, Machine, StateView};

let m = Machine::describe();
let closed: &StateView =
    m.states.iter().find(|s| s.state == EpisodeState::Closed).expect("a state");
assert!(closed.terminal && closed.may_move_to.is_empty());

What moved an episode. The vocabulary the ADR 0052 audit needs: open, resume, checkpoint, detach, close, recover.

One of them does not change the state, and it is a transition anyway. A checkpoint leaves an open episode open — but it is one of the two events whose absence is what the audit was looking for, and an event that is modelled as "nothing happened" cannot be counted. The six days of silence were six days in which session.started and session.closed kept arriving and the two events that produce the records a worker resumes from did not. A vocabulary in which those two are not events is a vocabulary in which that outage is invisible.

use majordomus_cli::session::{EpisodeState, Transition};

// a checkpoint is a transition that does not move the state, and says so
let c = Transition::Checkpoint;
assert_eq!(c.from_to(), (EpisodeState::Open, EpisodeState::Open));
assert!(!c.moves_state());

// a resume is canonically the return to a detached episode; a provider's start event
// arriving at one that is already open is the same transition seen from `Open`, which
// the machine allows without a move
assert_eq!(Transition::Resume.from_to(), (EpisodeState::Detached, EpisodeState::Open));
assert!(EpisodeState::Open.may_move_to(EpisodeState::Open));

// and every transition's own move is one the machine allows
for t in Transition::ALL {
    let (from, to) = t.from_to();
    assert!(from.may_move_to(to), "{} is not a legal move", t.as_str());
}

One transition of the machine: its word, the states it runs between, and whether it moves the state at all.

use majordomus_cli::session::{Machine, Transition, TransitionView};

let m = Machine::describe();
let close: &TransitionView = m
    .transitions
    .iter()
    .find(|t| t.transition == Transition::Close)
    .expect("a transition");
assert!(close.moves_state);