feat(review): add multi-owner contracts and receipts

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

docs/review-contracts-v1.md

@@ -0,0 +1,77 @@
+# 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.