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

id	type	title	domain	repo	status	owner	topic_slug	created	updated	related	origin	origin_ref	state_hub_workstream_id
STATE-WP-0082	workplan	Multi-owner review contracts and receipts	infotech	state-hub	finished	codex	multi-owner-review-contracts	2026-08-22	2026-08-22	RAILIANCE-WP-0024 RAIL-HO-WP-0011	routed	Operator request to generalize the RAILIANCE-WP-0024 owner-review interface	eb09a516-1fe6-5c41-999f-8e1471b7f82c

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

id: STATE-WP-0082-T01
status: done
priority: high
state_hub_task_id: "a6511423-78e0-51c6-8c7d-b91609e331ff"

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.

Implemented in docs/review-contracts-v1.md and the review-contract/v1 validator. The bounded WP-0024 adapter preserves the prototype source digest and derives stable assertion ids.

Add projection persistence

id: STATE-WP-0082-T02
status: done
priority: high
state_hub_task_id: "e2ac4ad6-91d9-5b4e-a0fb-7106c731e348"

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.

Implemented as separate review_contracts and append-only review_receipts tables in migration c9e5a1b3d7f2. A clean upgrade/downgrade/upgrade round trip passed.

Implement validation and aggregation APIs

id: STATE-WP-0082-T03
status: done
priority: high
state_hub_task_id: "48682d0c-e69f-5486-a007-472dea959994"

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.

Projection, receipt, exact listing, and aggregate routes enforce the v1 contract. Linked required reviews now prevent legacy decision resolution from bypassing an unsatisfied gate.

Provide a direct client and legacy adapter

id: STATE-WP-0082-T04
status: done
priority: medium
state_hub_task_id: "9ab5b022-25d0-556c-bca0-222c414bc18f"

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.

Implemented statehub review project|submit|status. The client derives the repository path and full revision from Git. Legacy message receipts remain historical notifications rather than canonical evidence.

Pilot with railiance-infra

id: STATE-WP-0082-T05
status: done
priority: high
state_hub_task_id: "90af0001-17c6-5cbb-9d08-64947211f956"

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.

Projected contract 01a02ac9-9e90-74c0-bdb2-a8604d32b542 from railiance-platform@a557208a4a33520c39f749dcc26e6985386a96d4. Projected railiance-infra receipt 01a02aca-02dd-7b16-93f2-7ab455976059 from railiance-infra@d85237aee8080201ddacb2d4f34a15b6fc91609b. Its owner state is approved while both gates remain unsatisfied and authorizes_execution remains false.

Verify compatibility and extraction readiness

id: STATE-WP-0082-T06
status: done
priority: medium
state_hub_task_id: "c8486c31-d36b-5517-be2f-7efc715dfd79"

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.

Focused lint, 13 affected tests, and the final 640-test full suite pass. The suite retains one pre-existing async SQLAlchemy cleanup warning. Authenticated actor-to-owner delegation is live residual intake 01a02aca-2dfc-7e57-bebf-f5e970d7b403.

Residual handoff

Authenticated actor-to-owner delegation and authorization proof are tracked by State Hub intake 01a02aca-2dfc-7e57-bebf-f5e970d7b403 (origin: residual, origin_ref: STATE-WP-0082). Until that work is promoted, actor strings are coordination identities only.

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.