Repository navigation
Enforce participant flow policy at final runtime sinks #1003
Description
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
RuntimeControlPlaneand instrumentedRuntimeTarget. - 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
Activity
Brad-Edwards commentedon Aug 2, 2026
🛠️ Picked up by /implement - driver claude, branch
1003-runtime-sink-flow-enforcement, 2026-08-02T16:22:44.634Z.Brad-Edwards commentedon Aug 2, 2026
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 commentedon Aug 2, 2026
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 commentedon Aug 2, 2026
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 commentedon Aug 2, 2026
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 commentedon Aug 2, 2026
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 commentedon Aug 2, 2026
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 intodev).Problem statement (the gap)
#1002 (PR #1053) published the portable SEM-233 final-sink flow-control contracts in
raes_contracts—ParticipantFlowControlRelationModel,ParticipantFlowSinkDecisionModel,ParticipantFlowControlValidationContext, andvalidate_participant_flow_control_resolved_context(). These are not consumed anywhere inraes_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 aRuntimeTargeteffect 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
RuntimeTargetcomponent 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_lockprepare→commit window that both real sinks already use.New shared final-sink guard —
implementations/python/packages/raes_runtime/participant_flow_sink.py.resolve_participant_flow_sink_decision(control_plane, prepared, *, sink_kind, ...)) that every real target invocation / disclosure writer must call. It delegates tovalidate_participant_flow_control_resolved_context(); it does not re-implement any join.ParticipantFlowControlValidationContextfrom a server-side resolver method on the existing_crossing_policy_resolver(new optional protocol methodresolve_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 viaresolve_participant_feature_support()), andParticipantFlowHistoryHeadResolutionbound to the same expected history heads as the prepared crossing.final_disposition == PERMITand 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.document_id+ digest +decision_id) into thePreparedParticipantCrossingrecord/history so it is written in the samecommit_participant_transitionset as the API-423 decision. The relation document itself is a resolver-side trusted artifact (like flow-policy profiles loaded viaload_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 undercontracts/schemas/, record thelast_changechange-ledger entry incontracts/schema-publication-manifest.jsonand keepschema_bundle()byte-identical (tools/check_generated_schemas.py). Preferred path: reuse existingevidence_refs/required_evidence_refsplumbing to carry the reference and avoid a schema change.Instrument every real sink — the guard is invoked inside the existing transaction window, before the effect:
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.participant_crossing_boundary.py::execute_action_ingress_crossing— resolve+bind before theapply_authorized_participant_actionbackend 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.RuntimeControlPlanetarget-dispatch paths (participant_control.pylifecycle initialize/reset/restart/terminate,control_plane_execution.py) for governed external effects/disclosures; any that reach aRuntimeTargetcomponent 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).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_observationpattern), never pre-committed as delivery.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).Restart validation. Extend
validate_persisted_crossing_history(or add a sibling invoked from theRuntimeControlPlaneconstructor 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)
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.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.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.raes_runtime+ tests (+ optionalcontracts/schemasledger if a reference field is published + optionaldocs/migration/participant-information-flow-control.mdnote). Respects.gc/plan-rules.md: no authority artifacts outsidespecs//contracts//docs//implementations/; noCHANGELOG.md/changelog.d//_version.pyedits; keep IMPLEMENTS/TESTS traceability aligned;RAES_REQUIREMENT_UID=RUN-319for verify (branch carries no UID).Tests (TDD, boundary-driven —
implementations/python/tests/test_issue_1003_final_sink_flow_enforcement.py)Drive the real
RuntimeControlPlanewith an instrumentedRuntimeTargetthat counts backend/target calls, plus a trusted test flow-control resolver (built onparticipant_crossing_fixtures.py,sem233_boundary_flow_model.py). Assert:InMemory,Local) preserve expected-head behavior and restart validation.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*.pystay 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 theverifynox session) all run at the completion boundary withRAES_REQUIREMENT_UID=RUN-319. PR title will be a valid Conventional Commitfeat:(consumer-visible runtime enforcement) passingtitle-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.
Brad-Edwards commentedon Aug 2, 2026
gc_codex_review — cycle 1 of 1 (pre-push) on issue #1003 (branch
1003-runtime-sink-flow-enforcement)Diff mode: inline — the complete diff was supplied in one prompt
Core review
Verdict:
ship-with-fixesThe change establishes a narrow SEM-233 enforcement seam at the existing RUN-319 crossing boundary and generally reuses the existing transaction, audit, and crossing machinery rather than inventing parallel infrastructure. That is the right shape, but the resolver result is treated as trusted beyond the validator: the runtime passes the actual sink kind into the resolver without binding the returned decision back to that sink coordinate, and its failure boundary is narrower than the declared fail-closed contract.
Blocking findings (2):
implementations/python/packages/raes_runtime/participant_flow_sink.py:159The runtime passes
sink_kindto the resolver but never verifies thatdecision.sink.sink_kindmatches it after validating the returned relation. A resolver can therefore return an otherwise valid permit for (for example)PARTICIPANT_OUTPUTwhile this call is about to admit anACTION_ARGUMENT; validation proves the relation is internally valid, not that it authorizes this concrete effect. Reject a decision unless its full applicable sink coordinate, at minimum its kind, is bound to the actual sink being invoked before committing or exposing the effect.implementations/python/packages/raes_runtime/participant_flow_sink.py:131The method promises that a resolver exception never leaks and never widens permission, but catches only four exception types. A resolver failure such as
RuntimeErroror an implementation-specific operational exception escapes this boundary instead of becoming the bounded non-permit decision required for a final-sink guard. Catch resolver failures at this boundary and convert them to the existing unresolved denial; preserve cancellation and process-control exceptions if the runtime has explicit handling for them.Security review
Verdict:
don't-shipThis change places the intended guard at the right operational seams—control ingress, action ingress, and egress serialization—and reuses the existing crossing transaction/audit flow. However, the central resolver treats SEM-233 as optional and fails to bind the validated permit to the actual sink being effected. That leaves the final-sink boundary dependent on resolver convention rather than enforced runtime invariants, foreclosing safe addition of further sink kinds.
Blocking findings (2):
implementations/python/packages/raes_runtime/participant_flow_sink.py:153The resolver result is validated as internally consistent, but the subsequent live binding checks participant, episode, history heads, and audience only. It never requires
decision.sink.sink_kind == sink_kind(nor otherwise proves the resolved decision is for this effect). An attacker able to invoke a participant-output path can receive a value if the configured resolver returns a valid permit for another sink with the same participant/audience/state cut, such as an action-argument sink. Passingsink_kindinto a resolver is not an enforcement boundary: a stale, overly broad, or incorrectly implemented resolver can ignore it while returning a fully validator-valid relation. Require exact equality between the resolved decision's sink coordinate and the concrete sink being executed before permitting the effect.implementations/python/packages/raes_runtime/participant_flow_sink.py:113A resolver that does not implement
resolve_flow_sink_decisioncauses this helper to returnNone, which every caller interprets as authorization to perform the effect. This makes final-sink enforcement silently absent for existing resolver deployments rather than fail closed. An attacker who can submit an otherwise API-423-authorized action/control request, or request an authorized projection, can reach the backend or receive serialized output without any SEM-233 final-sink decision whenever that deployment uses a legacy resolver. Missing enforcement capability must deny the final sink (or be rejected during resolver/control-plane configuration), rather than preserving the legacy permit path.Brad-Edwards commentedon Aug 2, 2026
gc_codex_review pre-push cycle 1 of 1 complete for issue #1003 on branch '1003-runtime-sink-flow-enforcement'. 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.Brad-Edwards commentedon Aug 2, 2026
Review decision record — codex cycle 1 (issue #1003)
Reviewer: codex
Cycle: 1
Architectural read:
Blocking findings: 4
Finding 1 —
one-offF1implementations/python/packages/raes_runtime/participant_flow_sink.py:159sink_kindto the resolver but never verifies thatdecision.sink.sink_kindmatches it after validating the returned relation. A resolver can therefore return an otherwise valid permit for (for example) `PARTICIPANT_OU…Finding 2 —
one-offF2implementations/python/packages/raes_runtime/participant_flow_sink.py:131RuntimeErroror an implementation-specific operational exception escapes this bounda…Finding 3 —
class(4 instances)F3implementations/python/packages/raes_runtime/participant_flow_sink.py:153decision.sink.sink_kind == sink_kind(nor otherwise proves the re…implementations/python/packages/raes_runtime/participant_flow_sink.py:153implementations/python/packages/raes_runtime/participant_crossing_boundary.py:134implementations/python/packages/raes_runtime/participant_crossing_boundary.py:228implementations/python/packages/raes_runtime/participant_crossing_egress.py:127Finding 4 —
class(4 instances)F4implementations/python/packages/raes_runtime/participant_flow_sink.py:113resolve_flow_sink_decisioncauses this helper to returnNone, which every caller interprets as authorization to perform the effect. This makes final-sink enforcement silently absent for existing resol…implementations/python/packages/raes_runtime/participant_flow_sink.py:113implementations/python/packages/raes_runtime/participant_crossing_boundary.py:134implementations/python/packages/raes_runtime/participant_crossing_boundary.py:228implementations/python/packages/raes_runtime/participant_crossing_egress.py:127Brad-Edwards commentedon Aug 2, 2026
gc_test_quality_review cycle 1 of 1 — issue #1003
Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch:
1003-runtime-sink-flow-enforcementCycle: 1 / 1
Findings: 1
Finding 1 — [critical]
implementations/python/tests/test_issue_1003_final_sink_flow_enforcement.py:41Problem:
_NON_PERMIT_TOGGLESexercises everyFlowSinkTogglesfield exceptreturn_non_resolution. That field exists specifically to driveSem233FlowSinkResolver.resolve_flow_sink_decisionto returnNone(a callable hook that doesn't raise, just returns the wrong type) — the exact caseresolve_participant_flow_sink_decision'sif not isinstance(resolution, ParticipantFlowSinkResolution): return _denied(...)guard (participant_flow_sink.py:140-141) exists to fail closed on. No test in this diff, and no test anywhere in the repo, calls the resolver with that toggle set or otherwise exercises that isinstance check.Why it matters: If that isinstance guard were deleted or weakened (e.g. changed to only check
is None, or removed so a malformed resolver return value falls through toresolution.relationattribute access), no current test would fail — every existing toggle produces a realParticipantFlowSinkResolutioninstance, valid or not. A regression here would either crash with an unhandled AttributeError (denial-of-service on the crossing boundary) or, worse, silently misbehave in a way that isn't fail-closed, and the security-outcome test (denied, zero backend dispatch, zero serialization) that would have caught it simply isn't run for this input class.Fix: Add a
pytest.param(FlowSinkToggles(return_non_resolution=True), id="resolver-returns-non-resolution")entry to_NON_PERMIT_TOGGLESin test_issue_1003_final_sink_flow_enforcement.py so it flows throughtest_non_permit_ingress_never_dispatches_backend,test_non_permit_egress_raises_and_serializes_nothing, andtest_non_permit_control_ingress_applies_no_transitionthe same as every other non-permit class.Brad-Edwards commentedon Aug 2, 2026
gc_test_quality_review cycle 1 of 1 complete for issue #1003 on branch '1003-runtime-sink-flow-enforcement'. Posted by the MCP server to enforce the gc_test_quality_review hard-cap-1 contract (issue #884 follow-up, default lowered in #906). Do not edit or delete — used by the next
gc_test_quality_reviewinvocation to count cycles.Brad-Edwards commentedon Aug 2, 2026
Review decision record — test-quality cycle 1 (issue #1003)
Reviewer: test-quality
Cycle: 1
Architectural read:
Blocking findings: 1
Finding 1 —
one-offF1feat: enforce participant flow policy at final runtime sinks
Brad-Edwards commentedon Aug 2, 2026
Ready for review — issue #1003
PR: #1058
Outcome
Every governed participant action or disclosure now resolves a fresh exact-cut SEM-233 final-sink permit immediately before the runtime dispatches to a backend or serializes a participant-visible value. The permit is validated, bound to the concrete sink kind and the live crossing decision, participant, audience, and history-head cut, and committed atomically before any effect. Any denied, missing, stale, unsupported, or mis-bound input or resolver failure yields zero dispatch and zero disclosure. Enforcement is fail-closed by default at the last controllable runtime point.
Files changed
Reviews
Traceability reconciliation
Status
feat: enforce participant flow policy at final runtime sinks (#1058)
Brad-Edwards commentedon Aug 2, 2026
gc workflow phase recorded:
traceability_reconciled(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 commentedon Aug 2, 2026
Final report — issue #1003 complete
PR: #1058
Outcome
Every governed participant action or disclosure now resolves a fresh exact-cut SEM-233 final-sink permit immediately before the runtime dispatches to a backend or serializes a participant-visible value. The permit is validated, bound to the concrete sink kind and the live crossing decision, participant, audience, and history-head cut, and committed atomically before any effect. Any denied, missing, stale, unsupported, or mis-bound input or resolver failure yields zero dispatch and zero disclosure. Enforcement is fail-closed by default at the last controllable runtime point.
In-scope requirements
SEM-233(Participant boundary information-flow semantics) — ACTIVERUN-319(Participant information-flow policy enforcement) — ACTIVERUN-310(Supervisory lifecycle transitions) — ACTIVEAPI-423(Participant crossing policy and evidence contracts) — ACTIVEAPI-407(Backend participant feature-support declaration) — ACTIVEFiles changed
Reviews
Traceability reconciliation
Status