[sinkog]

What

Documentation only (no code, no Relay change): the requirements the module needs from the Relay so that an execution is not only internally consistent (M4a, merged) but also authorized, happens at most once, and leaves evidence. The module can prove a request matches its plan and echo an execution_digest; it cannot prove that anyone allowed it, that it has not run before, or what happened to it.

• docs/design/relay-requirements.md: new section R6 to R10, each with current behaviour (read from the Relay at 55a899f, not executed), required behaviour, a negative test and an acceptance condition. All needed, not yet raised in CIC-Relay.
• docs/design/specs/approval-and-execution-state.md (new, status concept): what an approval names (execution_digest, approver, policy decision id, scope, validity, the module artifact digest verified at binding), the execution state of one approval, the ProofTrace evidence, the entry points, and the acceptance tests.
• docs/design/README.md index entry.

The three points the spec fixes

1. Atomic, durable single use. Reservation is a compare-and-set, durable and acknowledged before the first sign/actuate of the execution; of any number of concurrent requests for one approval at most one wins. A write-ahead record precedes every provider request. A reservation is released only when no request was attempted.
2. UNKNOWN is not failure and is not retryable. If a request was sent and the answer lost, the execution is neither failed nor released, nothing is resent automatically, and it leaves UNKNOWN only through recorded reconciliation by evidence (for an asynchronous operation including correlating the Work Request with the execution). An ambiguous answer (5xx, gateway timeout) is not proof of no effect. Whether OCI accepts an idempotency token the digest could be derived into is NOT MEASURED and not assumed.
3. ProofTrace keeps five things apart: requested, authorized, sent, confirmed by the provider, uncertain; plus the authenticated run id, the policy decision id, the verified module artifact digest, the reservation transition and the three digests. A signed observation is its own kind and is never recorded as the proven physical state.

Review F1 and F2 (commit 5b0a6ed)

F1 - the approval must bind the actual host call, not only the module's entry point. cic-flow.sign signs whatever bytes the guest hands it and cic-flow.actuate forwards the guest's own method, URL, headers (its Authorization verbatim) and body (read at 55a899f), so a valid execution_digest and a verified approval prove nothing about which HTTP request leaves. R7 now states as a required security property that, before every actuate that can cause a side effect, the relay checks from its own authenticated context that the actual method, target, body and step belong to the reserved, approved execution (the requests an execution may make come from the approved execution, never from the guest); that a sign serving no such step is refused; and that a guest-supplied digest or trace id is not authority. The module's M4a gate covers only its own execute path and cannot protect the host boundary. New negative tests: a different request under a valid approval, and a direct call of cic-flow.actuate/sign outside an approved context. New spec section "The host boundary". How the relay does it stays its own design.

F2 - the safety record is fail-closed. The reservation and the write-ahead record are safety state, not telemetry: if they cannot be made durable, no provider request is sent; they are kept apart from optional trace processing (display, aggregation, export). New read fact: the cabinet's ProofTrace recorder is optional (nil skips it, core/cabinet/service.go:99, :105-106) and runs once, after all steps, with a failed write logged and the workflow continuing (:299-307): a post-hoc, best-effort record, not a write-ahead one. New negative test: the store fails at the reservation and at the write-ahead record, no provider request in either case.

Relay facts used (read at 55a899f, not executed)

• The guest's auth context is the component id (core/cabinet/service.go:228); the cabinet dispatches only init, process, get, notify to a guest (:234-240).
• The cic-flow host functions get cicFlowDeps{sign, doer, egress}: no run, principal or plan (cmd/relay/cic_flow_host_funcs.go:51-55).
• sign and actuate accept a trace_id and never use it; the guest chooses it, so it cannot be an authority.
• actuate returns every transport error as one error text, so "never sent" and "sent, answer lost" look alike to the guest.
• No audit or ProofTrace sink is used in the cic-flow host functions.
• core/nexus/ois (Intent, Policy.Authorize) has non-test importers only in core/nexus/recorder and tools/statechain-demo; cmd/relay and core/cabinet do not use it: the model exists, the link to the module's execution breaks there.

NOT VERIFIED (said so in the documents): whether the Relay has a durable store and its guarantees; whether it sees the operation name (execute/destroy/invoke) before the guest runs; which correlation method exists for a lost asynchronous answer.

Acceptance tests written for later (no Relay implementation here)

The seven required cases (and, after the review, three more: a different request under a valid approval, the host function called directly, and a durable record that cannot be written) (no or invalid approval; approval for another execution_digest; expired or revoked; two concurrent uses; lost OCI answer; changed module artifact; destroy/invoke without approval), plus: reconciliation needed to leave UNKNOWN, crash after the reservation, crash after the write-ahead record, a module that refuses with zero sends, and the shape of the trace. Each states when "no provider request" holds (zero sign and zero actuate).

Module-side follow-up (concept, not built)

destroy and invoke have no plan and no digest, so the module cannot yet hand the Relay a value to approve for them. A digest over the same framing (operation, kind, target, and for invoke the canonical body) is recorded as a concept item.

Not in this PR

No Relay code, no module code, no module.wasm rebuild or signature, no production-integration claim. Nothing here is implemented in the Relay today. No merge without explicit owner GO.

🤖 Generated with Claude Code