ADR: the committed ledger of a coordination Mission is the blob on its coordination branch
The committed ledger of a coordination Mission is the blob on its coordination branch
Status: Proposed (2026-11-06). The operator accepts it by merging the pull request that carries it, together with the other records of the set.
Date: 2026-11-06
Deciders: Stijn Dejongh (operator). Ruling 4 of epic #7276 is DM 01M6QY371KRY5XXQMDQ4WZR1YE in Mission lane-worktree-model-hardening-01M6QY1M.
Technical Story:
- #7284 (S9), epic #7276. ADRs only; the implementation follows migration step 4 (#6117).
- Discharges the D-6 bullet of ADR 2026-10-22-1 on the publication seam (mapping in that record’s Amendment 2026-11-06).
- Amends ADR 2026-10-13-2 D-2 (the ledger is the publication seam) for coordination Missions, and ADR 2026-10-01-2 D-3 and D-6 (the read API composes existing read models; it is a pull over the committed ledger).
- Related records of the same set: C-1 ADR 2026-11-06-4, C-2 ADR 2026-11-06-5, events ADR-0007
docs/adr/0007-write-service-commits-coordination-status-by-ref.mdand events ADR-0008docs/adr/0008-read-service-reads-coordination-ledger-from-git-objects.mdinspec-kitty/spec-kitty-events, branchmain(merged fromissue-7284-coordination-ref-write-adrs), PR spec-kitty/spec-kitty-events#215. ADR-0008 decides how the Java read service reads the blob; this record decides what the committed ledger is and what the CLI’s cursor names. - Read contract: ADR 2026-11-06-2 (one status read contract, S1).
Reader: a maintainer of spec-kitty events tail, the Mission Status Read API, or a subscriber such as spec-kitty/event-router.
Context and Problem Statement
ADR 2026-10-13-2 D-2 makes the ledger the publication seam: a subscriber learns about events by reading the committed status.events.jsonl, through spec-kitty events tail (status/tail_reader.py::TailCursor) or the Mission Status Read API (ADR 2026-10-01-2), never by being called. Both read a file at a path.
From C-1’s step 4a, a coordination Mission has no coordination worktree: the committed tree of refs/heads/<coord> is the only copy of its ledger. A reader that reads a path would read nothing or a stale husk. Two further facts follow:
TailCursor(offset, content_invariant)is a byte offset into one file. A cursor taken on the coordination branch’s blob does not carry over to the target’s blob after consolidation, because the union at projection may reorder or deduplicate lines (ADR 2026-02-09-3), and itsResumeRefusedreasons (negative,out_of_range,misaligned,content_mismatch) cannot say why.- Today’s read oracle answers an unmaterialized coordination Mission by falling back to the primary directory (
probe_coord_statereturnsUNMATERIALIZED;src/specify_cli/missions/_read_path_resolver.py). Events ADR-0008 D-1 makes the Java read service follow whatever the oracle answers; the two must agree when the ref is missing.
Decision Drivers
- One committed ledger for every consumer: the writer’s commit (ruling 8).
- The read API’s guarantees (ADR 2026-10-01-2 D-6): read-only, no lock, independent of drain.
- Python and Java answer the same Mission the same way (ADR 2026-10-29-1 D-6, D-7).
- A cursor never silently skips or repeats events.
Considered Options
For the cursor (D-4), the open choice of this record:
- The cursor names the commit it was taken at (recommended).
- The cursor names the blob it was taken in.
- No change: the offset and content invariant only.
Decision Outcome
Each decision is marked (derived) or (open); open choices carry a recommendation (Mission assumption A-12).
D-1: the publication seam of a coordination Mission is the blob at its ref (derived; amends ADR 2026-10-13-2 D-2)
For a coordination topology (coord, lanes_with_coord), the committed ledger is the status.events.jsonl blob at refs/heads/<coord>, at kitty-specs/<mission-dir>/status.events.jsonl. After consolidation it is the target’s committed copy. “Committed” means reachable from that ref, never a working-tree file. For single_branch and lanes Missions, D-2 of ADR 2026-10-13-2 is unchanged. No new read path, toggle or daemon is added; publication stays on by default.
D-2: the read API’s pull reads git objects for coordination Missions (derived; amends ADR 2026-10-01-2 D-3, D-6)
- The read API’s pull, for a coordination Mission, reads the blob of D-1. It stays read-only, takes no lock and is independent of drain (D-6 unchanged in meaning).
- Python side: every read goes through the one read door of ADR 2026-11-06-2, whose
COORD_BRANCH_REFsource reads the ref withgit cat-file --batch(one batched subprocess per Mission per command). The door replaces D-3’s “_read_path_resolverandMissionStatus.loadpath” as the coordination-aware read surface; the read models D-3 composes (materialize_snapshot,reconstruct_wp_view,TailCursor) take their bytes from it. - Java side: events ADR-0008 (an in-process git-object adapter of
MissionEventSource;ReadDirResolver’s coordination case reads the ref). - One read pins one tip: every coordination-branch file of one answer comes from the same commit.
D-3: a missing ref is a typed error, in both languages (derived; oracle fallback parity)
The oracle’s fallback changes so that Java and Python agree on a missing ref (events ADR-0008 D-1). It follows ADR 2026-11-06-2’s read contract:
- Unmaterialized (the branch exists, no worktree; from step 4a, every coordination Mission): read the ref, never the primary directory.
- Missing ref:
CoordinationBranchDeletedwhen the probe classifies the declared branch as deleted;StatusSurfaceRefUnreadable(STATUS_SURFACE_REF_UNREADABLE) for an unreadable ref, a missing object or a git failure. Never a primary-directory read. - Readable ref, absent path:
ABSENT, an empty history. - The pre-seed fallback of ADR 2026-11-06-2 (branch exists, no log yet, the write checkout read with
fallback_reasonstamped) is open:- (a) keep it in both languages (the Java service already reads
meta.jsonfrom the primary directory, so it could read the write checkout’s log too); - (b) retire it at step 4a: C-1 D-9 seeds the coordination branch from the write checkout during the drain, and from step 4a the service’s first coordination write creates the path (events ADR-0007 D-1,
update-index --add), so a readable ref without the path truly means “no events”. - Recommendation: (b). It leaves Java with one rule and no working-tree read; until step 4a the Python door keeps the declared fallback and
ReadDirResolveris unchanged (events ADR-0008 D-1, “until migration step 4”).
- (a) keep it in both languages (the Java service already reads
- Conformance: the corpus compares only shapes both sides read the same way. The unmaterialized-coordination cell joins the comparison when ADR-0008’s adapter ships, with the no-worktree fixture of ADR-0008 D-3.
D-4: the events tail cursor names its source (open; recommendation: option 1)
Option 1, the commit (recommended): TailCursor(offset, content_invariant, source_ref, commit).
source_refis the ref the blob was read from (refs/heads/<coord>, or the target after consolidation);commitis the commit it was read at.- Resume on the same ref: when
commitis an ancestor of the ref’s current tip and the blob atcommitis a byte prefix of the current blob (the existing content invariant), resume by offset. A coordination log only grows by append (events ADR-0007 D-2), so this is the normal case. - Resume after the source moved (the coordination branch was consolidated onto the target and deleted, or the prefix no longer holds): refuse with a new
ResumeRefusedreason,source_moved, naming the new source and the last event id the cursor had passed. The consumer resumes from that event id. The CLI does not remap offsets by event id itself. - Polling is a cheap
git rev-parseofsource_ref. - A cursor with no source (taken before this change, or on a
single_branchorlanesMission) keeps today’s meaning: an offset into the write checkout’s file.
Option 2, the blob id: TailCursor(offset, content_invariant, blob). Considered: it detects that the bytes changed, which the content invariant already does, but cannot tell an append from a consolidation, and gives no ancestry to reason with.
Option 3, no change. Rejected: after consolidation a coordination cursor is refused with content_mismatch or, worse, lands on a misaligned but valid line boundary of the reordered target log.
Remap by event id inside the CLI (on source_moved) was considered and left out: it makes the CLI own a second ordering of the same events; the consumer already holds the event ids.
The cursor change is consumer-visible (spec-kitty/event-router). If it is taken, the mission-status contract’s stream cursor changes before that contract’s 1.0.0 (events ADR-0008 D-4), and events tail documents the new reason.
D-5: retention is unchanged (derived)
ADR 2026-10-13-2 D-3 stands: the coordination branch’s history is git’s to keep until consolidation, and the teardown’s branch delete is its only removal, under the destructive authority (ruling 7, git/destructive_guard.py; ADR 2026-11-06-1 on PR #7275).
D-6: JGit or a subprocess (open; not ruled here)
How each side reads git objects stays open in core (A-12). The options are an in-process reader (pinned JGit, or a minimal reader of loose objects, packs and refs), or a git subprocess (cat-file --batch). Recommendation: core rules nothing for Java; it follows events ADR-0007 D-5 (a git subprocess for writes) and events ADR-0008 D-2 (in process for reads, with a named source fault for an unsupported ref backend). The Python CLI keeps its batched git cat-file --batch subprocess (Mission research R-12: no Python git library).
D-7: what stays open (open)
- Whether the read API’s overview cursor becomes a commit id (default: it follows D-4 if option 1 is taken).
- Whether
events tailpolls the ref or watches the reflog (default: polls,rev-parse). - The pre-seed fallback (D-3) and the cursor (D-4), as above.
Consequences
Positive
- Every consumer reads exactly what the writer committed; the husk ambiguity of a stale coordination directory disappears.
- Java and Python give the same answer for a missing coordination ref.
- A consumer can tell an append from a consolidation, and is never resumed into a reordered log.
Negative
- A new
ResumeRefusedreason and a cursor shape change, visible to consumers. - The read path of a coordination Mission costs a git subprocess on the Python side.
Neutral
single_branchandlanesMissions read as today.- Retention, drain and the produce seam (
status/adapters.py) are unchanged.
Confirmation
Named here, to be written by the step-4 Mission (the Java side by its own Confirmation in events ADR-0008):
tests/status/test_events_tail_coordination_ref.py:events tailon a coordination Mission with no coordination worktree reads the blob at the ref and emits every committed event once.tests/status/test_tail_cursor_source_ref.py: a cursor resumes by offset after appends on the same ref; after consolidation and branch deletion it refuses withsource_moved, naming the target and the last event id; a sourceless cursor keeps today’s behaviour.tests/status/test_read_door_missing_ref_parity.py: a deleted coordination branch raisesCoordinationBranchDeleted, an unreadable ref raisesStatusSurfaceRefUnreadable, an absent path reads empty, and no case reads the primary directory.- The no-worktree corpus fixture of events ADR-0008 D-3, compared against the Python oracle.
Pros and Cons of the Options
1. The cursor names the commit (recommended)
- Good: ancestry tells append from consolidation; cheap polling; exact snapshot re-read.
- Bad: a cursor shape change and a new refusal reason.
2. The cursor names the blob
- Good: a smaller change.
- Bad: duplicates the content invariant; no way to tell why the bytes changed.
3. No change
- Good: nothing to build.
- Bad: wrong or confusing answers after every consolidation of a coordination Mission.
More Information
- Mission discovery map:
kitty-specs/lane-worktree-model-hardening-01M6QY1M/upstream/doctrine-and-write-service-adr-map.md(Part 2, C-3; risk 9). - Current cursor:
src/specify_cli/status/tail_reader.py(TailCursor,ResumeRefused).