pi-daddy 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -12,6 +12,160 @@ the record of how the package got here and are worth keeping; they are not worth
 > the record of how the package arrived at what it does, and because the reasoning behind each one is
 > usually the clearest statement of why the current behaviour is what it is.
 
+## 0.19.0 — workspace routing is a capability (2026-08-23)
+
+**The four hang fixes below were staged for a 0.18.2 and are released here instead — a decision reversed
+deliberately, so the reversal is recorded rather than the reason vanishing.** The paragraph that stood here
+argued for cutting them as a patch so a fix for released code would not be gated on a breaking change. The
+counter-argument won: **R-131 — workspace routing does not attenuate — is a live escalation in published
+0.18.0 and 0.18.1**, a child routed to `staging` can route its grandchild to `prod` with a real lease and a
+ledger line that reads as authorised, and the fix for it *is* the breaking change. A 0.18.2 would have fixed
+one defect and left that one open, on a line that then needed supporting alongside this one. Shipping once
+fixes all three.
+
+- **FIX — a retained lease no longer reports a retention that did not happen (R-152).** `markRetained`
+  returned `void` and `releaseDelegationWorkspace` hardcoded the ledger word, so a `workspace_lease` event
+  said `retained` — *"the pane may still be live"* — for a helper that had already died (the fact is `lost`),
+  for a lease already cleanly released, and for a retention whose record could not be written. It now answers
+  in the release vocabulary and the caller ledgers what it says. **Breaking for direct library callers only:**
+  `WorkspaceLease.markRetained` returns `Promise<LeaseReleaseOutcome>` instead of `Promise<void>`, and
+  `LeaseReleaseOutcome` gained `retained` (so `| "retained"` unions are now redundant, not wrong).
+- **FIX — an impossible `herdr tab close` bound is rejected at both ends, and as a `RangeError` (R-152).**
+  Above `2^31 - 1` the timeout truncates — `Number.MAX_SAFE_INTEGER` becomes 1ms and SIGKILLs every close
+  attempt before herdr can act (measured: callback at 3ms for a 3s sleep) — the mirror of the `0` case, which
+  means no bound at all. Fractional counts were accepted too. **The exception type changed on purpose:** this
+  was a `GovernanceRefusal` carrying `WORKSPACE_LEASE_STALE`, which elsewhere means the lease went stale, so a
+  controller switching on codes would retry a permanent caller bug. Both bounds are now validated for read
+  leases as well, where the check previously sat below an early return and validated nothing.
+- **FIX — a retained writer lease no longer stops its own process from exiting (R-146).** `markRetained`
+  leaves the kernel lock and the pane alone by design; it also left the parent's three pipes to the lock
+  helper referenced, and the helper was never `unref`ed, so node's event loop stayed alive and `pi` could
+  never exit. Measured: `exit=124` (timed out) against `exit=0` for the same sequence ending in `release()`.
+  Reached whenever the herdr executor's `tab close` fails. **Which hosts it wedged:** those that let the loop
+  drain — pi's `-p`/print mode, and library consumers such as an ADR-0034 external controller. Interactive and
+  rpc mode call `process.exit()`, so there the process still left and the on-exit pane sweep still ran.
+  Present in 0.18.0 and 0.18.1. Retention still holds the lock: on the parent's exit the helper makes its
+  bounded close attempts and then releases, so the worktree is recoverable (R-102) rather than stranded.
+- **FIX — one `herdr tab close` attempt is now bounded in wall clock, not only in count (R-146).** The
+  helper's `execFile` had no `timeout`, so a herdr that accepted the close and never answered never called
+  back: the retry budget was unreachable, no marker was written, and the lock was held **forever** — R-102's
+  explicitly rejected outcome. Measured with a `herdr` that sleeps: before, `LOCK=HELD` with no marker
+  indefinitely; after, released with the marker written. Tunable via `herdrCloseTimeoutMs` (default 15s).
+
+
+- Ship a canonical JSON Schema draft 2020-12 contract for `ledgerVersion: 2` plus deterministic fixtures for
+  all four event types, generated through the production builders. Stable package export paths let external
+  harnesses pin the real contract instead of maintaining a parallel format.
+- Add a check-receipt event builder and use it on the production named-check path, so every checked-in fixture
+  is produced by the same builder that emits the corresponding ledger line.
+- Document strict version dispatch: legacy 0.17 grant records have no explicit version; unsupported explicit
+  versions fail closed and are never reinterpreted as legacy.
+
+- **BREAKING — routing a child to a registered workspace now requires `workspace:<id>` in the caller's
+  grant.** Every grant that routes must add it; a delegation naming a workspace the session does not hold
+  is refused `WORKSPACE_NOT_AUTHORIZED`, with the id recorded in `denied` so it counts as an escalation.
+
+  Until now this was the one governance dimension that did **not** attenuate: the registry inherited into
+  every governed child and nothing checked the caller's authority, so a child routed to `staging` could
+  route its grandchild to `prod` — with a real lease, a validated CWD, and a ledger line naming `prod`.
+  Measured in `docs/probes/g36-workspace-attenuation`, decided in ADR-0035, tracked as R-131.
+
+  Failing open for compatibility was considered and rejected: it would have made an attenuation fix opt-in.
+  The migration is one line per grant, and `pi-daddy init` now lists the registered ids commented in
+  `.pi/grants.env` so the edit is visible from the file you already open.
+
+- `PI_GRANTS_GATED=workspace:prod` asks a human before a child is routed there, through ADR-0024's existing
+  mechanism — the id is the caller's authority for that one delegation and never joins the child's grant.
+  `workspace:*` in the gate covers every id.
+- `workspace:*` covers the namespace but is **held, never inherited** — R-26's rule, because a descendant
+  holding it could route anywhere the registry lists. `agent:*` is unchanged and still inherits. Asking to
+  hand `workspace:*` to a child is refused (`NARROWING_VIOLATED`) rather than silently stripped, so the
+  ledger never records authority the child did not receive.
+- `tool:*` still satisfies a workspace capability: governance is opt-in and an ungoverned session must keep
+  routing anywhere.
+- A `workspace:` id never reaches pi's `--tools`. It is enforced by pi-daddy before the spawn, which is a
+  different and weaker class than the `--tools` allowlist; `docs/SPEC.md` now states both classes explicitly.
+- **BREAKING — a registry id must now match `[A-Za-z0-9][A-Za-z0-9._/-]*`.** The registry became an input to
+  the grant grammar when an id became the tail of a capability id, so ids that 0.18.0/0.18.1 accepted are now
+  refused `GRANT_ID_MALFORMED` at load, naming the file and the id. **Slashes and dots are fine** — a worktree
+  named after its branch (`feature/x`) works, and an earlier build of this release wrongly refused it by
+  reusing the tool-name grammar. Refused: whitespace (it splits `allowed-tools`), commas and newlines (they
+  split a grant — 0.18.1's defect), `*` (it collided with `workspace:*`, so registering a worktree as `*` and
+  granting `workspace:*` minted routing over the whole registry), shell metacharacters (they reach the
+  `ROUTABLE WORKSPACES` block of a generated `.pi/grants.env`, which tells you to paste them into your
+  grant), and non-ASCII (the generated file is reviewed in an editor, where control characters and
+  homoglyphs let one id render as another). One bad entry refuses the whole file, so rename before upgrading.
+- **The registry must be a regular file under 1 MiB** — a FIFO there blocked session start indefinitely, and
+  the read is bounded by one handle `fstat`-ed as a descriptor. **Ownership and mode are NOT checked.** An
+  earlier draft of this release added a uid/world-writable guard and this bullet promised it; `e1937cf`
+  removed the code when the change was narrowed to ADR-0035 and left the promise here for a day. Nothing in
+  0.19.0 checks who may write the registry, and a mode check would not reach the attack that matters — a
+  governed child runs as the same uid as its parent. Tracked as R-137.
+- No `workspace:` id is live by default in a generated grant, including one a package's `allowed-tools`
+  declares. Which worktree a child starts in is the operator's decision (ADR-0028).
+
+### Fixed before release — found reviewing this change
+
+The first group never shipped — they were defects in 0.19.0's own development, caught by two review passes
+and a mutation battery, and are listed because ADR-0035 claimed three of them as done (R-133, and that ADR's
+amendment). **The entries under "Present in earlier releases" below DID ship**, and an earlier draft of this section put
+them under this heading, telling operators the `tool:*` attenuation escape could not affect them. (That draft
+then said "two" while three bullets sat under the heading, one of which — the v2 enum — is the single item
+here that provably did *not* ship. It has moved back.)
+
+- **Routing terminated below the root instead of attenuating.** `unknownCapabilities` did not know the
+  namespace, and a catalog is always present in a real session, so every requested `workspace:<id>` was
+  refused as an unknown capability. No child could be granted one, which made the "two authorities" model
+  unreachable. This was the headline defect.
+- The `PI_GRANTS_GATED=workspace:<id>` gate above was claimed and inert.
+- `pi-daddy init` had never heard of the workspace registry.
+- `allowed-tools: workspace:prod` in a `SKILL.md` became `tool:workspace:prod`, which names nothing.
+- `isSafeCapability` rejected the namespace, so the boundary that generates grants could not emit the
+  capability this release makes mandatory.
+- `subsumedBy` reported `workspace:*`-covered ids as subsumed, contradicting its own rule.
+- The v2 ledger contract's `refusalCode` enum is now **generated** from `REFUSAL_CODES` by
+  `scripts/generate-ledger-v2-contract.ts` instead of hand-maintained beside it. `WORKSPACE_NOT_AUTHORIZED`
+  joins the enum in this release; `contracts/ledger/v2/README.md` records why that is a legitimate v2 edit
+  rather than a v3 — v2 has never been published, so nothing can have pinned it. It is **not** the last such
+  edit: every other closed enum in that schema is still hand-maintained beside its source array — `test/ledger-contract.test.ts`
+  asserts each equality, so the same ambush waits for whoever adds an executor kind or a lease outcome. (First
+  written as "five"; the figure is larger and is not worth restating, since the test file is the list.)
+
+### Present in earlier releases — read these before upgrading
+
+**Upgrade if you run governed delegation trees, and read R-135 first.**
+
+- **R-135, and it is not part of this feature.** `tool:*` was reaching delegated children. R-26's rule —
+  a wildcard is held, never inherited — was enforced only in `childEnv`, the interceptor path, while
+  `delegate.ts` (the path that spawns, since 0.7.0 — ADR-0016) applied no filter, and `tool:*` is not universal enough
+  for `assertNarrowing` to stop. A parent holding `tool:*` and delegating `tools: ["tool:*"]` gave its child
+  `tool:*`, so attenuation ended at the root. **Present in every published version.** One shared
+  `inheritableGrant` now serves both paths. If you run governed delegation trees, this is the entry to read.
+
+- **R-134.** Session start no longer warns that a gated `agent:` id "does NOT gate spawning that definition".
+  That was R-47's partial fix in 0.11.1 and false from 0.12.0, when ADR-0024's gate landed. The warning
+  outlived the defect across eight published versions (0.13.0 through 0.18.1), and the integration suite
+  required it to, while advising operators to
+  remove a control that works.
+
+## 0.18.1 — SECURITY: a capability id containing a comma minted authority
+
+**Upgrade if you use `tool:*` or `agent:*` in any grant.** Present in 0.18.0 and every earlier published
+version that has the wildcard prefix rules.
+
+`PI_GRANTS_GRANT` is comma-separated. A capability id containing a comma was admitted by a wildcard's
+**prefix** rule — `agent:x,tool:bash` starts with `agent:`, so a root holding `agent:*` covered it — then
+written verbatim into the child's grant and split by the child into two capabilities. The child received a
+real `tool:bash` from a tree whose root never held it, `denied` was empty, so nothing recorded an
+escalation and the ledger line read as an ordinary authorised delegation.
+
+`tool:*` is affected identically, since it covers every namespace.
+
+Fixed with two guards: a malformed id can no longer be **granted** (it lands in `denied` and is recorded as
+the escalation attempt it is), and neither grant writer will **emit** one. No legitimate id is affected —
+`ext:@scope/pkg/tool`, `skill:my-skill`, `agent:my_agent` and both wildcards are unchanged. Tracked as
+R-132.
+
 ## 0.18.0 — generic runtime enforcement for external controllers
 
 - Optional correlation metadata joins capability decisions to run/task/workspace/context IDs, candidate

package/README.md

@@ -330,6 +330,29 @@ All fields are optional; existing callers behave unchanged.
   Git worktree root, and sets initial CWD. A caller cannot label a write-capable grant read-only. Kernel
   util-linux `flock` allows one **pi-daddy-governed** writer per canonical root; `setpriv --pdeathsig` plus
   helper attachment stops the writer process or herdr tab on parent death before release. This does not confine paths or exclude unrelated writers; `bash` remains an escape.
+
+  **BREAKING in 0.19.0 — routing now requires a capability.** A delegation naming `workspace_id: W` needs
+  `workspace:W` in the caller's grant, or it is refused `WORKSPACE_NOT_AUTHORIZED`. Every grant that routes
+  must add it: `PI_GRANTS_GRANT="tool:read,tool:delegate,workspace:W"`. `pi-daddy init` lists the registered
+  ids commented in `.pi/grants.env`. A child can only route on to ids it was granted itself, so this is also
+  the list of what any descendant could reach; `workspace:*` exists but is held and never inherited, which
+  makes it the wrong answer for anything but a single-worktree setup. `PI_GRANTS_GATED=workspace:W` asks a
+  human first. Enforced by pi-daddy before the spawn, not by pi's `--tools` — see `docs/SPEC.md` on the
+  enforcement classes.
+
+  **BREAKING in 0.19.0 — a registry id must match `[A-Za-z0-9][A-Za-z0-9._/-]*`.** An id is now the tail of a
+  capability id, so it has to survive the grant grammar. **Slashes and dots are fine**, so a worktree named
+  after its branch (`feature/x`) works. Refused, with the file and the id named: whitespace (it splits a
+  definition's `allowed-tools`), commas and newlines (they split a grant), `*` (it collided with
+  `workspace:*`), shell metacharacters (they reach a generated file you are told to paste from), non-ASCII,
+  and `@ + % = ^ ! ? ~ { } [ ]` or a leading `_`, `-` or `.`. **One bad entry refuses the whole registry**, so
+  rename before upgrading. The regex is the specification; that list is a summary.
+
+  **Also new in 0.19.0:** the registry must be a **regular file under 1 MiB**. A FIFO or device there would
+  block session start rather than fail, and the read is bounded so a file that grows after its size is checked
+  is refused rather than allocated. What is *not* checked: ownership, permissions, and whether a descendant
+  holding a write tool repointed an entry — routing attenuates by **id**, not by **destination**
+  (`docs/probes/g37-registry-tamper`, tracked as R-137).
 - Refusals retain current prose and add stable codes such as `CAPABILITY_ESCALATION`,
   `GATED_UNAPPROVED`, `APPROVAL_SCOPE_MISMATCH`, and `WORKSPACE_WRITE_CONFLICT`.
 - Ledger v2 adds joinable capability, lease, lifecycle and check-receipt events while reading legacy lines.
@@ -342,6 +365,23 @@ All fields are optional; existing callers behave unchanged.
 Public subpaths: `pi-daddy/correlation`, `pi-daddy/refusals`, `pi-daddy/workspace`,
 `pi-daddy/check-runner`.
 
+### Canonical ledger v2 contract
+
+Machine consumers should import or resolve
+`pi-daddy/contracts/ledger/v2/ledger-event.schema.json`, not infer a format from examples in prose. This
+unreleased source candidate packages generated fixtures at
+`pi-daddy/contracts/ledger/v2/fixtures/{capability-decision,workspace-lease,child-lifecycle,check-receipt}.json`.
+They are built through the same event builders as production and pin nested correlation, trusted digests,
+approval and refusal facts, and lifecycle nullability.
+
+Dispatch on version before event: no `ledgerVersion`/`event` is a legacy 0.17 grant record; explicit version
+2 must validate as one of the four events; every other explicit version fails closed and must never be read
+as legacy. `verifyLedger` enforces that dispatch boundary and required join fields; full nested validation
+uses the schema. The v2 schema is closed, so a field/event/enum/requiredness or semantic change requires a new
+ledger version and versioned artifact path. The already-published npm 0.18.1 does not contain these files;
+they require the next authorized package release. See `contracts/ledger/v2/README.md` for the field inventory
+and compatibility rules.
+
 ## Running it
 
 ```bash
@@ -683,9 +723,9 @@ every in-repo test passed. `npm run test:smoke` packs a tarball, installs it int
 ## Testing
 
 ```bash
-npm test                   # 587 unit tests. Fast, pure, no pi, no network.
+npm test                   # 633 unit tests. Fast, pure, no pi, no network.
 npm run typecheck          # src + extensions + tests + integration tests
-npm run test:integration   # 44 tests against a REAL pi process. ~55s, no model tokens.
+npm run test:integration   # 45 tests against a REAL pi process. ~55s, no model tokens.
 npm run test:smoke         # pack, install into a scratch project, import and use it — and run the
                            # installed `pi-daddy init` bin, which is how R-73 was found
 PI_GRANTS_IT_MODEL=1 npm run test:integration   # + 10 end-to-end tests with a real model. Costs money.
@@ -713,6 +753,10 @@ its own author the day after it was added: rather than raise the cap, `delegatio
 
 ## Status
 
+**0.18.1 — security fix for malformed capability IDs.** Capability IDs containing comma, CR, LF, NUL or
+surrounding whitespace are refused before resolution and again before grant serialization, preventing a
+wildcard-covered string from splitting into authority the parent never held.
+
 **0.18.0 — generic runtime enforcement, still honest about scope.** The governed spawn path now includes
 optional correlation, exact task-bound approvals, registered-worktree CWD validation, OS-backed governed
 writer leases, structured refusals, lifecycle/lease ledger events, and a no-shell named-check subpath. All

package/contracts/ledger/v2/README.md

@@ -0,0 +1,59 @@
+# pi-daddy ledger contract — version 2
+
+Canonical machine contract for one `ledgerVersion: 2` JSONL line:
+
+- `ledger-event.schema.json` — JSON Schema draft 2020-12 union, closed by event discriminator.
+- `fixtures/*.json` — deterministic examples generated in the repository by
+  `scripts/generate-ledger-v2-contract.ts` through the production builders.
+
+After the package version carrying this unreleased artifact is published, installed consumers can resolve
+`pi-daddy/contracts/ledger/v2/ledger-event.schema.json` and the four fixtures as
+`pi-daddy/contracts/ledger/v2/fixtures/{capability-decision,workspace-lease,child-lifecycle,check-receipt}.json`.
+JSON module imports require the runtime's JSON import attribute; filesystem-based validators can resolve the
+same exported package paths without importing the JSON as code.
+
+## Dispatch and compatibility
+
+1. No `ledgerVersion` and no `event` is a legacy 0.17 `GrantRecord`. It is intentionally not described by
+   the v2 schema; pi-daddy's reader continues accepting it.
+2. `ledgerVersion: 2` requires one of the four exact event discriminators and validation against this schema.
+3. Any other explicit `ledgerVersion`, a missing discriminator, or an unknown discriminator must fail closed.
+   Never reinterpret it as a legacy grant line. pi-daddy's `verifyLedger` enforces that dispatch boundary and
+   required join fields; consumers needing full nested validation use this schema.
+
+The v2 schema is closed (`additionalProperties: false`) so a pinned consumer cannot silently assign meaning
+to a field it does not know. Adding/removing a field, event, enum member, requiredness rule, or changing a
+field's meaning requires a new ledger version and a new versioned path. Correcting prose or adding a fixture
+that does not change accepted records does not.
+
+**The rule above binds from first publication, and v2 was first published in 0.19.0.** It was added to the
+repository during 0.19.0's development and no released version has ever carried it, so nothing can have
+pinned it — which is why `WORKSPACE_NOT_AUTHORIZED` (ADR-0035) could join `refusalCode`'s enum in that same
+release rather than forcing a v3 for one refusal code. Recorded here rather than left to inference, because
+the rule as written forbids exactly that edit and a reader comparing the two would be right to.
+
+This is the only such amendment for `refusalCode`: from 0.19.0 that enum is **generated** from
+`REFUSAL_CODES` by `scripts/generate-ledger-v2-contract.ts`, and `test/ledger-contract.test.ts` holds the two
+equal. So a new refusal code is now a visible, mechanical change to this artifact — which is what makes the
+rule above enforceable instead of aspirational. Before that it was hand-maintained beside the array it had to
+match, and the first code added after publication turned the suite red with no diff from the generator.
+
+## Event field inventory
+
+All v2 events require `ledgerVersion`, `event`, and RFC 3339 `ts`; all carry a joinable `childId` and may
+carry bounded, non-authoritative `correlation` metadata.
+
+- `capability_decision`: parent/child/depth, executor, requested/parent/effective/denied/clipped/gated sets,
+  blocked/reason, trusted task and optional definition digests, approval source/scope/expiry/use facts,
+  optional prior-task author, human/gate outcome, and structured refusal.
+- `workspace_lease`: workspace/root/access, acquisition or release outcome, recovery fact, release reason,
+  and structured refusal.
+- `child_lifecycle`: starting/completed/failed state, executor, nullable exit code and signal, timeout/abort/
+  truncation flags, and reason.
+- `check_receipt`: receipt/workspace/check IDs and candidate tree identity. The full named-check receipt is a
+  separate return artifact; the ledger event is its join record.
+
+Trusted fields (`taskDigest`, `definitionDigest`) are outside `correlation`. Digest-looking correlation
+values remain opaque and non-authoritative. `assurance_scope`, `schema_version`, access classification,
+workspace attenuation, approval freshness, tree identity, lease-directory identity, and runtime-cycle
+limitations remain exactly as documented in `docs/SPEC.md`; this artifact does not repair or hide them.

package/contracts/ledger/v2/fixtures/capability-decision.json

@@ -0,0 +1,95 @@
+{
+  "ledgerVersion": 2,
+  "event": "capability_decision",
+  "ts": "2026-08-20T12:00:01.000Z",
+  "parentId": "d0",
+  "childId": "d0.1",
+  "depth": 1,
+  "agentType": "build",
+  "executor": "process",
+  "taskFrom": "d0.0",
+  "taskDigest": "9999999999999999999999999999999999999999999999999999999999999999",
+  "correlation": {
+    "schema_version": "1.0",
+    "run_id": "run-contract-001",
+    "task_id": "task-contract-001",
+    "workspace_id": "workspace-contract",
+    "context_id": "context-contract",
+    "phase": "verify",
+    "assurance": "critical",
+    "assurance_effective": "critical",
+    "policy_label": "policy-contract",
+    "assurance_source": "policy",
+    "assurance_scope": {
+      "kind": "changed-files",
+      "paths": [
+        "src/**"
+      ],
+      "include_untracked": true
+    },
+    "activated_at": "2026-08-20T12:00:00.000Z",
+    "plan_digest": "1111111111111111111111111111111111111111111111111111111111111111",
+    "definition_digest": "2222222222222222222222222222222222222222222222222222222222222222",
+    "task_digest": "3333333333333333333333333333333333333333333333333333333333333333",
+    "base_sha": "4444444444444444444444444444444444444444",
+    "head_sha": "5555555555555555555555555555555555555555",
+    "tree_sha": "6666666666666666666666666666666666666666",
+    "event_seq": 21,
+    "last_change_seq": 18,
+    "last_authority_seq": 20,
+    "check_receipt_id": "7777777777777777777777777777777777777777777777777777777777777777"
+  },
+  "refusal": {
+    "code": "WORKSPACE_WRITE_CONFLICT",
+    "message": "workspace-contract already has a governed writer",
+    "details": {
+      "workspace_id": "workspace-contract",
+      "retryable": true,
+      "holder_depth": 1
+    }
+  },
+  "requested": [
+    "tool:bash",
+    "tool:read"
+  ],
+  "parentGrant": [
+    "agent:build",
+    "tool:bash",
+    "tool:read"
+  ],
+  "effective": [
+    "tool:bash",
+    "tool:read"
+  ],
+  "denied": [],
+  "clipped": [],
+  "gatedBlocked": [],
+  "blocked": true,
+  "reason": "workspace-contract already has a governed writer",
+  "approved": [
+    "tool:bash",
+    "tool:read"
+  ],
+  "approvalSources": {
+    "tool:bash": "persisted",
+    "tool:read": "prompt"
+  },
+  "approvalScopes": {
+    "tool:bash": "always",
+    "tool:read": "once"
+  },
+  "approvalExpiresAt": {
+    "tool:bash": "2026-09-19T12:00:00.000Z"
+  },
+  "approvalUses": {
+    "tool:read": {
+      "max": 1,
+      "remaining": 0
+    }
+  },
+  "definitionDigest": {
+    "name": "build",
+    "source": "/operator/skills/build/SKILL.md",
+    "sha256": "8888888888888888888888888888888888888888888888888888888888888888"
+  }
+}

package/contracts/ledger/v2/fixtures/check-receipt.json

@@ -0,0 +1,40 @@
+{
+  "ledgerVersion": 2,
+  "event": "check_receipt",
+  "ts": "2026-08-20T12:00:04.000Z",
+  "childId": "check:spec-lint:00000000-0000-4000-8000-000000000000",
+  "receiptId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "workspaceId": "workspace-contract",
+  "checkId": "spec-lint",
+  "treeSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "correlation": {
+    "schema_version": "1.0",
+    "run_id": "run-contract-001",
+    "task_id": "task-contract-001",
+    "workspace_id": "workspace-contract",
+    "context_id": "context-contract",
+    "phase": "verify",
+    "assurance": "critical",
+    "assurance_effective": "critical",
+    "policy_label": "policy-contract",
+    "assurance_source": "policy",
+    "assurance_scope": {
+      "kind": "changed-files",
+      "paths": [
+        "src/**"
+      ],
+      "include_untracked": true
+    },
+    "activated_at": "2026-08-20T12:00:00.000Z",
+    "plan_digest": "1111111111111111111111111111111111111111111111111111111111111111",
+    "definition_digest": "2222222222222222222222222222222222222222222222222222222222222222",
+    "task_digest": "3333333333333333333333333333333333333333333333333333333333333333",
+    "base_sha": "4444444444444444444444444444444444444444",
+    "head_sha": "5555555555555555555555555555555555555555",
+    "tree_sha": "6666666666666666666666666666666666666666",
+    "event_seq": 21,
+    "last_change_seq": 18,
+    "last_authority_seq": 20,
+    "check_receipt_id": "7777777777777777777777777777777777777777777777777777777777777777"
+  }
+}

package/contracts/ledger/v2/fixtures/child-lifecycle.json

@@ -0,0 +1,42 @@
+{
+  "ledgerVersion": 2,
+  "event": "child_lifecycle",
+  "ts": "2026-08-20T12:00:03.000Z",
+  "childId": "d0.1",
+  "state": "failed",
+  "executor": "process",
+  "exitCode": null,
+  "signal": null,
+  "aborted": true,
+  "reason": "child did not start",
+  "correlation": {
+    "schema_version": "1.0",
+    "run_id": "run-contract-001",
+    "task_id": "task-contract-001",
+    "workspace_id": "workspace-contract",
+    "context_id": "context-contract",
+    "phase": "verify",
+    "assurance": "critical",
+    "assurance_effective": "critical",
+    "policy_label": "policy-contract",
+    "assurance_source": "policy",
+    "assurance_scope": {
+      "kind": "changed-files",
+      "paths": [
+        "src/**"
+      ],
+      "include_untracked": true
+    },
+    "activated_at": "2026-08-20T12:00:00.000Z",
+    "plan_digest": "1111111111111111111111111111111111111111111111111111111111111111",
+    "definition_digest": "2222222222222222222222222222222222222222222222222222222222222222",
+    "task_digest": "3333333333333333333333333333333333333333333333333333333333333333",
+    "base_sha": "4444444444444444444444444444444444444444",
+    "head_sha": "5555555555555555555555555555555555555555",
+    "tree_sha": "6666666666666666666666666666666666666666",
+    "event_seq": 21,
+    "last_change_seq": 18,
+    "last_authority_seq": 20,
+    "check_receipt_id": "7777777777777777777777777777777777777777777777777777777777777777"
+  }
+}

package/contracts/ledger/v2/fixtures/workspace-lease.json

@@ -0,0 +1,41 @@
+{
+  "ledgerVersion": 2,
+  "event": "workspace_lease",
+  "ts": "2026-08-20T12:00:02.000Z",
+  "childId": "d0.1",
+  "workspaceId": "workspace-contract",
+  "root": "/worktrees/contract",
+  "access": "write",
+  "outcome": "acquired",
+  "recovered": "unknown",
+  "correlation": {
+    "schema_version": "1.0",
+    "run_id": "run-contract-001",
+    "task_id": "task-contract-001",
+    "workspace_id": "workspace-contract",
+    "context_id": "context-contract",
+    "phase": "verify",
+    "assurance": "critical",
+    "assurance_effective": "critical",
+    "policy_label": "policy-contract",
+    "assurance_source": "policy",
+    "assurance_scope": {
+      "kind": "changed-files",
+      "paths": [
+        "src/**"
+      ],
+      "include_untracked": true
+    },
+    "activated_at": "2026-08-20T12:00:00.000Z",
+    "plan_digest": "1111111111111111111111111111111111111111111111111111111111111111",
+    "definition_digest": "2222222222222222222222222222222222222222222222222222222222222222",
+    "task_digest": "3333333333333333333333333333333333333333333333333333333333333333",
+    "base_sha": "4444444444444444444444444444444444444444",
+    "head_sha": "5555555555555555555555555555555555555555",
+    "tree_sha": "6666666666666666666666666666666666666666",
+    "event_seq": 21,
+    "last_change_seq": 18,
+    "last_authority_seq": 20,
+    "check_receipt_id": "7777777777777777777777777777777777777777777777777777777777777777"
+  }
+}