Record what one worker did in one sitting

setup: installed
given:
  - 'Majordomus installed, no session open'
steps:
  - id: open
    run: ['session', 'start', '--worker', 'some-provider/some-model']
    note: 'one execution episode of one worker begins'
    expect:
      exit: 0
      stdout_contains: ['^session s-[0-9]+-[0-9a-f]+ opened at']
  - id: refuse-a-second
    run: ['session', 'start']
    note: 'one session per checkout at a time'
    expect:
      exit: 15
      stdout_contains: ['is open here']
  - id: close
    run: ['session', 'close']
    note: 'the envelope: identity, a temporal boundary, references to what the episode produced'
    expect:
      exit: 0
      stdout_contains: ['^\.ai/repo/sessions/']
  - id: an-object-of-the-layer
    run: ['knowledge', 'nodes', '--kind', 'session']
    note: 'the record is a shared object the moment it is committed: one source class discovers it, and the index, MCP, the object routes, the graph and the site follow without being told'
    expect:
      exit: 0
  - id: ledger
    run: ['history']
    note: 'the ledger carries both ends of the episode'
    expect:
      exit: 0
      stdout_contains: ['session.started', 'session.closed']
then:
  - 'a closed session is an envelope, never a transcript'
  - 'the envelope is a shared object of the layer, discovered rather than registered'
  - 'which work happened together, and in what order, is answerable'

The scenario

Executed against the real tool, in a repository prepared by installed, every time this site is generated. What follows is not a description of what should happen; it is what happened.

What the tool did

Evidence of the run this page was generated from: pass, 5 step(s). Output is normalised: the repository's path, timestamps, ids and durations are placeholders; nothing else is edited.

Tested by test/cases/94_use_cases.sh, which runs every scenario and refuses a step whose recorded output is not what it produced.

1. 1$ majordomus session start --worker some-provider/some-model exit 0

   one execution episode of one worker begins

   session s-<id> opened at <time> (head <head>)
   working context: .ai/local/session-contexts/<time>--s-<id>.md
   next: majordomus plan next; majordomus context; majordomus session close when the episode ends

   • exit 0
   • stdout_contains /^session s-[0-9]+-[0-9a-f]+ opened at/
2. 2$ majordomus session start exit 15

   one session per checkout at a time

   majordomus: session s-<id> is open here since <time>; run majordomus session close first

   • exit 15
   • stdout_contains /is open here/
3. 3$ majordomus session close exit 0

   the envelope: identity, a temporal boundary, references to what the episode produced

   majordomus: session close: knowledge derived: knowledge derive: 0 written, 0 unchanged, 0 skipped for episode s-<id>
   .ai/repo/sessions/<time>--s-<id>--main--<head>--<hash>.md

   • exit 0
   • stdout_contains /^\.ai/repo/sessions//
4. 4$ majordomus knowledge nodes --kind session exit 0

   the record is a shared object the moment it is committed: one source class discovers it, and the index, MCP, the object routes, the graph and the site follow without being told

   knowledge nodes: 0 in scope all, kind session
   INFO knowledge   . — the schema check was not asked for (MAJORDOMUS_KNOWLEDGE_SCHEMA=unasked), so no file was checked against the schema of its kind

   • exit 0
5. 5$ majordomus history exit 0

   the ledger carries both ends of the episode

   <time>  projections.updated -                      <head>  targets=3
   <time>  session.started     -                      <head>  
   <time>  knowledge.derived   -                      <head>  
   <time>  session.closed      -                      <head>  

   • exit 0
   • stdout_contains /session.started/
   • stdout_contains /session.closed/

Why the tool knows this

The chain from this page to the code: the use case names commands, rules and claims; each rule is dispatched from the registry and each claim names the test that proves it; the scenario above executed the commands. Nothing in this chain is prose about intent.

• majordomus sessionOpen, inspect and close one execution episode.
• majordomus historyRead the append-only ledger back, filtered by task, event or time.
• majordomus knowledgeThe compiled index over what this repository states, and the candidate records it derives from what an episode did.

The rules that make it hold

• ✕blocking Ledger integrityEvery line of the append-only ledger is a well-formed event; the one durable record nothing else can reconstruct stays readable.
• ✕blocking Session records are shared objects with a closed field setA closed execution episode is written once, into the layer's sessions section, against a schema that admits what the repository can prove and nothing else.

Guarantees exercised

• ○guaranteed Every line of the append-only ledger is a well-formed event, and a malformed line is a failure rather than a skipped record
• ○guaranteed The ledger is readable back as operational history, filtered by task, event and time
• ○guaranteed The ledger's event vocabulary is closed, on the way in and on the way out
• ○guaranteed A closed execution episode is a shared object of the layer, written by the tool from git and the ledger, valid against a contract that admits no conversation and no absolute path, and discovered rather than registered

Related use cases

Computed from what they share: claims, rules, commands, category, applications. Nobody maintains this list.

• Read back what happened, and keep the ledger within its capRead the append-only ledger as operational history, filtered by task and event, validate every line, and rotate the oldest lines into an archive rather than deleting them.
• Record a decision so the next worker can find itWrite down what was decided and why as state, then find it again without reading a conversation.
• Have the session opened and closed without anybody remembering toWire the provider's own session events, and the episode opens when the sitting begins, hands the worker what the last one left, records what a compaction is about to discard, and closes with a continuation record beside its envelope.
• Find out what has drifted since anyone last lookedAsk what has moved, rather than whether anything is wrong.
• Hand work over with a question still open, and keep it blockingClose a task into a handover while a question is unresolved, start the follow-up task, and see the same question still refuse acceptance there.

The moments this answers

• → asked what the workers did last night and had only transcripts to grep A conversation log records what was said, not what happened, so the operational question has to be answered by a person reading prose.
• → could not say why one provider was used for that work and another for this Provider and model selection is made implicitly, per session, and recorded nowhere, so it cannot be reviewed or repeated.
• → looked at the bill and could not say which of it produced anything Consumption is measured per account and outcomes are recorded per person, so the two can never be joined.
• → could not reproduce a result because nothing recorded the state it came from The result is recorded and the conditions that produced it are not, so it is an anecdote rather than a measurement.
• → was asked who made a change and under what policy, and had only a commit Attribution stops at the commit, so what authorised a change, what verified it and what governed it are unrecoverable.