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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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