tegwick
2d114be84d
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
187 lines
7 KiB
Markdown
187 lines
7 KiB
Markdown
---
|
|
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.
|