---
id: STATE-WP-0082
type: workplan
title: "Multi-owner review contracts and receipts"
domain: infotech
repo: state-hub
status: finished
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"
state_hub_workstream_id: "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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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.