Enforce participant flow policy at final runtime sinks

[Brad-Edwards]

Parent: #812

Bounded outcome

Extend RUN-319 so every governed external action or disclosure resolves SEM-233 effective labels, exact policy/state cut, authority, destination, and API-407 support immediately before RuntimeTarget dispatch or serialization. Commit the decision atomically before effect and preserve idempotent, append-only evidence.

Negative cases

• Enforcement only at planning, schema validation, action admission, gateway, prompt, monitor, or request construction.
• Backend dispatch or participant-visible output before the durable permit decision.
• Missing label/provenance, stale cut, unsupported capability, policy denial, failed expected-head check, or failed commit causing any external effect.
• Streaming chunks, errors, tool arguments, callbacks, or handoffs bypassing the sink policy.
• Unsafe raw values in diagnostics, logs, audit, or error envelopes.

Evidence required

• Boundary tests through the real RuntimeControlPlane and instrumented RuntimeTarget.
• Zero target-call and zero disclosure assertions for every denial class.
• Atomic store, history-head, idempotency, replay, restart, and both shipped-store evidence.
• Authenticated identity/target/participant/controller/audience binding tests.
• Safe bounded diagnostics and audit/evidence assertions.

Explicit nonclaims

• Reference-runtime enforcement is not backend realization or universal information-flow control.
• No undeclared timing/covert-channel, opaque apparatus, monitor-honesty, or model-alignment claim.

Dependencies

• Blocked by Publish adversarial participant flow-control contracts #1002.
• Parent design: Adopt adversarial AI-agent control and boundary-IFC threat models for participants #812.

Requirements

• SEM-233
• RUN-319
• RUN-310
• API-423
• API-407

[Brad-Edwards]

🛠️ Picked up by /implement - driver claude, branch 1003-runtime-sink-flow-enforcement, 2026-08-02T16:22:44.634Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #1003). 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: preflight (issue #1003). 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: preflight (issue #1003). 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: preflight (issue #1003). 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: preflight (issue #1003). 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 #1003). 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 — Enforce participant flow policy at final runtime sinks (#1003)

Requirements in scope: SEM-233, RUN-319, RUN-310, API-423, API-407 (all ACTIVE). Base branch dev (blocker #1002/PR #1053 is merged into dev).

Problem statement (the gap)

#1002 (PR #1053) published the portable SEM-233 final-sink flow-control contracts in raes_contracts — ParticipantFlowControlRelationModel, ParticipantFlowSinkDecisionModel, ParticipantFlowControlValidationContext, and validate_participant_flow_control_resolved_context(). These are not consumed anywhere in raes_runtime. The reference runtime today resolves and commits only the older API-423 crossing decision (prepare_participant_crossing → commit_prepared_crossing), and does not resolve the SEM-233 effective-label / exact-cut / release-authority / destination / API-407-capability final disposition before a RuntimeTarget effect or serialization. The architecture preflight (docs/decisions/issue-1003-sem-233-final-runtime-sinks-preflight.md, created by Step 2.5, kept as the binding note) is the governing guidance.

Per ADR-101 the final RAES-controlled boundary is after exact policy/authority/destination/capability/state-cut resolution and before a RuntimeTarget component performs an external action or any participant/external value is serialized, streamed, persisted, returned in an error, callback, or handoff.

Design (fail-closed, one decision bound to the committed state cut)

Wire the SEM-233 final-sink decision into the existing operation-bound crossing transaction — no new store, policy engine, audit channel, exception hierarchy, or generic sink/dispatcher. All work stays inside the _participant_control_lock prepare→commit window that both real sinks already use.

1. New shared final-sink guard — implementations/python/packages/raes_runtime/participant_flow_sink.py.

   • A single narrow helper (resolve_participant_flow_sink_decision(control_plane, prepared, *, sink_kind, ...)) that every real target invocation / disclosure writer must call. It delegates to validate_participant_flow_control_resolved_context(); it does not re-implement any join.
   • It obtains the trusted SEM-233 relation + ParticipantFlowControlValidationContext from a server-side resolver method on the existing _crossing_policy_resolver (new optional protocol method resolve_flow_sink_decision(...) — no wire input, no caller-supplied relation/labels/profile/authority/sink/disposition). The context carries the already-validated API-423 occurrence, exact profile/policy/cut, source labels + provenance, ParticipantFlowSinkCoordinate (destination/audience), release authority, ParticipantFlowActionAdmissionResolution, ParticipantFlowCapabilityResolution (API-407 via resolve_participant_feature_support()), and ParticipantFlowHistoryHeadResolution bound to the same expected history heads as the prepared crossing.
   • Permit iff SEM-233 final_disposition == PERMIT and the referenced API-423 decision, SEM-211 admission (where applicable), SEM-226 projection (where applicable), API-407 capability result, authenticated principal/target/participant/controller/audience bindings, and current history heads all agree. Missing / stale / ambiguous / unresolved / unsupported / denied / mismatched → a preserved non-permit reason class (DENY/UNSUPPORTED/STALE/UNRESOLVED), never collapsed into an implicit permit or an unbounded error.
   • Evidence is reference, not raw payload: the guard folds the SEM-233 sink-decision reference (document_id + digest + decision_id) into the PreparedParticipantCrossing record/history so it is written in the same commit_participant_transition set as the API-423 decision. The relation document itself is a resolver-side trusted artifact (like flow-policy profiles loaded via load_participant_boundary_flow_policy_profile_revision), not stored raw in the snapshot. If a closed reference field must be added to a published crossing/flow schema under contracts/schemas/, record the last_change change-ledger entry in contracts/schema-publication-manifest.json and keep schema_bundle() byte-identical (tools/check_generated_schemas.py). Preferred path: reuse existing evidence_refs/required_evidence_refs plumbing to carry the reference and avoid a schema change.

2. Instrument every real sink — the guard is invoked inside the existing transaction window, before the effect:

   • Egress serialization: participant_crossing_egress.py::serialize_participant_view — resolve+bind the SEM-233 permit before the governed view is committed/returned; non-permit → commit denial, PermissionError, zero disclosure.
   • Ingress action admission: participant_crossing_boundary.py::execute_action_ingress_crossing — resolve+bind before the apply_authorized_participant_action backend call (line 229); the authorization commit already precedes the effect, the SEM-233 permit joins that same commit. record_participant_control (RUN-310 control ingress) gets the same guard so intervention/handoff/approval crossings resolve a final-sink permit.
   • Ensure no bypass: audit the other RuntimeControlPlane target-dispatch paths (participant_control.py lifecycle initialize/reset/restart/terminate, control_plane_execution.py) for governed external effects/disclosures; any that reach a RuntimeTarget component with participant-relative scope route through the same guard. Legacy non-participant provisioning/orchestration/evaluation plan submission is out of scope and remains unchanged (it is not a participant-governed disclosure).

3. Commit-before-effect + later facts separate. commit_participant_transition() remains the sole durable pre-effect transaction across both shipped stores (InMemoryControlPlaneStore, LocalControlPlaneStore) with expected-head guarding. After a successful commit, invoke only the authorized target / serialize only the governed projection. Backend failure, delivery, observation, callback completion, and audit retention stay later append-only facts with predecessor refs (existing _with_opacity_egress_observation pattern), never pre-committed as delivery.

4. Idempotency + replay. The operation fingerprint and expected heads bind the same semantic cut the flow decision used; a profile/policy/label/provenance/release/sink/audience/capability/controller/target/head change conflicts and must not reuse a prior permit (extend _semantic_fingerprint / _require_replay_state_cut).

5. Restart validation. Extend validate_persisted_crossing_history (or add a sibling invoked from the RuntimeControlPlane constructor for both stores) to revalidate any persisted SEM-233 final-sink reference against the resolver's trusted context on load; unresolved → fail closed (no serving/mutating).

Cross-cutting design review (FAANG-L6 / preflight §Security layers)

• Security: trusted server-side resolver only (no caller-selected file/URL/profile/relation/disposition); separate participant / controller / audience bindings via ControlPlaneIdentity (role or API-408 admin read is not disclosure authority); bounded value-independent denial reasons; unexpected failures stay {"detail":"internal server error"}; no raw values, prompts, policy bodies, tokens, backend exceptions, URLs, env, or argv in diagnostics/audit/logs/evidence; a digest is not automatically safe-to-disclose content. No subprocess/secret-loader/env-binding/plugin added.
• Maintainability: reuse the incumbents in the preflight table (prepare_participant_crossing, commit_participant_transition, PreparedParticipantCrossing, expected_participant_history_heads, resolve_participant_feature_support, ControlPlaneOperationRecord, AuditEvent, Diagnostic); the guard composes owning validators, never copies joins into routes/adapters/tests.
• Extensibility: the seam is the closed SEM-233 sink coordinate (sink_kind, sink_ref, destination_ref, audience_scope_ref) + trusted non-wire context + expected-head write set. A future stream/callback/persistent-write/multi-part sink adds a closed sink variant that calls the same pre-effect decision/commit boundary; streaming requires a decision before the first byte and retains the bound decision/cut per chunk; error paths and handoffs are sinks too.
• Whole-repo view: touches only raes_runtime + tests (+ optional contracts/schemas ledger if a reference field is published + optional docs/migration/participant-information-flow-control.md note). Respects .gc/plan-rules.md: no authority artifacts outside specs//contracts//docs//implementations/; no CHANGELOG.md/changelog.d//_version.py edits; keep IMPLEMENTS/TESTS traceability aligned; RAES_REQUIREMENT_UID=RUN-319 for verify (branch carries no UID).

Tests (TDD, boundary-driven — implementations/python/tests/test_issue_1003_final_sink_flow_enforcement.py)

Drive the real RuntimeControlPlane with an instrumented RuntimeTarget that counts backend/target calls, plus a trusted test flow-control resolver (built on participant_crossing_fixtures.py, sem233_boundary_flow_model.py). Assert:

• Zero target calls and zero disclosures for every non-permit class: missing label/provenance, stale cut, unsupported API-407 capability, policy denial, failed expected-head check, failed commit, resolver exception, replay-semantic mismatch, restart-validation failure.
• Positive: successful permitted egress projection and ingress admission; SEM-233 evidence reference committed atomically with the API-423 decision; correct final disposition combination.
• Idempotent replay returns the stored receipt only on exact semantic match; both shipped stores (InMemory, Local) preserve expected-head behavior and restart validation.
• Authenticated identity / target / participant / controller / audience binding required before existence or content disclosure; transformed ingress re-admission and projected egress; streaming/callback/error/handoff paths do not bypass the guard.
• Safe bounded diagnostics / audit / error envelopes (no raw values).
• Regression: existing test_run_319_participant_flow_policy.py, test_sem_233_flow_control_contracts.py, test_api_423_participant_crossing_contracts.py, test_run_310_supervisory_lifecycle.py, test_runtime_control_plane*.py stay green.

Traceability (reconciled post-merge at Steps 15–16)

New participant_flow_sink.py → IMPLEMENTS SEM-233 + RUN-319; edits binding the final-sink permit → IMPLEMENTS RUN-319 (primary), with API-423 (evidence reference), API-407 (capability gate), RUN-310 (control-ingress lifecycle ordering) as the joins they enforce. New test file → TESTS SEM-233/RUN-319/API-423/API-407/RUN-310. All five requirements already ACTIVE — no DRAFT→ACTIVE transition needed; Step 15/16 reconcile links only.

Gates before completion (per .gc/plan-rules.md)

tools/check_repo_policy.py, tools/check_requirement_governance.py, tools/verify_all.py (via the verify nox session) all run at the completion boundary with RAES_REQUIREMENT_UID=RUN-319. PR title will be a valid Conventional Commit feat: (consumer-visible runtime enforcement) passing title-guard.

Non-goals (preflight)

Reference-runtime enforcement only — no universal information-flow control, backend realization, noninterference, covert/timing-channel control, monitor honesty, model alignment, or adversarial-robustness claim. No new policy language, transport, schema family, HTTP auth mechanism, or generic sink framework. Absence of crossing evidence never implies a permit or historical enforcement.