tegwick
598f6418e7
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
3.4 KiB
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.