US-45.1: the change-thread ledger (narrowed; replaces #901)

[mkreyman]

US-45.1 (Epic 45, change threads, #882): the thread ledger, narrowed. Replaces #901.

Why a rewrite, not a round 4

#901 ran three review rounds. Round 3 was the ceiling and still found material defects, and all of them sat in one design choice: deciding who may JUDGE a change (findings, verdicts, the round count) by inferring separation from the calling key. Each round found another way around that inference:

• a released implementer;
• a user key in the implementer's own MCP process;
• a repeated verdict;
• a previous claimant with no checkpoint.

The ledger now owns the record only. Findings, fixes, verdicts and round counting move to US-45.3, where the author is a review dispatch loopctl places for the thread (the story files are rewritten in this PR to match).

What it does

• Tables. thread_checkpoints and thread_entries, RLS enabled, tenant_id never cast.
• Checkpoints.
  • Recorded only for the current claimant under the current claim_epoch with a live lease, through Delivery.Claimant, now shared with Escalations.
  • Liveness is the lease alone, so a claimant that reported done is still the claimant.
  • Keyed by (commit_sha, claim_epoch): a new claim resuming at a recorded commit records it again.
• Replays. A replay is the same write (tree and note included) or 409: checkpoint_conflict or idempotency_key_reused.
• Entries.
  • Callers write message and review_requested only. The judgement kinds are refused 422, naming the review dispatch, and loopctl's own kinds 422.
  • checkpoint_id is an Ecto.UUID: canonicalised, refused at the changeset if malformed, and checked against this story.
  • The loopctl: key prefix is reserved.
• Bodies and notes are bounded by one attribute shared with the OpenAPI spec, secret-scanned (422 secret_blocked) and returned with body_untrusted: true.
• Locking. Writes take the per-story advisory lock, then the story FOR SHARE, then the audit chain, in one transaction. Reads take no row lock.
• Paging. GET pages entries (after_seq, limit, next_after_seq); a parameter outside non-negative int4 is 400.
• Shared definitions. claim_not_live is a fallback clause. ActorLabel and ClaimEpochParam have one definition each, used by the escalation and merge-precondition controllers too.
• MCP. thread_get, thread_checkpoint and thread_entry ship in 2.105.0, with every refusal named, keyHint on every call, and LOOPCTL_API_KEY accepted for reads. The route snapshot is regenerated.

Failure design

• Retries. Both writes are idempotent for the same write and refuse a different one.
• Concurrency.
  • A release waits on FOR SHARE instead of committing between the fence and the insert.
  • A poll never queues a release.
  • The per-story lock is taken before the chain lock, and never after.
• Partitions. A runner that loses its claim can still push, but cannot record a checkpoint.

Checks

• Commit gate green. MCP node suite green, route coverage included.
• Mutations (bin/mutate.sh), 36, all red:
  • Claimant: the claimant, epoch, unclaimed guard, lease use and lease definition.
  • Checkpoints: replay, (sha, epoch) key, note replay, tree conflict, note size, empty note.
  • Entries: secret scan, reserved prefix, caller kind, entry replay, entry idempotency, the Ecto.UUID type, checkpoint-of-story.
  • Audit and read: the chain action, tenant visibility, both paging mutations.
  • HTTP: the exact_role plug, the untrusted marker, the route, the 409 status, the int4 bound, the claim_not_live code.
  • MCP: the default key, the checkpoint key, dispatch, keyHint, the API-key fallback, entry fields.
• Three mutations were fixed before commit:
  • V18's target had been reformatted by mix format, so the mutation was re-pointed.
  • V26 lacked an HTTP test, so an idempotency_key_reused 409 test was added.
  • V03 exposed a logically dead is_nil(agent_id) half in the claimant rule, now removed; the unclaimed guard is mutated instead.
• Not covered by a test: the FOR SHARE lock and the lock-free read, which need concurrent transactions to observe.

Review round 1 (all ten fixed, aaa9023)

• Parents. A checkpoint's parent is the previous checkpoint of the same claim.
• Replay. The recorder's resend is answered before the fence.
• Tenant delete. The entry-to-checkpoint key is NO ACTION instead of RESTRICT, and thread_entries.checkpoint_id is indexed.
• Secrets. Idempotency keys are secret-scanned, and every refusal emits [:loopctl, :threads, :secret_blocked].
• Paging. limit=0 is 400.
• Notes. A whitespace-only note is empty.
• Docs. The moduledoc, the tier comment and the thread_get description are corrected.
• CI Lint. It had failed on the migration's formatting: a worktree under .claude/ makes mix format skip priv/*/migrations. Recorded as KB c46133e5.

Mutations after round 1: 40, all red. Six are new: parent-by-claim, replay-before-fence, replay-author, key secret scan, telemetry and limit=0.

Not covered by a test: the FK mode (a real tenant delete is itself blocked by audit_chain's FK, and the one-statement emulation passed under RESTRICT too, so it was removed as non-discriminating), the index, and the lock behaviour.

Review round 2 (fixed, c5e414d)

Two of these came from round-1 fixes: the unreachable fence-fallback path and the limit wording. That qualifies the PR for round 3.

• Liveness. It is Progress.live_claim? plus the review marker, so an implementer adds nothing after request-review, after reporting, or on a NULL lease once verified.
• Bounds. claim_epoch is bounded to int4, and a map-shaped query parameter is 400.
• Chain. A checkpoint's event records its commit, tree, epoch and seq.
• Checkpoints. The read returns at most the latest page of them, and a commit and its tree must share one object format.
• Docs and MCP. The limit-clamp doc is corrected, and MCP refuses a missing claim_epoch locally.
• Story. US-45.1 AC-3 is updated.
• Not changed: the controller test stays async: false, the repo's documented exception with the same reason StoryEscalationControllerTest gives. Keys resolve on AdminRepo and the story lives on the RLS Repo, so tenant and key are committed rows that a concurrently running module's sweep could delete.

Mutations after round 2: 47, all red. New ones:

• the live-claim use and definition, and the review marker;
• the object format;
• the chain's adopted fields;
• the checkpoint cap;
• the map query parameter;
• the claim_epoch int4 bound;
• the MCP claim_epoch check.

Review round 3, the ceiling (all eight fixed, 86d9d89)

The ceiling allows no round 4. These eight were contained edges and documentation, not a design flaw like #901's, so they were fixed here and each is mutation-tested:

• MCP key. Checkpoints and agent entries go out on the key claim_story claims with.
• claim_not_live. The message no longer advises a renewal that cannot help.
• checkpoints_truncated. The read flags a cut checkpoint list.
• review_requested. It is no longer caller-writable.
• OpenAPI. It carries the claim_epoch maximum and states that bodies and notes are bounded in bytes.
• Lease boundary. live_claim? now agrees with the reclaimer at the exact lease instant.
• Replay. It reads the checkpoint's entry once, and 404s for a deleted story.

Mutations after round 3: 55, all red, including every round-3 mechanism. The probe-row mutation for truncation replaced one that could not observe the change.

Not covered by a test:

• the exact-instant lease boundary, which needs a clock equal to claimed_until to the microsecond;
• the OpenAPI maximum;
• the FK mode, the index and the locks, as before.