railiance-platform/docs/wp0024-owner-review-interface.md

WP-0024 direct owner-review interface

This interface lets each procedure owner inspect its exact review assertions, run the applicable read-only checks, and submit an approval or change request directly. No coding agent has to copy a to-do or translate a prose reply.

The canonical contract is interfaces/RAILIANCE-WP-0024-owner-reviews.json. A receipt is valid only for the canonical SHA-256 digest of that contract and the pinned digests of the owner's artifacts. Any procedure change therefore makes prior approval stale.

Owner flow

Run these commands from a current railiance-platform checkout, replacing the owner and reviewer with your stable agent or operator identifier:

python3 scripts/wp0024-owner-review.py show --owner audit-core
python3 scripts/wp0024-owner-review.py verify --owner audit-core
python3 scripts/wp0024-owner-review.py approve --owner audit-core --reviewer audit-core

Valid owners are audit-core, rapp-postgres, railiance-cluster, railiance-infra, and railiance-platform. approve repeats verification and submits the receipt only when artifact hashes and all named read-only checks pass. The checks may read resource metadata, but they never read Secret data or OpenBao lease payloads. They cannot revoke a lease, restart a workload, create a snapshot, or reboot a node. A successful review is still not a live execution window.

The task-to-owner interface is explicit in the contract:

• T02 requires audit-core, rapp-postgres, and railiance-platform.
• T03 requires audit-core, rapp-postgres, railiance-cluster, and railiance-infra, plus railiance-platform.

One owner receipt may approve both tasks when that owner is responsible for both; its receipt is bound to all artifacts and checks in that owner's review.

To request changes instead:

python3 scripts/wp0024-owner-review.py request-changes \
  --owner audit-core --reviewer audit-core \
  --note 'Clarify the synthetic-load abort threshold.'

The note is durable State Hub metadata. Do not include credentials, secret values, private keys, or sensitive provider output.

Coordination status

Anyone can collect current receipts without interpreting owner messages:

python3 scripts/wp0024-owner-review.py status

The result reports approve, request-changes, or missing per owner, then computes all_approved separately for T02 and T03 as well as for the whole interface. Receipts for an older contract digest or different artifact hashes are counted as stale and cannot satisfy an aggregate.

The interface uses STATE_HUB_URL when set and otherwise connects to http://127.0.0.1:8000. The same value can be supplied explicitly with the top-level --api-base option before the subcommand.

T02 synthetic-load candidate

After procedure receipts are complete, audit-core can implement directly against interfaces/RAILIANCE-WP-0024-T02-synthetic-load-driver.json. The contract fixes all four phases, exact JSON keys, accepted statuses, retry semantics, value-safety requirements, and custody boundary.

The owner registers committed source without executing it:

python3 scripts/wp0024-t02-driver-candidate.py register \
  --repo ../audit-core \
  --driver scripts/<approved-driver> \
  --reviewer audit-core

Registration refuses untracked, modified, non-executable, or out-of-repository source. Its State Hub receipt contains the full source commit and SHA-256 driver revision. It neither runs synthetic traffic nor authorizes a lease revocation. Coordination collects the candidate with:

python3 scripts/wp0024-t02-driver-candidate.py status