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-WP-0082	workplan	Multi-owner review contracts and receipts	infotech	state-hub	active	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

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: 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

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

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

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

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

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.