From ceab9ce27966b6a85eb5f9b0bdf9463339bc9803 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 22 Aug 2026 18:02:36 +0200 Subject: [PATCH] docs(review): add multi-owner contract workplan Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d --- ...lti-owner-review-contracts-and-receipts.md | 144 ++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 workplans/STATE-WP-0082-multi-owner-review-contracts-and-receipts.md diff --git a/workplans/STATE-WP-0082-multi-owner-review-contracts-and-receipts.md b/workplans/STATE-WP-0082-multi-owner-review-contracts-and-receipts.md new file mode 100644 index 0000000..b159df1 --- /dev/null +++ b/workplans/STATE-WP-0082-multi-owner-review-contracts-and-receipts.md @@ -0,0 +1,144 @@ +--- +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.