docs(review): add multi-owner contract workplan

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d

workplans/STATE-WP-0082-multi-owner-review-contracts-and-receipts.md

@@ -0,0 +1,144 @@
+---
+id: STATE-WP-0082
+type: workplan
+title: "Multi-owner review contracts and receipts"
+domain: infotech
+repo: state-hub
+status: active
+owner: codex
+topic_slug: multi-owner-review-contracts
+created: "2026-08-22"
+updated: "2026-08-22"
+related:
+  - RAILIANCE-WP-0024
+  - RAIL-HO-WP-0011
+origin: routed
+origin_ref: "Operator request to generalize the RAILIANCE-WP-0024 owner-review interface"
+---
+
+# Multi-owner review contracts and receipts
+
+## Goal
+
+Generalize the hash-bound `RAILIANCE-WP-0024` owner-review prototype into a
+file-authoritative, queryable review-contract projection. State Hub validates,
+indexes, aggregates, and exposes contracts and immutable receipts; it does not
+execute consumer-defined commands or turn procedure review into live-action
+authorization.
+
+This is a compatibility and extraction slice while State Hub retires. Contract
+and receipt files remain authoritative in their owning repositories, messages
+carry notification references only, and the implementation must remain
+separable for later movement to `hub-core`.
+
+## Define the review-contract boundary
+
+```task
+id: STATE-WP-0082-T01
+status: progress
+priority: high
+```
+
+Specify a versioned canonical contract with typed subject and owner references,
+explicit gates, stable assertion ids, revision-pinned artifact hashes, named
+read-only checks, allowed dispositions, and deterministic canonical digesting.
+Specify append-only receipt semantics, staleness, supersession, idempotency,
+and aggregate state.
+
+Done when the boundary preserves existing simple decisions, keeps repository
+files authoritative, treats State Hub as projection, and states explicitly
+that a satisfied procedure review is not an execution authorization.
+
+## Add projection persistence
+
+```task
+id: STATE-WP-0082-T02
+status: todo
+priority: high
+```
+
+Add review-contract and immutable receipt persistence through an Alembic
+migration. Keep the review aggregate separate from the existing `decisions`
+row rather than adding owner arrays or receipt blobs to it. Retain source repo,
+path, full revision, contract digest, receipt digest, canonical UTC timestamps,
+and optional links to a decision, workplan, or task.
+
+Done when upgrade/downgrade works and existing decision rows and routes require
+no data rewrite.
+
+## Implement validation and aggregation APIs
+
+```task
+id: STATE-WP-0082-T03
+status: todo
+priority: high
+```
+
+Provide contract projection, receipt submission, exact reads, and aggregate
+status. Reject unknown owners, incomplete owner scopes, digest mismatches,
+artifact drift, missing assertions/checks, unsafe dispositions, duplicate
+non-idempotent submissions, and legacy decision resolution that would bypass a
+required review gate.
+
+For version 1, support the prototype's `all_required` policy only. A latest
+valid `request_changes` blocks its owner's gates; contract changes make prior
+receipts stale rather than mutating or deleting them.
+
+## Provide a direct client and legacy adapter
+
+```task
+id: STATE-WP-0082-T04
+status: todo
+priority: medium
+```
+
+Add a State Hub CLI or import surface that can project an authoritative
+contract, submit a file-backed receipt, and print owner/gate status. Provide a
+bounded adapter for the `RAILIANCE-WP-0024` contract shape so the prototype can
+migrate without making State Hub execute its repository-specific checks.
+
+Done when callers no longer encode receipts as opaque agent-message bodies and
+message transport can carry stable contract/receipt references instead.
+
+## Pilot with railiance-infra
+
+```task
+id: STATE-WP-0082-T05
+status: todo
+priority: high
+```
+
+Use `railiance-infra` as the first consumer. Publish a canonical receipt file
+for its existing `RAILIANCE-WP-0024-T03` procedure review, project it through
+the generic interface, and prove the aggregate owner matrix matches the
+prototype without authorizing a reboot.
+
+The pilot must prove approval, request-changes supersession, artifact-change
+staleness, duplicate idempotency, wrong-owner rejection, canonical UTC receipt
+time, and rebuild from repository files.
+
+## Verify compatibility and extraction readiness
+
+```task
+id: STATE-WP-0082-T06
+status: todo
+priority: medium
+```
+
+Run migration, router, service, CLI, and full-suite tests. Document the source
+and projection contracts, operational rollback, message compatibility, and the
+future `hub-core` extraction boundary. Record any unimplemented authenticated
+actor-to-owner authorization as a live residual rather than implying that a
+caller-supplied owner string is authority.
+
+## Acceptance
+
+- Existing single-decider APIs remain backward compatible.
+- Review contracts are separate aggregates linked to decisions/work records.
+- Every valid approval is bound to the exact contract, assertions, artifacts,
+  checks, owner, actor, and canonical UTC receipt time.
+- Contract or artifact change makes old receipts stale.
+- State Hub never runs arbitrary commands from a contract.
+- Aggregate satisfaction never by itself authorizes a live mutation.
+- `railiance-infra` completes the first file-backed consumer round trip.
+- The projection can be rebuilt from authoritative contract and receipt files.