RUN-319 — Participant Information-Flow Policy Enforcement

[Brad-Edwards]

Requirements

• RUN-319

Bounded outcome

Enforce and persist governed participant ingress/egress decisions through the reference runtime using existing admission, projection, lifecycle, store, audit, idempotency, error, and security boundaries.

Non-goals

• Selecting a participant gateway or transport.
• A parallel policy engine, persistence store, audit channel, or exception hierarchy.
• Claiming backend realization or universal information-flow assurance from reference-runtime tests.

Dependencies

• Assess and design formal participant I/O control with information-flow and bisimulation semantics #794
• API-423 — Participant Crossing Policy And Evidence Contracts #798 (API-423 crossing contracts)
• Declare participant I/O policy capability and realization support (API-407) #801 (API-407 capability declarations)
• Intervention, Handoff, And Supervisory Lifecycle (RUN-310) #255 (RUN-310 supervisory lifecycle)
• Participant Exposure And Visibility-Boundary Semantics (SEM-226) #296 (SEM-226 exposure)

Acceptance criteria

• Fail closed on missing policy, authority, projection, marking, declassification basis, or required capability.
• Revalidate transformed proposals as new attempts; project/mask/redact output before serialization; preserve source/result identity and markings.
• Apply authenticated caller, participant subject/authority, admission, and visibility as separate gates.
• Append-only decision and realization histories survive persistence/restart/replay and retain ordering, policy revision, evidence, provenance, loss, and audit links.
• Unsupported or downgraded backend behavior is explicit and cannot retain a stronger claim.
• Update the participant section of docs/explain/sdl/lineage.md with this issue's adopted intellectual lineage, exact ACES artifact mappings, delivery status, evidence links, and explicit nonclaims; update contracts/provenance/sdl-lineage-ledger-v1.json and its source audit only when normative derivation or compatibility claims change.

Required assurance evidence

• Boundary behavioral, property, persistence/replay, and concurrency tests.
• Negative cross-participant leakage, stale-policy, authority, transformation, redacted-error, and audit-integrity tests.
• Bounded reference-runtime claim bindings with explicit backend nonclaims.

Parent program: #794.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 799-participant-flow-policy, 2026-07-27T21:31:42.667Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #799). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #799). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Implementation plan

1. Close the exact-cut contract gap. Extend the draft API-423 policy reference with a required exact decision/state-cut reference, update its hand-governed schema, fixtures, generated bundle parity, focused contract tests, and schema-publication entry/hash. Keep policy bodies and hidden state out of portable records; no new ADR unless compatibility checks reveal a normative conflict.
2. Add first-class crossing state. Add typed participant_crossing_history to RuntimeSnapshot, the published runtime-snapshot model/schema, serializers, with_entries() plumbing, snapshot shape checks, append-only transition checks, and operational summary accounting. Persist it as normal snapshot state—not metadata, audit details, or a second store.
3. Implement one runtime-owned mediation seam. Add a closed, bounded crossing intent plus trusted policy/context resolver interfaces under raes_runtime. RuntimeControlPlane will derive caller/target/participant-or-audience authorization, infer mandatory API-407 features from the crossing, resolve strength/evidence with resolve_participant_feature_support(), compose all gates deny-first, own API-423 identities/dispositions/reason codes, validate the full candidate history through validate_participant_crossing_occurrence_context(), and reject missing/stale policy, authority, marking, declassification, exposure/admission, transformation, or capability context. Callers cannot submit completed occurrences or choose gates/dispositions.
4. Preserve operation separation. Keep SEM-211 action admission, RUN-310 control, SEM-226 exact-cut exposure, DSL-142 inject delivery, and API-423 stage meanings as their canonical owners. Governed transformations must create a fresh typed result, retain markings/provenance unless explicitly declassified, and re-enter the complete crossing/admission path with fresh identity and idempotency semantics. Participant-facing projection is completed and durably authorized before any projected result is returned; administrative snapshot retrieval remains distinct.
5. Generalize the atomic participant transition. Reuse/generalize the RUN-310 expected-head transaction so crossing facts, snapshot state, operation/idempotency record, and safe audit correlation commit atomically in both in-memory and local stores. Bind fingerprints to principal, target, participant, episode, audience, typed subject revision/digest, exact cut, history heads, policy/capability posture, markings, and transformation identity. Validate persisted crossing context on restart before serving or mutating it.
6. Drive implementation with focused tests first. Add failing RUN-319 tests for positive ingress/egress decisions; independent caller/target/participant/admission/visibility/marking/declassification gates; missing/stale policy and required capability; unsupported and explicitly authorized downgrade claims; transformed-proposal fresh validation; cross-participant leakage; append-only ordering; exact retry/conflicting idempotency; atomic failure; restart/replay; concurrency head conflicts; redacted errors; and serialization only after durable projection. Extend API-423/runtime-snapshot/schema tests and use property-based cases where they add boundary value.
7. Document bounded delivery. Update the participant section of docs/explain/sdl/lineage.md with exact RAES mappings, runtime/store/test evidence, delivery status, and explicit nonclaims. Do not change the lineage ledger or source audit because the adopted derivation and compatibility claims are unchanged. Do not edit CHANGELOG.md or the product version.

Repository-wide design checks

• Security: preserve request bounds and closed models; strict bearer/proxy authentication; exact target binding; separate trusted control-subject and audience bindings; SEM-211/SEM-226/marking/declassification gates; safe value-independent diagnostics; existing redacted unexpected-error envelope; no credentials, hidden payloads, policy bodies, rejected values, or exception text in history/audit/logs.
• Maintainability: reuse API-423 models/validator, RUN-310 mediation/idempotency/store transaction, SEM-226 selectors, API-407 strength resolver, Diagnostic, AuditEvent, RuntimeSnapshot, and existing publication tooling. Add no gateway, policy engine, store, audit channel, logger, exception hierarchy, or open metadata bag.
• Extensibility: parameterize one transition by typed subject, audience, exact cut, trusted resolvers, required feature strength, optional authorized downgrade/governed transformation, and expected history heads, leaving a closed seam for future carrier kinds, audiences, ordering models, and durable stores.
• Whole-repo view: update the Python contract/runtime/store/model/test surfaces, hand-governed API-423 and runtime-snapshot schemas, schema publication entries, generated-schema parity, operational summary, documentation, traceability, and all configured policy/verification gates.

Verification

Use RAES_REQUIREMENT_UID=RUN-319 for every repo-authored gate. Run focused pytest suites during TDD, then the configured completion and policy gates. Before declaring completion, explicitly run implementations/python/.venv/bin/python tools/check_repo_policy.py, implementations/python/.venv/bin/python tools/check_requirement_governance.py, and implementations/python/.venv/bin/python tools/verify_all.py, followed by the required pre-push code and test-quality review cycles.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #799 (branch 799-participant-flow-policy)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: don't-ship

This change correctly identifies API-423 occurrence history, exact policy/cut references, canonical capability resolution, and expected-head persistence as the right design vocabulary; the schema and snapshot plumbing is coherent. The runtime seam is not completed, however: crossing mediation is implemented as a separately committed recorder before action/control execution and merely placed alongside participant retrieval, rather than as the atomic boundary that owns the governed result, incumbent state mutation, operation record, audit correlation, and egress serialization. That shape leaves bypasses, cannot carry transformed ingress into execution, and conflicts with the preflight and lineage claims.

Blocking findings (1):

1. [class] Crossing mediation is a detached sidecar rather than the shared atomic boundary — implementations/python/packages/raes_runtime/participant_crossing_boundary.py:50
   Architecture-fit — the control and action bridges first commit a standalone crossing operation, discard an accepted crossing receipt, and then invoke the incumbent control transition or execute the original action request separately. Crossing facts, the owning state transition, operation/idempotency outcome, and audit therefore do not share one expected-head write set; a failure after the crossing commit leaves durable authorization evidence without the owning transition. A transformed ingress is also only represented by a new subject reference inside crossing history: the bridge returns no governed request/result, so action execution still receives the original request. Egress has the same structural gap in another form: ParticipantCrossingMixin is composed alongside ParticipantRetrievalMixin, but no retrieval path invokes mediation or serializes a governed result. Code-quality — the tests exercise the standalone recorder and its history rather than these end-to-end boundaries, so they make this incomplete integration appear delivered. Make the shared boundary own the decision, governed result, incumbent operation, atomic commit, and output serialization.

Security review

Verdict: don't-ship

The change targets the correct shared runtime boundary and composes authentication, exact-cut policy resolution, capability checks, append-only evidence, and expected-head persistence. However, the security seam is split in two ways: the caller-supplied crossing description is not fully bound to the operation that follows, and the authorization decision is committed separately from that operation. Those shapes create reusable authorization-confusion and stale-decision bypasses across both control and action ingress, so this should not ship until mediation and execution form one operation-bound transition.

Blocking findings (2):

1. [class] Crossing authorization is not bound to the operation being executed — implementations/python/packages/raes_runtime/participant_crossing_boundary.py:51
   Attacker model: an authenticated operator bound to the participant/controller but restricted by crossing policy to particular interaction kinds or exact subjects. For supervisory control, the mediator receives only the participant and a caller-supplied crossing intent; it never receives or derives semantics from the actual ParticipantControlIntent. Any interaction in the broad allowed set is accepted, so an attacker can pair a policy-permitted denial crossing with a ParticipantHandoffControlIntent; the resolver authorizes the denial description, after which the code executes the handoff. The action path has the same confused-deputy shape: it compares only action_or_projection_ref with the coarse action-contract address and never binds the crossing subject identity, revision/digest, episode, or policy-relevant request semantics to the exact admission request. Construct the crossing input from the incumbent operation inside the trusted boundary, or validate an operation-specific canonical binding covering the actual intent type and exact subject/request semantics before resolving policy.
2. [class] Authorization and the protected operation are separated by a stale-decision window — implementations/python/packages/raes_runtime/participant_crossing_boundary.py:61
   The crossing mediator resolves policy under _participant_control_lock, commits its decision, releases the lock, and returns. Only afterward does this wrapper enter the incumbent control transition; the action path similarly calls backend action execution afterward. A concurrent request can advance a policy-relevant behavior/control head or revoke participant authority between those steps, while the already-permitted call continues without re-resolving the crossing decision against the new state. The expected-head checks protect only the earlier crossing-record commit, not the later protected operation. An authenticated caller can exploit this by obtaining a permit under the old cut while another coordinated request changes the relevant state, then allowing the original thread to dispatch under the stale permit. Resolve the decision, validate the incumbent operation, and commit the applicable crossing facts plus operation/state outcome under one locked expected-head transition; no backend dispatch or permitted output should occur after releasing that boundary without revalidation.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #799 on branch '799-participant-flow-policy'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.