wowbagger 0.1.0-alpha.7 → 0.1.0-alpha.8

package/docs/mutation-contract.md

@@ -1,7 +1,7 @@
 # Local mutation contract
 
-Status: versions 1, 2, and 3 are defined; the pre-alpha standalone
-local-filesystem runtime currently emits version 3.
+Status: versions 1 through 5 are defined; the pre-alpha standalone
+local-filesystem runtime currently emits version 5.
 
 This document defines the machine contract implemented by the local-filesystem
 mutation backend. It supplements [SPEC.md](../SPEC.md) and
@@ -10,7 +10,10 @@ mutation backend. It supplements [SPEC.md](../SPEC.md) and
 
 The executable supports `validate`, `ready`, and the commands below. Clients
 must still call `capabilities` and honor its advertised limits before assuming a
-backend can provide a particular write guarantee.
+backend can provide a particular write guarantee. A non-agent consumer that
+launches this executable directly reads
+[docs/host-contract.md](host-contract.md) for the package seam, the process
+tuple, and the packaged JSON Schemas.
 
 ## Contract versions
 
@@ -159,10 +162,9 @@ and stops. That is the intended outcome, not a regression.
 
 ### Version 4
 
-Version 4 is the version this document defines and the runtime emits. It
-retains every version 3 request, response, state, exit, locking, CAS,
-publication, and recovery rule except for these explicit deltas, which are the
-complete difference against published version 3 (`0.1.0-alpha.6`):
+Version 4 retained every version 3 request, response, state, exit, locking,
+CAS, publication, and recovery rule except for these explicit deltas, which are
+the complete difference against published version 3 (`0.1.0-alpha.6`):
 
 - every core command envelope carries `contract_version: 4`;
 - **the bounded item source.** `MAX_ITEM_SOURCE_BYTES` is 8,388,608 and bounds
@@ -211,6 +213,58 @@ members exactly must negotiate version 3 before reading a date refusal, and a
 consumer that must not have its accepted input narrowed underneath it must
 negotiate version 4 before writing an item.
 
+### Version 5
+
+Version 5 is the version this document defines and the runtime emits. It
+retains every version 4 request, response, state, exit, locking, CAS,
+publication, and recovery rule except for these explicit deltas, which are the
+complete difference against published version 4 (`0.1.0-alpha.7`):
+
+- every core command envelope carries `contract_version: 5`;
+- **the bounded list operation.** `list` is a new read-only core command
+  (section 5.1). It enumerates a validated ledger as bounded item summaries
+  under closed filters, one selected sort field, and cursor pagination. It adds
+  the refusals `list-snapshot-changed` (exit 4) and `list-response-too-large`
+  (exit 2);
+- **the advertised list bounds.** `result.operations.list` and four new
+  `result.limits` members carry the list contract's exact numbers (section 4).
+  A version 4 consumer that validated `result.operations` or `result.limits` by
+  exact members refuses the new members, which is the same fail-closed outcome
+  the version field already produces;
+- **the bounded workbench projection.** `inspect` accepts the opt-in flag pair
+  `--workbench --as-of YYYY-MM-DD` and answers with a bounded per-item lifecycle
+  affordance projection under `result.workbench` (section 5.2). It adds the
+  refusal `workbench-response-too-large` (exit 2) and the advertisement
+  `result.operations.inspect.workbench` with three new `result.limits` members
+  (section 4). An `inspect` invocation without `--workbench` keeps its exact
+  result members and its exact bytes; and
+- **named custom report views.** `report` accepts an optional `--view <name>`
+  against report configuration `report_version: 2`, adds `result.view` to a
+  named success, adds the refusal `report-view-not-found` (exit 2), and is
+  advertised at `result.operations.report` (section 4). An invocation without
+  `--view` keeps its exact result members and its exact bytes under either
+  configuration version.
+
+Nothing else moves. `validate` and `ready` carry no version member and their
+bytes are unchanged. `create`, `transition`, `patch`, `mint-id`, and
+`capabilities` change only in the `contract_version` number, and an `inspect`
+invocation without `--workbench` changes only in that number too: no root
+member, result member, issue member, error code, or exit meaning of an existing
+invocation changes.
+
+A version 4 consumer fails closed against a version 5 core the same way: it
+reads `contract_version: 5` from `capabilities --json`, does not recognize it,
+and stops.
+
+The bootstrap wire, adapter approval, instruction, handoff, and fixture-format
+versions are separate version domains and remain version 1. The adapter
+contract remains version 2 and the work-claim API remains version 2. The list
+query and the workbench projection each have their own version domain,
+`query_version` and `projection_version`, both `1`: a consumer negotiates them
+through `result.operations.list.query_version` and
+`result.operations.inspect.workbench.projection_version`, not through the core
+contract version.
+
 ## 1. Scope
 
 The contract keeps four concerns separate:
@@ -263,6 +317,8 @@ The local commands are:
 ~~~text
 wowbagger capabilities --json
 wowbagger inspect --ledger <dir> --id <id> --json
+wowbagger inspect --ledger <dir> --id <id> --workbench --as-of YYYY-MM-DD --json
+wowbagger list --ledger <dir> --input <json-file|-> --json
 wowbagger create --ledger <dir> --input <json-file|-> --json [--auto-commit]
 wowbagger transition --ledger <dir> --input <json-file|-> --json [--auto-commit]
 wowbagger patch --ledger <dir> --input <json-file|-> --json [--auto-commit]
@@ -312,7 +368,7 @@ answer in two domains.
 
 | Domain | Root `namespace` | `contract_version` | Version to negotiate |
 |---|---|---|---|
-| core | absent | 4 | top-level `contract_version` of `capabilities --json` |
+| core | absent | 5 | top-level `contract_version` of `capabilities --json` |
 | work-claim | `work-claim` | 1, the legacy envelope marker | `result.operations.work_claim.api_version` of `claim capabilities --json` |
 | ledger-publication | `ledger-publication` | 1, the legacy envelope marker | the same work-claim `api_version` |
 | ledger-mutation | `ledger-mutation` | 1, the legacy envelope marker | the same work-claim `api_version` |
@@ -339,14 +395,20 @@ legacy claim-envelope marker, and a consumer must never compare it with the core
 | `ready` | bare result `{as_of, valid, ready}` | bare result `{valid, errors}` on an invalid ledger, exit 1 |
 | `capabilities` | core | core |
 | `inspect` | core | core |
+| `list` | core | core |
 | `mint-id` | core | core |
 | `report` | core | core |
 | `create` | core | core, or ledger-mutation when the claim fence refuses |
 | `transition` | core | core, or ledger-mutation when the claim fence refuses |
+| `parent-migrate` | core | core, or ledger-mutation when the claim fence refuses |
+| `snooze` | core | core, or ledger-mutation when the claim fence refuses |
 | `patch` | core | core, or ledger-mutation when the claim fence refuses |
+| `extensions-provision` | core | core |
 | `provision` | work-claim | work-claim |
 | `claim capabilities/read/acquire/renew/release` | work-claim | work-claim |
 | `claim-verify` | work-claim | work-claim |
+| `claim-merge-verify` | work-claim | work-claim |
+| `claim-sync` | work-claim | work-claim |
 | `claim-adopt` | work-claim | work-claim |
 | `mutation-finalize` | work-claim | work-claim |
 | `claim verify` | ledger-publication, `command: "read"` | ledger-publication |
@@ -359,6 +421,14 @@ A core response has exactly `ok`, `command`, `contract_version`, and one of
 claim-domain response has exactly `ok`, `namespace`, `command`,
 `contract_version`, `state`, and one of `result` or `error`; a `claim
 capabilities` response omits `state`, and a claimed-publication response adds
+
+Successful mutation responses may carry `result.changed_paths`. It is the
+complete deterministic ledger-relative set whose bytes this invocation changed
+in the working tree. It does not mean Git committed those paths. `create`
+returns only its item path; `transition`, `patch`, and `publish-claimed` return
+their item path plus the tracked reconciliation log when that log changed.
+`--auto-commit` additionally returns `commit_paths` and `git_commit`; its
+`changed_paths` equals the committed set.
 `operation_id` once schema validation has accepted it. No expected envelope has
 undocumented root members.
 
@@ -468,9 +538,10 @@ presence is reported separately as bounded recovery_artifacts.
 | Exit | Condition | Error codes |
 |---:|---|---|
 | 0 | Successful command; a mutation is state committed. | none |
-| 2 | Argument, request, lookup, or candidate/lifecycle/layout-precondition failure. | invalid-request, item-not-found, transition-precondition-failed, patch-precondition-failed, candidate-invalid, item-source-too-large, items-directory-unavailable |
-| 3 | The complete configured ledger is invalid. | ledger-invalid |
-| 4 | Cooperative comparison, lock, identity, or default-path conflict. | revision-conflict, lock-held, id-collision, path-collision, auto-commit-preflight-failed, mutation-finalize-refused |
+| 1 | A bare-result command found the ledger invalid, or `report` failed before or during publication. `report` answers an invalid ledger here rather than at exit 3. | bare result `{valid, errors}`, ledger-invalid (`report` only), report-read-failed, report-write-failed |
+| 2 | Argument, request, lookup, or candidate/lifecycle/layout-precondition failure. | invalid-request, item-not-found, transition-precondition-failed, patch-precondition-failed, candidate-invalid, item-source-too-large, items-directory-unavailable, list-response-too-large, report-config-invalid, report-view-not-found |
+| 3 | The complete configured ledger is invalid, for every command except `report`. | ledger-invalid |
+| 4 | Cooperative comparison, lock, identity, or default-path conflict. | revision-conflict, lock-held, id-collision, path-collision, auto-commit-preflight-failed, mutation-finalize-refused, list-snapshot-changed |
 | 5 | The backend lacks the required capability or write scope. | atomic-scope-required, capability-unavailable |
 | 6 | An unexpected operating or post-publication recovery condition. | operation-failed, post-commit-recovery-required, write-outcome-unknown, git-commit-failed, git-commit-outcome-unknown, post-commit-reconciliation-failed |
 
@@ -596,21 +667,95 @@ members above. This is the one input to `capabilities`, so the response is
 deterministic for a given working directory but not fixed across working
 directories.
 
-### Contract version 4 capability delta
+### Contract version 5 capability delta
 
 The preceding JSON and three-member Git-dependent coupling remain the exact
-version 1 definition. Versions 2, 3, and 4 change only the following capability
-paths; all omitted paths retain their version 1 values:
+version 1 definition. Versions 2, 3, 4, and 5 change only the following
+capability paths; all omitted paths retain their version 1 values:
 
-| Path | Version 4 value |
+| Path | Version 5 value |
 |---|---|
-| `contract_version` | `4` |
+| `contract_version` | `5` |
 | `result.backend.coordination_scope` | `"same-working-copy-cooperative-writers"` |
+| `result.operations.inspect.workbench` | `{"supported":true,"projection_version":1}` |
+| `result.operations.list` | `{"supported":true,"write_scope":"none","cas_scope":"none","query_version":1}` |
 | `result.operations.patch` | `{"supported":true,"write_scope":"single-item","cas_scope":"exact-byte-sha256"}` |
+| `result.operations.report` | `{"supported":true,"write_scope":"derived-output","config_versions":[1,2],"named_views":true}` |
 | `result.operations.work_claim.api_version` | `2` |
 | `result.limits.max_item_source_bytes` | `8388608` |
+| `result.limits.default_list_page_size` | `50` |
+| `result.limits.max_list_page_size` | `200` |
+| `result.limits.max_list_title_characters` | `120` |
+| `result.limits.max_list_response_bytes` | `131072` |
+| `result.limits.max_workbench_title_characters` | `120` |
+| `result.limits.max_workbench_collection_entries` | `50` |
+| `result.limits.max_workbench_response_bytes` | `65536` |
 | `result.limits.cross_worktree_coordination` | `false` |
 
+`result.operations` advertises in the fixed order `inspect`, `list`, `create`,
+`transition`, `patch`, `report`, `work_claim`. `result.limits` advertises
+`max_item_source_bytes` first, then the four list bounds in the order above,
+then the three workbench bounds, then the version 1 booleans. `list` is
+read-only, so its `write_scope` and `cas_scope` are `none`, exactly like
+`inspect`. `inspect` keeps its version 1 members and gains the nested
+`workbench` member, which is how a consumer learns the opt-in affordance
+projection of section 5.2 exists and which projection shape it will receive.
+
+The four list bounds are exact numbers, not advice:
+
+- `default_list_page_size` is the page size a query that omits `page_size` receives;
+- `max_list_page_size` is the largest `page_size` a query may request;
+- `max_list_title_characters` is the exact number of Unicode code points a row's
+  projected title may carry before it is truncated and flagged; and
+- `max_list_response_bytes` bounds the complete `list` response, envelope and
+  trailing LF included.
+
+A full page of maximum-width rows can exceed `max_list_response_bytes`. When it
+does, the command refuses the page whole with `list-response-too-large` and the
+caller lowers `page_size`; neither bound silently rewrites the other, and a
+`list` response is never a partial page. A consumer with its own transport
+budget uses the lower of that budget and `max_list_response_bytes`.
+
+The three workbench bounds are exact numbers on the same terms:
+
+- `max_workbench_title_characters` is the exact number of Unicode code points
+  the projected item title may carry before it is truncated and flagged;
+- `max_workbench_collection_entries` is the largest number of entries any one
+  variable-size workbench collection carries — the relation lists, an option's
+  precondition issues, an option's blockers, and the related IDs inside one
+  issue. A longer collection carries its first entries, its observed `total`,
+  and `truncated: true`; and
+- `max_workbench_response_bytes` bounds the complete workbench response,
+  envelope and trailing LF included.
+
+The entry bound keeps every projection this core can build well inside the
+response bound, so `max_workbench_response_bytes` is a promise rather than a
+knob: a workbench request carries no size to lower. A projection that would
+exceed it is refused whole with `workbench-response-too-large` at exit 2 rather
+than written short.
+
+`result.operations.report` is how a consumer learns what the read-only report
+command accepts, so it never has to probe by generating an artifact.
+`write_scope: "derived-output"` states that the command writes one configured
+output path and no ledger item. `config_versions` lists the accepted
+`<ledger>/.wowbagger/report.json` versions: version 1 is unchanged, and
+`report_version: 2` adds a `views` object whose named members — for example
+`security-blockers` — each project the validated ledger through grouped filters
+with **OR within one filter group; AND across groups**. `named_views: true` says
+the core accepts a selection by name:
+
+~~~text
+wowbagger report --ledger <dir> --view <name> --as-of YYYY-MM-DD --json
+~~~
+
+A named success adds `result.view` and nothing else; a base report's result is
+unchanged. A selection that names no configured view, or any `--view` against a
+version 1 configuration, is refused with `report-view-not-found` at exit 2,
+`details.view` naming the requested name, and every existing output left as it
+was. The report request, the configuration, and the generated artifact are
+defined in [the README](../README.md#named-custom-report-views); this contract
+defines the advertisement.
+
 `result.limits.max_item_source_bytes` is the first member of `result.limits`,
 before `multi_item_atomicity`. It is the exact number of bytes the complete
 serialized item source may occupy, and it applies to successor bytes accepted
@@ -706,7 +851,7 @@ core contains only fields defined by supported item schema versions:
 - schema_version, id, title, kind, status, created, updated;
 - provenance.source and provenance.recorded_at;
 - depends_on and related;
-- optional parent, snoozed_until, completed, killed, archived;
+- optional parent, snoozed_until, completed, killed, archived, deferred;
 - optional number, the core-assigned item identity on schema version 2, and
   optional priority, the caller-supplied schema priority; and
 - decisions with only their defined action, date, summary, rationale, and
@@ -755,6 +900,332 @@ An operator repairing an invalid ledger reads the bytes and revision of the
 items around the fault with `inspect`, and reads the fault itself from
 `validation_errors`, whose `expected_path` and `remediation` name the repair.
 
+### 5.1 The bounded list query
+
+`list` enumerates a validated ledger. It is read-only, takes no lock, and
+returns no item source and no body: a caller selects a row, then reads that one
+item with `inspect`. `--ledger` is required; `list` performs no ledger discovery
+and binds no implicit path.
+
+`list` loads and validates the complete ledger before it projects anything. An
+invalid ledger returns `ledger-invalid`, exit 3, with `details.validation_errors`
+and no rows: there is no partial list.
+
+#### The query
+
+The request is UTF-8 JSON with one top-level object and exactly these members:
+
+| Member | Required | Value |
+|---|---|---|
+| `query_version` | yes | `1` |
+| `as_of` | yes | ISO calendar date; readiness is projected as of this date |
+| `sort` | yes | object with exactly `field` and `direction` |
+| `filters` | no | object with a subset of the closed filter members below |
+| `page_size` | no | integer from 1 to `max_list_page_size`; default `default_list_page_size` |
+| `cursor` | no | an opaque cursor from a previous `list` response |
+
+`sort.field` is one of `created`, `id`, `number`, `priority`, `status`, `title`,
+`updated`. `sort.direction` is `ascending` or `descending`.
+
+`filters` members are:
+
+| Filter | Value | Meaning |
+|---|---|---|
+| `status` | non-empty array of distinct statuses | row status is in the set |
+| `kind` | non-empty array of distinct kinds | row kind is in the set |
+| `ready` | boolean | row readiness as of `as_of` equals the value |
+| `number` | non-empty array of distinct positive integers | row number is in the set |
+| `title_contains` | non-empty string | the stored title contains it |
+
+Filters are a conjunction: every named filter must accept the item. A value
+filter is a set, so an empty array or a repeated entry is `invalid-request`
+rather than a silently widened or deduplicated query. `title_contains` is a
+case-sensitive substring test against the whole stored title, not against the
+bounded excerpt a row carries; there is no locale collation, case folding, or
+Unicode normalization.
+
+Unknown, missing, and mistyped members are `invalid-request`, exit 2, with the
+aggregated issues of section 3. A JSON number is an integer only when its
+literal is canonical, so `page_size: 1.0` is `invalid-value`.
+
+#### Order
+
+The selected field decides the primary order. An item that does not carry the
+selected member sorts after every item that does in `ascending` order;
+`descending` is the exact reverse of the ascending primary comparison. Every
+order then breaks ties on ascending immutable ID, in both directions, so the
+total order is stable across invocations and a full traversal never depends on
+file order.
+
+#### The response
+
+~~~json
+{
+  "ok": true,
+  "command": "list",
+  "contract_version": 5,
+  "result": {
+    "query_version": 1,
+    "as_of": "2026-08-21",
+    "snapshot": { "revision": "sha256:…", "item_count": 5 },
+    "page": {
+      "size": 2,
+      "offset": 0,
+      "returned": 2,
+      "matched": 5,
+      "has_more": true,
+      "next_cursor": "…"
+    },
+    "items": []
+  }
+}
+~~~
+
+`snapshot.revision` is the ledger-snapshot witness: a digest over every item's
+ledger-relative path and exact item revision, so any item added, removed,
+renamed, or byte-modified changes it. `snapshot.item_count` counts the whole
+validated ledger, not the filtered page.
+
+`page.matched` counts every row the filters accept in that snapshot.
+`page.next_cursor` is a string when `has_more` is `true` and `null` otherwise.
+
+Each row has exactly:
+
+| Member | Presence | Value |
+|---|---|---|
+| `id` | always | immutable item ID; the only identity |
+| `number` | when the item carries one | the short handle, never identity |
+| `title` | always | the title, truncated to `max_list_title_characters` code points |
+| `title_truncated` | always | `true` when the projection dropped code points |
+| `kind` | always | `task` or `epic` |
+| `status` | always | the item status |
+| `priority` | when the item carries one | the supplied priority, never recomputed |
+| `created` | always | ISO calendar date |
+| `updated` | always | ISO calendar date |
+| `revision` | always | the exact item revision, as `inspect` reports it |
+| `ready` | always | readiness as of `as_of` |
+
+#### Cursor pagination
+
+A cursor is opaque and carries no ledger content. It binds three things: the
+digest of the query it was issued for, the snapshot revision it was issued
+against, and the offset to resume at. A caller passes it back unchanged with the
+same query.
+
+A string that is not a cursor this core issued is `invalid-request`, exit 2, at
+`/cursor`. It is never treated as a restart from offset zero.
+
+When either binding no longer holds, the cursor is refused with
+`list-snapshot-changed`, exit 4:
+
+~~~json
+{
+  "ok": false,
+  "command": "list",
+  "contract_version": 5,
+  "error": {
+    "code": "list-snapshot-changed",
+    "message": "The ledger snapshot the cursor was issued against is no longer current.",
+    "details": {
+      "mismatch": "snapshot",
+      "cursor_snapshot_revision": "sha256:…",
+      "current_snapshot_revision": "sha256:…"
+    }
+  }
+}
+~~~
+
+`details.mismatch` is `snapshot` when the ledger changed and `query` when the
+same cursor was replayed under a different `as_of`, `filters`, or `sort`. Both
+carry one remedy: restart pagination with no cursor. A caller MUST NOT combine
+pages from different snapshot revisions; across one unchanged traversal every
+matching item appears exactly once.
+
+The response is a live projection on every invocation. A consumer may cache it
+as transient interface state only; it never becomes a second ledger store.
+
+#### Exit and error summary
+
+| Exit | Code | Condition |
+|---:|---|---|
+| 0 | none | the page was projected and fits the response bound |
+| 2 | `invalid-request` | arguments, JSON, query schema, or cursor form |
+| 2 | `list-response-too-large` | the exact rows exceed `max_list_response_bytes` |
+| 3 | `ledger-invalid` | the complete configured ledger is invalid |
+| 4 | `list-snapshot-changed` | the cursor's snapshot or query binding moved |
+
+### 5.2 The bounded workbench projection
+
+A workbench shows a person which native lifecycle transitions an item can take
+before it asks for consent. `inspect` answers that read opt-in:
+
+~~~text
+wowbagger inspect --ledger <dir> (--id <id> | --number <n>) --workbench --as-of YYYY-MM-DD --json
+~~~
+
+`--workbench` requires `--as-of`, and `--as-of` is accepted only with
+`--workbench`: the projection reports readiness for an explicit date, so the
+date is part of the request rather than a default this core invents. An
+unpaired flag is an `invalid-request` issue at `/arguments`
+(`missing-argument` for the missing `--as-of`, `conflicting-argument` for the
+unpaired `--as-of`), and a date that is not an ISO calendar date is
+`invalid-value`. An invocation without `--workbench` is byte-identical to the
+lossless read of section 5: the two reads share one item resolution, and only
+the flagged one answers with a projection.
+
+The read changes no ledger item, lock, claim journal, reconciliation log, or Git
+state. It takes no lock: a lock would make a read look like a lease.
+
+`inspect --workbench` loads and validates the complete ledger and answers from
+that one snapshot. An invalid ledger returns `ledger-invalid`, exit 3, with
+`details.validation_errors` and nothing else. The lossless read attaches the
+resolved item to that refusal so an operator can read the bytes to repair; the
+workbench read cannot, because an affordance derived from a ledger this core has
+not judged would be a claim it cannot support. An unresolved selector is
+`item-not-found`, exit 2, with exactly the selector the caller used, as in
+section 5.
+
+#### The response
+
+~~~json
+{
+  "ok": true,
+  "command": "inspect",
+  "contract_version": 5,
+  "result": {
+    "workbench": {
+      "projection_version": 1,
+      "as_of": "2026-08-22",
+      "snapshot": { "revision": "sha256:<hex>", "item_count": 5 },
+      "observation": {
+        "authority": "observed-snapshot",
+        "rechecked_by": [
+          "revision", "lock", "claim-fence", "reconciliation", "candidate-validation"
+        ]
+      },
+      "item": {
+        "id": "wb_...",
+        "number": 10,
+        "title": "Epic awaiting disposition",
+        "title_truncated": false,
+        "kind": "epic",
+        "status": "backlog",
+        "priority": 1,
+        "parent": "wb_...",
+        "created": "2026-08-02",
+        "updated": "2026-08-05",
+        "revision": "sha256:<hex>",
+        "ready": false,
+        "depends_on": { "entries": ["wb_..."], "total": 1, "truncated": false },
+        "related": { "entries": [], "total": 0, "truncated": false }
+      },
+      "transition_options": [
+        {
+          "to_status": "done",
+          "action": "complete",
+          "decision_required": true,
+          "minimum_date": "2026-08-05",
+          "enabled": false,
+          "precondition_issues": {
+            "entries": [
+              {
+                "code": "live-dependencies",
+                "field": "depends_on",
+                "message": "Completion requires every depends_on target to be done.",
+                "related_ids": { "entries": ["wb_..."], "total": 1, "truncated": false }
+              }
+            ],
+            "total": 1,
+            "truncated": false
+          },
+          "blockers": { "entries": [], "total": 0, "truncated": false }
+        }
+      ]
+    }
+  }
+}
+~~~
+
+`result` carries exactly one member, `workbench`, and its members are in the
+order above. The projection is negotiated by `projection_version`, its own
+version domain, exactly as `list` is negotiated by `query_version`.
+
+`snapshot` is the same witness `list` returns: it covers every item's
+ledger-relative path and exact revision, so any item added, removed, renamed, or
+byte-modified changes it. It is in the response because an option's blockers and
+precondition issues are functions of the whole ledger, not of the one item, so
+the item revision alone would not name what was observed.
+
+`item` is a bounded summary: `number`, `priority`, and `parent` are present only
+when the item carries them, `title` is projected to
+`max_workbench_title_characters` with `title_truncated` saying whether it was
+cut, `depends_on` and `related` are bounded collections, and `ready` is the
+section 5.1 readiness state for `as_of`. The projection carries no item source
+and no body: those are the lossless read of section 5, and this response stays
+inside an advertised bound.
+
+`revision` is the exact revision of the item's own bytes, and it is what a caller
+sends as `transition`'s `expected_revision`.
+
+#### Transition options
+
+`transition_options` holds one option for every lifecycle target the section 8
+edge table allows out of this item's kind and status, in ascending status order.
+A target the table does not allow is absent, so `invalid-edge` never appears in a
+projected issue. A terminal item has no allowed target and its
+`transition_options` is `[]`.
+
+| Member | Meaning |
+|---|---|
+| `to_status` | the target status a `transition` request would name |
+| `action` | the generated decision action, or `null` for the two no-decision edges |
+| `decision_required` | whether the request must carry `decision.summary` and `decision.rationale` |
+| `minimum_date` | the earliest legal transition date, `max(created, updated)` |
+| `enabled` | whether the observed ledger refuses nothing for this target at `minimum_date` |
+| `precondition_issues` | the observed section 8 precondition issues, bounded |
+| `blockers` | the observed section 8 multi-item blockers, bounded |
+
+An option is evaluated at `minimum_date`, so neither date precondition can be
+what disables it: a caller reads `minimum_date` and sends that date or a later
+one. Issues and blockers use exactly the `transition` vocabulary — the same
+`code`, `field`, `message`, `item_id`, and ordering — so a consumer renders one
+set of refusal reasons. The one reshaped member is an issue's `related_ids`,
+which is a bounded collection here because that list grows with the ledger.
+
+`enabled` is `true` exactly when both bounded collections observed nothing:
+`precondition_issues.total` and `blockers.total` are `0`. A disabled option still
+names why, so a workbench can show a target and the reason it cannot be taken
+rather than hiding it.
+
+#### What the projection does not promise
+
+`observation` states the semantics in the response rather than leaving them to a
+reader of this contract. `authority: "observed-snapshot"` says the projection is
+one observation of the named snapshot: it is not a lease, not a reservation, and
+not a promise that the option remains executable after the returned revision.
+`rechecked_by` names what a later `transition` rechecks under lock — the exact
+revision, the cooperative lock, the claim fence, reconciliation, and complete
+candidate validation — in the refusal precedence of section 8. A transition
+dispatched against a returned option can still be refused by any of them, and
+that refusal is the authority.
+
+The affordance projection and `transition` share one implementation-level
+lifecycle definition (`src/lifecycle.js`): the edge table, the generated actions,
+the precondition issues, and the blockers have exactly one home, so an
+advertised option cannot drift from what the mutation does. A consumer therefore
+never reimplements the edge table, the date derivation, the decision
+requirement, or the blocker rules.
+
+#### Exit and error summary
+
+| Exit | Code | Condition |
+|---:|---|---|
+| 0 | none | the projection was answered and fits the response bound |
+| 2 | `invalid-request` | arguments, including the `--workbench`/`--as-of` pairing |
+| 2 | `item-not-found` | the selector resolved no item in a valid ledger |
+| 2 | `workbench-response-too-large` | the exact projection exceeds `max_workbench_response_bytes` |
+| 3 | `ledger-invalid` | the complete configured ledger is invalid |
+
 ## 6. Cooperative lock and snapshot protocol
 
 Per-ID locks live at:
@@ -1812,6 +2283,9 @@ patch.
 | patch-precondition-failed | id, issues |
 | candidate-invalid | id, validation_errors |
 | item-source-too-large | id, size_bytes, limit_bytes |
+| list-response-too-large | max_list_response_bytes, response_bytes, page_size |
+| list-snapshot-changed | mismatch, cursor_snapshot_revision, current_snapshot_revision |
+| workbench-response-too-large | id, max_workbench_response_bytes, response_bytes |
 | revision-conflict | id, expected_revision, actual_revision |
 | lock-held | id, lock_path, owner, owner_diagnostic |
 | id-collision | id, path, actual_revision |
@@ -1923,6 +2397,58 @@ A cleanup failure reports the remaining bounded artifacts. Locks are never
 auto-broken by age. Clients must inspect after committed-recovery or unknown
 outcomes and must not retry blindly.
 
+### Response loss and once-only dispatch
+
+A caller can lose the response to a mutation it already dispatched: the
+transport between the caller and the owning host can drop after the core
+started, and a dropped transport observes nothing about the ledger. This
+section is normative for every explicit user-triggered `create`, `transition`,
+and `patch`.
+
+Only a complete observed process result establishes an outcome. A result is
+complete when the process is observed to have exited, both captured streams are
+complete and within their bounds, and standard output is one valid envelope for
+the dispatched command. Anything else establishes nothing about the ledger.
+
+| Observation | Established outcome | Required client action |
+|---|---|---|
+| Complete envelope, exit 0, state committed | The mutation applied exactly as returned. | Continue. |
+| Complete envelope, state unchanged, any nonzero exit | The mutation did not create, remove, rename, or byte-modify an item. | Read the refusal; a revision conflict re-inspects. |
+| Complete envelope, exit 6 post-commit-recovery-required, state committed | The item is published; a verify or cleanup step still needs recovery. | Inspect the item and clear the reported recovery artifacts. Never repeat the mutation. |
+| Complete envelope, exit 6 write-outcome-unknown, state unknown | Publication was attempted and the visible bytes are indeterminate. | Validate, inspect, and compare the caller-known revision. Never repeat the mutation. |
+| Signal, timeout, orphan or containment doubt, or an incomplete or over-limit stream | Nothing. The mutation may or may not have applied. | Treat as unresolved. |
+| No envelope, a partial envelope, or no response at all because the transport was lost | Nothing. | Treat as unresolved. |
+
+No row reports success that was not observed, and no row licenses a repeat of
+the mutation.
+
+An unresolved outcome is answered by one sequence, never by a retry:
+
+1. Dispatch once, never replay, invalidate the inspected revision, reconnect,
+   then re-read the ledger.
+2. Re-read means `validate`, then `inspect` the caller-known ID. For `create`
+   the caller already knows the ID it minted; for `transition` and `patch` the
+   caller already knows the expected revision it sent.
+3. Compare the observed current state with the caller's own pre-dispatch
+   observation, and report the comparison as current state. A later item state
+   describes only current ledger state; it never proves that the lost dispatch
+   caused it.
+4. Dispatch a fresh mutation only after a person reviews that comparison, and
+   only as a new explicit decision built on the current revision.
+
+Exit 4 is not response loss. A `revision-conflict` is a complete observed
+refusal with state unchanged: the item changed after it was inspected, and the
+core proves the write did not run. It invalidates the inspected revision and
+requires re-inspection; it never becomes an unresolved outcome and never
+triggers a retry of the same request bytes.
+
+This contract carries no operation identity. There is no operation ID, no
+durable outcome store, and no replay endpoint, because the caller never
+replays: once-only dispatch plus honest unresolved outcomes need no
+correlation. Introducing replay-safe correlation requires a new contract
+decision that defines request binding, retention, and collision behavior before
+implementation.
+
 ## 11. Normative design vectors
 
 The synthetic vectors under
@@ -1944,6 +2470,21 @@ frontmatter, the body append with its exclusivity refusal, and the declared
 extension-member correction with its untouched anchored extension nodes and
 its undeclared-member refusal.
 
+The `list` cases cover the seven categories section 5.1 is accepted against: an
+empty ledger's witnessed empty page (`list-empty`), a mixed-status filtered
+first page with its continuation cursor (`list-page`), a cursor whose bound
+snapshot moved (`list-stale-cursor`), an invalid ledger refused with no rows
+beside the error (`list-invalid-ledger`), and a maximum page whose exact rows
+exceed the advertised response bound (`list-response-too-large`).
+
+The `workbench` cases cover section 5.2 the same way: a task's four allowed
+edges with their generated actions and derived minimum date
+(`workbench-task-options`), an epic carrying both observed precondition issues
+and both observed disposition blockers (`workbench-epic-blocked`), a terminal
+item with no target at all (`workbench-terminal`), and an invalid ledger refused
+with no projection beside the error (`workbench-invalid-ledger`). Every one
+declares identical before and after ledger digests: the projection is a read.
+
 The runtime executes every vector as a black-box CLI test, including exact
 response bytes and the complete before/after ledger snapshot.