# Review contracts and receipts v1

State Hub exposes a replaceable projection of repository-authoritative review
contracts and immutable receipt files. This is coordination evidence, not an
authorization system: a satisfied aggregate always says that it does not
authorize execution.

## Ownership and extraction boundary

- The contract-owning repository owns the contract file and its full Git
  revision.
- Each reviewing repository owns its receipt file and full Git revision.
- State Hub validates, indexes, derives owner/gate state, and can be rebuilt
  from those files. Agent messages may link to record IDs but are not receipt
  storage.
- State Hub never executes a check named by a consumer. Receipt producers run
  their own closed, read-only check interfaces and submit only their results.
- Actor strings are coordination identities in v1, not authenticated proof.
  Authenticated actor-to-owner delegation belongs in the extracted hub-core
  service.

All timestamps stored or emitted by State Hub are canonical UTC. Local calendar
and time rendering is an I/O or UI concern.

## Contract

POST /review-contracts/projections accepts a wrapper containing:

- source: repository, relative path, and a full Git revision;
- optional decision, workplan, and task UUID links;
- required_for_decision, which makes a linked decision wait for the gate;
- contract: a review-contract/v1 document.

The contract document has a stable contract key, typed subject, the two allowed
dispositions approve and request_changes, SHA-256 artifacts, owner scopes with
stable assertion and named check IDs, and gates. Version 1 supports only the
all_required gate policy.

Projecting a new digest under the same contract key makes the prior revision
inactive. Its receipts remain immutable and are reported as stale until the
owner submits evidence against the active digest. The bounded
railiance.owner-review version 1 adapter derives stable assertion IDs and
preserves that prototype's canonical source digest.

## Receipt

POST /review-contracts/{contract_key}/receipts accepts an authoritative receipt
document. An approval must exactly cover the owner's artifacts, assertion IDs,
and named checks. Every check must say both passed true and read_only true.
request_changes requires a note and becomes the owner's latest blocking
disposition. Reposting byte-equivalent evidence is idempotent.

The service assigns submitted_at in UTC and a SHA-256 receipt digest. Receipts
cannot be patched or deleted through this API.

Direct client examples:

    statehub review project interfaces/review.json
    statehub review submit EXAMPLE-REVIEW-1 receipt.json
    statehub review status EXAMPLE-REVIEW-1

The CLI derives the repository-relative path and full current Git revision, so
those projection fields do not need to be embedded in the authoritative file.
Use --source-repo only when the repository directory name is not its canonical
slug.

If an active contract is linked to a decision with required_for_decision true,
the legacy decision resolve action returns 409 until every v1 all_required gate
is satisfied. Decisions without such a contract retain their existing
behavior.

## Rollback and rebuild

The Alembic downgrade drops only the two projection tables. It does not rewrite
or delete existing decisions. Rebuild by replaying contract projection files
in revision order, then their receipt files. Repository files remain the
recovery source throughout.
