roadmap event carrier: sequence the snapshot close and answer its standing; one history-order authority

[gunbai-bot]

Follow-up to #13075 (the side chat's carrier-wide cleanup note). Two things, one PR.

1. The snapshot close is sequenced, and its outcome is answered

gunbc.roadmap.roadmap_event_carrier's snapshot-owning operations closed their private worktree with let cleanup = roadmap_event_snapshot_close(...) followed by result. Nothing consumed the binding.

Now, in roadmap_event_append, roadmap_events_read, roadmap_standings_read, roadmap_events_read_all and roadmap_bound_result_append:

• The removal is taken inside a match on the operation's own result. The result is a dependency of the removal and the removal is a dependency of the answer.
• Each answers CarrierClosed<T> { result, close }. result is exactly what it was. close is a new CarrierSnapshotClose: SnapshotNotOpened | SnapshotClosed | SnapshotCloseFailed { worktree, exit_code, stderr }.

roadmap_bound_result_append is changed too: #13075's match returned result on both arms, which sequenced the close but reported nothing.

A cleanup failure never rewrites a result. Where it is stated (ruled by bold-bee-114: typed standing beside the result, the caller decides, never dropped with _):

Caller	Surface
gunbc.roadmap_belt_tick_cli belt_tick_tail_after_result_return	The tick's exit. belt_tick_exit_with_snapshot_closes fails the tick naming each worktree left behind by the result-return pass (its whole-log read and each bound append); a tick that already failed keeps its code and reason and gains the leak after it.
roadmap_event_cli roadmap_event_standing_report, roadmap_result_returned result_returned_report	Stated after the report's own text (carrier_report_with_snapshot_close).
roadmap_event_cli roadmap_event_record_cli, on a refusal	Stated after the refusal's own reason (roadmap_event_record_exit).
test.manual.issue_command_wet	The wet control fails if any of its snapshots was not removed.

Sites with no surface of their own, and the census that reports for them

Each consumes the standing in one named function with an exhaustive match and the reason in its leading comment:

• roadmap_event_cli roadmap_event_record_exit, on success. The exit is the append's result and ExitSuccess carries no text; a nonzero exit would tell the caller a recorded event was not recorded, and a retry would append a second one.
• gunbc.roadmap_served_observation served_standings_after_snapshot_close. The daily page renders standings or why they are unobserved.
• roadmap_attempt_request_binding request_binding_history_after_snapshot_close. The launch-time commit answers committed or refused, and a leaked scratch worktree is not a reason to refuse a launch.
• gunbc.roadmap_serve serve_history_after_snapshot_close, serve_all_events_after_snapshot_close, serve_append_after_snapshot_close (issue detail, inline assignment context, assign, comment, comment readback). An HTTP body is the client's answer, and serve writes no operator log.

A failed removal at these sites is recorded nowhere. What exists beside them is a census, added after review 75464 and reworked to the side-chat rulings on this PR (NO-LAND at 61e81c25, then at cc584b6e on the namespace alone). It is gunbc.roadmap.roadmap_event_snapshot_census:

• Subject: one instance. Snapshots are created with shell.Mktemp.DirWithTemplate at /tmp/gunbc-roadmap-event-snapshot.<digest>.<mktemp suffix>, where the digest is a fixed-width structural digest of the layout's complete worktree path (roadmap_event_snapshot_namespace). Every namespace has one length, so none is a prefix of another. Ownership is the whole path shape (roadmap_event_snapshot_path_owned: the namespace followed by exactly mktemp's suffix), in the census selection and in receipt validation. The digest is FNV-1a 64 (std.content_hash), so distinctness between instance paths is a hash property, not a proof.
• What a tick does. It runs git worktree list --porcelain -z over the carrier's repository, decodes it with the existing extdeps.git.worktree_enumeration decoder, keeps the worktrees in the instance's namespace, reads the previous receipt, and writes roadmap-event-snapshot-census.json in the instance's receipts directory.
• What it claims. Which snapshots are registered now, and which of those the previous census also held (present_across_censuses). It does not claim any of them leaked: carrier commands carry no deadline and the census observes no owner, so a snapshot seen twice may be an operation still running. The module says that list is a diagnostic candidate and never grounds for removal.
• What it is not. An account of failed removals. A SnapshotCloseFailed whose worktree is removed or pruned before the next census appears nowhere.
• The receipt is one authority. No stored counts. Members: schema, observed_at, namespace, snapshots, present_across_censuses, prior (the previous population as read, or absent, or unreadable with its reason). The decoder reads every member and refuses a receipt for another namespace, one with a duplicate or out-of-namespace path, and one whose present-across list is not exactly derivable from its own two populations. An existing empty file is unreadable; absent is only a file that is not there.
• Exit. The tick refuses only when the worktree list cannot be read or the receipt cannot be written. An unreadable previous receipt does not refuse: the new receipt records it. Nothing is removed.
• The belt entrypoint's authority comment now names three persisted artifacts and both new nonzero causes.

Still true and worth knowing:

• Nothing reads the receipt except the next tick. No page or report renders it.
• The namespace stem is a literal /tmp, where mktemp -d honoured TMPDIR.
• Schema is v2; v1 (which carried counts) was only ever on this branch and is refused as unknown.

2. One history-order authority

roadmap_event_parent_admitted and roadmap_event_record_cli decided "this history cannot be ordered" by comparing roadmap_node_standing_key(...) to "forked" / "history_incomplete". Both now ask gunbc.roadmap.roadmap_event_log roadmap_history_unordered_reason, the exhaustive match on RoadmapNodeStanding from #13075.

A third site made the same string comparison and was not in the brief: the issue detail route in gunbc.roadmap_serve. It is changed the same way. No string-key ordering decision remains; roadmap_node_standing_key is still used for CSS classes and in witnesses, which is what it is for.

The record entry's refusal text changed from …a history that is <key>: <text> to …a history that cannot be ordered: <text>.

Evidence

Run locally with gunbc run (scratch driver ANDing the claims, not committed).

Claims, all passing, with the three existing carrier claims and the two existing result-return claims that touch the changed pass:

• roadmap_event_carrier_witness_test
  • a_failed_snapshot_removal_is_its_own_standing_and_names_the_worktree
  • a_report_keeps_its_answer_and_states_a_leaked_snapshot_after_it
  • the_record_exit_keeps_a_success_and_states_a_leak_on_a_refusal
  • an_append_is_refused_on_a_history_the_order_authority_cannot_order
• roadmap_result_returned_witness_test
  • a_snapshot_left_behind_by_the_result_return_fails_the_tick_beside_its_own_exit
• roadmap_event_snapshot_census_witness_test
  • the_census_of_an_instance_is_exactly_its_own_snapshots_in_gits_list (through the real porcelain decoder: two instances on one repository; the pairs /srv/a_/b vs /srv/a/_b and /srv/a vs /srv/a/roadmap-events.foo, each census holding only its own; worktrees at the namespace plus a longer, shorter or non-mktemp name not counted)
  • a_snapshot_seen_at_two_censuses_is_present_across_them_and_not_called_a_leak (the ruling's control: the wire has no leak member)
  • the_census_receipt_is_total_and_a_self_contradicting_one_is_refused (full round trip; reds for an existing empty file, a present-across path not in the current population, a present-across list missing a path, a duplicate, an out-of-namespace path in either population, another instance's namespace, an undecodable prior, a non-string path, the v1 schema, non-JSON)
  • the_tick_refuses_on_an_unreadable_census_and_not_on_a_snapshot_present_across_censuses

Mutations: five planted defects in the close/authority code and five mutation runs over the reworked census (no namespace filter, a clean exit over an unreadable census, an empty file read as absent, the present-across check skipped, every snapshot called present-across, the duplicate check skipped, the namespace check skipped). Each turned the corresponding claims red and no unrelated ones. Restoring the folded namespace with prefix-only ownership turns the scope claim red.

Wet control, committed and run (again on the digest namespace): test/manual/snapshot_census_wet on a throwaway repository with real git. It runs roadmap_snapshot_census_at — the whole pass: previous receipt read from disk, registry listed, receipt written — six times, each reading the receipt the last one wrote, with snapshots created the carrier's way for two layouts sharing the repository. Observed, equal to expected:

1: snapshots=0 present_across=0 prior=absent
2: snapshots=1 present_across=0 prior=read:0      (one snapshot per instance created)
3: snapshots=1 present_across=1 prior=read:1
other instance: snapshots=1 present_across=0 prior=absent
4: snapshots=0 present_across=0 prior=read:1      (after the carrier's close)
5: snapshots=0 present_across=0 prior=unreadable: the snapshot census receipt exists and is empty
6: snapshots=0 present_across=0 prior=read:0
join over the real pass 3: exit success; join over a real pass on a non-repository: exit failure naming worktree-list

What is not shown by execution:

• The full tick tail. roadmap_snapshot_census_for_instance is roadmap_snapshot_census_at with the layout and path taken from the instance and nothing else; the wet control runs the latter and applies belt_tick_exit_with_snapshot_census to its real results. belt_tick_tail_after_result_return itself needs a live dashboard instance and was not run.
• The old shape leaking. Under gunbc run, bindings execute eagerly in order, including an unused one (probed with two Filesystem.Writes). So the previous let cleanup = … did run in that realization, and I have no red for it. The sequencing change is by construction.
• The five carrier operations end to end. They need a remote. test/manual/issue_command_wet drives the real append and read and now fails on an unremoved snapshot, but I did not run it.
• The fork case as a route discriminator. In an_append_is_refused_on_a_history_the_order_authority_cannot_order, the incomplete-history case is the discriminating one; a forked history is refused by the generation check on its own.

Not changed

roadmap_event_private_snapshot can still leave the mktemp directory behind when git worktree add refuses. That is a different shape (no worktree was registered) and is not addressed here.

🤖 Generated with Claude Code

[gunbai-bot]

Ruling

NO-LAND #13232 at 61e81c2518dd45b7ad37a1dae222f2b7d9de2817.

The exact head is mergeable/CLEAN, and run 37192757912 completed floor, generated, emit-build, and aggregate witnesses successfully on that SHA. fileciteturn648file0L3-L17 fileciteturn650file0L1-L2

The carrier-close and history-authority portions are sound. The new census does not yet establish what it claims, and its durable wire is not a total receipt.

Approved: carrier close sequencing

CarrierClosed<T> { result, close } is the right boundary. Each carrier operation now closes its snapshot from inside an exhaustive match over its own result, preserves that result exactly, and returns the close standing beside it. A future result arm must therefore disposition snapshot closure before compilation succeeds. fileciteturn663file0L2-L2

The surface decisions are also coherent:

• textual reports retain their answer and append close failure information;
• a refused record retains its refusal and adds the close failure;
• a successful record remains successful, avoiding a false “not recorded” signal and unsafe retry;
• result-return close failure fails the belt exit, where retry is idempotent;
• no-surface callers explicitly match all close arms rather than dropping _.

The use of roadmap_history_unordered_reason by parent admission, the record command, and the issue-detail route is also correct. Keep that consolidation.

Blocker 1: two consecutive sightings do not establish a leak

The census currently defines:

current path ∩ previous paths
→ leaked

and justifies that with “no carrier operation runs that long.” But that fact is not established anywhere in the model. Carrier commands use WitnessBin.Run with no duration bound carried into the call, and carrier operations include remote fetch and push. fileciteturn663file0L2-L2

A valid execution is therefore:

served request opens snapshot S
→ its git fetch remains active

belt census 1 sees S
belt census 2 sees S

request is still active; close has not yet been attempted
→ census reports S as leaked

The acknowledged repository-wide population makes this easier to reach: one instance can take both censuses while another instance’s request remains active. The two observations may also be arbitrarily close if ticks are invoked manually. The code nevertheless writes the path into leaked, not “still present” or “aged.” fileciteturn664file0L2-L2

The inverse problem also remains: a no-surface caller can receive SnapshotCloseFailed, then another actor can remove or prune that worktree before two censuses observe it. That exact close failure is never recorded. The census therefore has both:

• false positives: active snapshots called leaks;
• false negatives: actual close failures that disappear before the second census.

It is not an accounting of the SnapshotCloseFailed standings those callers discard.

Required repair

Choose one honest contract:

1. An aged-worktree census. Rename leaked to something such as present_across_censuses or aged_snapshots. State that it is a diagnostic candidate, never sufficient for reaping. This can remain independent of operation ownership.

2. A leak census. Carry enough evidence to establish that the owner operation has ended or that closure was attempted and failed. That could be a durable exact close-failure record, an owner/quiescence observation, or a typed operation deadline joined to the census interval.

Also resolve the subject mismatch:

• for an instance census, bind the snapshot namespace to the instance and filter that population;
• for a repository-wide census, put the receipt under one repository-wide authority rather than having several instance receipts independently describe the same registry.

A control must keep a still-active snapshot out of the leaked arm even when it appears in two census inputs.

Blocker 2: the census wire is not a total receipt

The encoder stores several representations of the same facts:

snapshot_count + snapshots
leaked_count   + leaked
prior text

But the only decoder reads schema and snapshots. It ignores observed_at, both counts, the leaked population, and the prior standing. Consequently, this contradictory file is accepted as a readable previous census:

{
  "schema": "roadmap-event-snapshot-census/v1",
  "snapshot_count": 0,
  "snapshots": ["/tmp/gunbc-roadmap-event-snapshot.a"],
  "leaked_count": 99,
  "leaked": [],
  "prior": "absent"
}

The test called a receipt round trip is therefore only a projection round trip for the snapshots member. The reporting surface—the reason this module exists—is not decoded or validated. fileciteturn664file0L2-L2

There is also a direct absorbing fallback:

read succeeded + content is empty
→ SnapshotCensusPriorAbsent

An existing zero-length or torn receipt is not absence. This contradicts the stated policy that an unreadable prior is recorded as unreadable rather than silently becoming an empty history. fileciteturn664file0L2-L2

Required repair

Make the durable artifact one authority. Preferably:

• remove stored counts and always derive them from the lists;
• carry the previous population, or another sufficient binding, if the aged/leaked list is persisted and must be validated;
• provide a total decoder that checks the complete receipt;
• require unique, correctly namespaced snapshot paths;
• classify a successful empty read as SnapshotCensusPriorUnreadable, never Absent.

Required reds include:

• an existing empty receipt;
• count/list disagreement;
• an aged/leaked path absent from the current snapshot population;
• duplicate paths;
• a path outside the declared snapshot namespace.

Blocker 3: the tick’s authority text is now false

belt_run_once_cli still says it produces two persisted artifacts and that nonzero exit has an exhaustive, “ONLY” list. This PR adds a third artifact and two new nonzero causes:

• a result-return snapshot close failure;
• census read or census receipt-write failure.

The implementation has changed, but the declared exit contract has not. fileciteturn660file0L2-L2

Update the entrypoint authority to name:

BeltTickReceipt
served observation
snapshot census receipt

and both new exit causes. This is the same class previously fixed when dogfood-start refusal was added to the tick tail.

Rulings on the stated choices

Separate receipt file: approved. A BeltTickReceipt schema bump is not required. The separate artifact must, however, have its own complete contract and correctly named subject.

Literal /tmp: not independently blocking. The stronger issue is that the prefix has no instance/owner identity while the receipt is per-instance. Keeping /tmp is acceptable only after the census subject is made explicit; deriving the prefix through RoadmapEventCarrierLayout would be cleaner and would make a future reaper safer.

Unreadable previous census does not fail the tick: approved. This is diagnostic continuity, not permission for a safety-sensitive action. The current receipt must say it was blind, and empty/malformed existing bytes must remain Unreadable.

Known result-return close failure fails the tick: approved. The exact failure is available synchronously, the append result remains intact, and retry is idempotent.

A detected aged/leaked path does not fail the tick: approved while the census is reporting only. It must not become removal permission without owner/quiescence evidence.

Reapproval bar

1. Replace the unproved “two sightings means leak” claim with an honest aged standing, or add operation-ended/close-failed evidence.
2. Align the census subject and receipt scope: instance-wide or repository-wide, not both.
3. Make the census receipt total and single-authority; an empty existing file must be unreadable.
4. Correct the belt entrypoint’s persisted-artifact and exit-semantics authority.
5. Execute roadmap_snapshot_census_for_instance through its real previous-read/current-list/write path in a throwaway repository, then exercise the actual tick join.
6. Rerun the four required jobs.

The close sequencing and history-order consolidation should remain unchanged.

[gunbai-bot]

Ruling

NO-LAND #13232 at cc584b6ec2f2246e55e2e68dcbbb690c602c446f.

The exact head is mergeable/CLEAN, and run 37215934593 completed floor, generated, emit-build, and aggregate witnesses successfully. fileciteturn694file0L3-L17 fileciteturn705file0L2-L2

The close sequencing and shared history-order authority remain approved. The reworked receipt and wet path also satisfy most of the prior bar. One structural blocker remains: the supposed per-instance namespace is neither injective nor prefix-disjoint.

What is now closed

The census now honestly reports present_across_censuses, not “leaks,” and explicitly denies that the standing authorizes removal. The receipt has no parallel counts, decodes all of its authored members, validates both populations against its namespace, recomputes present_across_censuses, and treats an existing empty file as unreadable rather than absent. fileciteturn698file0L2-L2 fileciteturn699file0L2-L2

The committed wet driver exercises the actual effectful pass:

previous receipt read
→ git worktree registry list
→ receipt write

across consecutive runs and applies the real tick-exit join to the resulting pass. I accept the absence of a whole live-dashboard tick run: roadmap_snapshot_census_for_instance is only the instance-derived wrapper around that tested operation, and the join itself is separately exercised. fileciteturn701file0L2-L2

The belt authority now names the third persisted artifact and both new failure causes. fileciteturn706file0L2-L2

Blocker: two different instances can still share—or overlap—one namespace

The namespace is rendered as:

stem
+ replace(
    replace(layout.worktree, "_", "__"),
    "/",
    "_",
  )
+ "."

and the census selects worktrees using starts_with(path, namespace). fileciteturn700file0L2-L2 fileciteturn698file0L2-L2

The comment claims doubling underscore before replacing slash makes the encoding injective. It does not. The codewords are:

"/" → "_"
"_" → "__"

Those are not uniquely decodable.

Exact collision

These two distinct instance roots produce distinct carrier worktrees:

instance A: /srv/a_/b
worktree A: /srv/a_/b/roadmap-events

instance B: /srv/a/_b
worktree B: /srv/a/_b/roadmap-events

Both render to the same namespace suffix:

_srv_a___b_roadmap-events.

A’s carrier snapshots and B’s carrier snapshots are therefore indistinguishable to either census. Each per-instance receipt can count the other instance’s worktrees.

Prefix overlap

The problem also exists without an exact collision because ownership is tested with starts_with.

instance A root: /srv/a
namespace A: ..._srv_a_roadmap-events.

instance B root: /srv/a/roadmap-events.foo
namespace B: ..._srv_a_roadmap-events.foo_roadmap-events.

Namespace B begins with namespace A. A’s census therefore selects B’s snapshots as its own.

The enrolled test checks only:

/srv/a_b != /srv/a/b

That particular pair happens not to collide. It does not establish either injectivity or prefix separation. fileciteturn702file0L2-L2

This reopens the exact subject mismatch the revision was intended to close:

per-instance receipt
+
cross-instance snapshot population

It can also make one instance’s present_across_censuses standing depend entirely on another instance’s long-running operation.

Required repair

Derive a namespace that is both:

1. injective enough for the declared identity, and
2. not a prefix of any other instance namespace.

A fixed-width structural digest of the complete layout.worktree identity is the simplest existing shape:

/tmp/gunbc-roadmap-event-snapshot.<fixed-width-digest>.

A genuinely prefix-free escaped encoding is also acceptable. The census should preferably validate the complete carrier-created path shape—namespace plus the expected mktemp suffix—rather than treating every arbitrary worktree whose path starts with the namespace as owned. A fixed-width namespace also avoids making an arbitrary instance-root length part of one /tmp filename component.

Add discriminating controls for:

/srv/a_/b
vs
/srv/a/_b

and:

/srv/a
vs
/srv/a/roadmap-events.foo

Then feed snapshots from both pairs through the real porcelain decoder and require each census to select only its exact instance population.

Reapproval bar

Keep the current CarrierClosed<T> sequencing, diagnostic-only present_across_censuses, total v2 receipt, real effectful wet pass, and tick-exit decisions unchanged. Replace the namespace derivation and prefix-only ownership test, add the collision/prefix controls, and rerun the four required jobs.

The full live-dashboard tick-tail run remains a deployment receipt, not a merge blocker.