tegwick
ceab9ce279
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
144 lines
5 KiB
Markdown
144 lines
5 KiB
Markdown
---
|
|
id: STATE-WP-0082
|
|
type: workplan
|
|
title: "Multi-owner review contracts and receipts"
|
|
domain: infotech
|
|
repo: state-hub
|
|
status: active
|
|
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"
|
|
---
|
|
|
|
# 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: progress
|
|
priority: high
|
|
```
|
|
|
|
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.
|
|
|
|
## Add projection persistence
|
|
|
|
```task
|
|
id: STATE-WP-0082-T02
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
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.
|
|
|
|
## Implement validation and aggregation APIs
|
|
|
|
```task
|
|
id: STATE-WP-0082-T03
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
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.
|
|
|
|
## Provide a direct client and legacy adapter
|
|
|
|
```task
|
|
id: STATE-WP-0082-T04
|
|
status: todo
|
|
priority: medium
|
|
```
|
|
|
|
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.
|
|
|
|
## Pilot with railiance-infra
|
|
|
|
```task
|
|
id: STATE-WP-0082-T05
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
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.
|
|
|
|
## Verify compatibility and extraction readiness
|
|
|
|
```task
|
|
id: STATE-WP-0082-T06
|
|
status: todo
|
|
priority: medium
|
|
```
|
|
|
|
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.
|
|
|
|
## 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.
|