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