Migrate participant I/O control semantics and existing carriers

[Brad-Edwards]

Requirements

• SEM-230
• API-423
• RUN-319

Bounded outcome

Provide the compatibility classification, staged migration, adapters, fixtures, and rollout guidance needed to adopt the participant-control boundary across existing scenarios, contracts, participant implementations, and backends without silently changing historical meaning.

Non-goals

• A flag-day replacement of action, observation, lifecycle, inject, or backend contracts.
• Automatic promotion of legacy records to stronger IFC or behavioral claims.
• Selecting a concrete participant gateway.

Dependencies

• Assess and design formal participant I/O control with information-flow and bisimulation semantics #794
• RUN-319 — Participant Information-Flow Policy Enforcement #799 (RUN-319)
• ASR-535 — Participant Information-Flow And Relation Assurance #800 (ASR-535)

Acceptance criteria

• Inventory every affected published carrier and authored/runtime surface and classify compatibility under ADR-061.
• Define legacy interpretation, opt-in and required phases, rejection and explicit downgrade behavior, rollback, and deprecation timing.
• Supply migration fixtures for legacy scenarios, histories, manifests, participant implementations, and backend profiles.
• Preserve source/result identity, markings, provenance, evidence, and loss during transformation.
• Update scientific-completeness delivery status only from shipped evidence.
• 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

• Before/after compatibility fixtures.
• Cross-version parser, schema, runtime, and conformance tests.
• Negative tests proving legacy absence cannot imply a stronger policy or relation.

Parent program: #794.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 802-migrate-participant-control, 2026-07-28T22:14:48.673Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #802). 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 #802). 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 #802). 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 #802). 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. Lock the compatibility contract and inventory. Keep the architecture preflight as the binding design note. Add a surface-specific migration guide under docs/migration/ that inventories every directly affected published carrier named by preflight, gives producer/consumer, direction and compatibility dimension, and defines legacy, opt-in, required, downgrade, rollback, and deprecation timing. Preserve the existing ADR-061/075/085/095 authorities; add no generic migration DTO, service, registry, policy bag, or schema.

2. Drive the API-408 adapter repair with failing tests. Add issue-802 tests proving that, when the existing crossing_policy_resolver seam is active, status/history/context HTTP reads pass the authenticated ControlPlaneIdentity, obtain crossing evidence from the trusted resolver rather than request headers/query values, enforce participant/audience binding before existence disclosure, record API-423 crossing history, and fail closed when trusted evidence is unavailable. Preserve legacy HTTP behavior when no positive participant-policy capability/resolver is selected. Reuse the existing crossing mediator, security identities, capability gates, diagnostics, operation/idempotency records, and redacted error handling.

3. Implement the narrow owning-boundary adapter seam. Extend ParticipantCrossingPolicyResolver with a trusted participant-view evidence resolution method and route all governed API-408 HTTP projections through it. Keep direct runtime projection APIs and all existing carrier models intact. Do not synthesize historical decisions, accept caller-authored policy/state-cut/audience/evidence, expose the assurance plane, or add route-specific legacy bypasses.

4. Add paired cross-version fixtures and compatibility tests. Under the existing fixture boundaries, add before/after cases for a legacy SDL scenario, runtime snapshot/history, backend manifest, participant implementation manifest, and backend profile. Validate each artifact with its exact incumbent parser/model/profile adapter. Assert source/result identity, markings, provenance, evidence, order, limitations, and disclosed loss are preserved; absence of API-423 history or API-407 support remains legacy/unknown/unsupported; environment injects are not inferred as participant-directed; decision-surface v1 is not field-renamed to v2; downgrade requires the existing policy/provenance gates; and no fixture promotes finite/structural success to noninterference or behavioral equivalence.

5. Document shipped lineage without claim inflation. Update the participant section of docs/explain/sdl/lineage.md with issue 802’s exact migration mappings, delivery evidence, status, and explicit nonclaims. Leave contracts/provenance/sdl-lineage-ledger-v1.json, its source audit, and the scientific-completeness assessment unchanged unless implementation actually changes normative external derivation or shipped assurance status; verify that decision in tests/review.

6. Verify and reconcile. Run focused issue-802 and affected RUN-319/API-408/backend-manifest/profile tests during TDD. Then run the required repository gates with RAES_REQUIREMENT_UID=SEM-230: implementations/python/.venv/bin/python tools/check_repo_policy.py, tools/check_requirement_governance.py, and tools/verify_all.py; Ground Control will run the canonical completion, policy, pre-commit, review, CI, and Sonar gates. No published schema is planned to change, so no schema-publication ledger edit is expected. After merge, reconcile IMPLEMENTS/TESTS links for SEM-230, API-423, and RUN-319.

[Brad-Edwards]

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

Core review

Verdict: ship-with-fixes

The change is mostly shaped around the correct incumbents: it preserves legacy snapshot meaning before model defaults, reuses the crossing mediator and existing manifest/profile adapters, and adds compatibility fixtures rather than inventing a migration envelope. The design seam is the new trusted participant-view evidence resolver, but that seam omits the authenticated audience binding even though audience is a policy coordinate. Consequently, it cannot correctly support the obvious next variation—multiple audiences with different egress policies—without another interface change.

Blocking findings (1):

1. [class] Trusted evidence resolution omits the authenticated audience — implementations/python/packages/raes_runtime/participant_crossing_mediation.py:140
   The new resolver receives the snapshot, participant, episode, interaction kind, and projection, but not the authenticated identity or the matched typed audience binding. The HTTP precheck confirms that some binding exists and then discards it, leaving the resolver unable to select audience-specific policy evidence when an identity has multiple bindings or two audiences have different disclosure policies. Pass the matched typed audience/subject binding through this interface and invocation, and add a test proving that two authenticated audiences resolve distinct evidence rather than relying on the resolver's global/default evidence.

Security review

Verdict: ship

This change is shaped correctly: participant-view HTTP routes perform an authenticated audience-candidate check before participant lookup, while final authorization and mediation remain at the shared serialization boundary using trusted server-side evidence. The resolver seam receives stable projection coordinates and interaction kinds, preserving the next rollout variation across participants and egress types without introducing caller-controlled policy inputs. The source-level snapshot-presence classifier also stays separate from materialized defaults, avoiding invented historical security claims. The change crosses authentication, policy resolution, projection serialization, append-only crossing persistence, and audit concerns without exposing a concrete new attack path.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #802 on branch '802-migrate-participant-control'. 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]

Review decision record — codex cycle 1 (issue #802)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: The change is mostly shaped around the correct incumbents: it preserves legacy snapshot meaning before model defaults, reuses the crossing mediator and existing manifest/profile adapters, and adds compatibility fixtures rather than inventing a migration envelope. The design seam is the new trusted participant-view evidence resolver, but that seam omits the authenticated audience binding even though audience is a policy coordinate. Consequently, it cannot correctly support the obvious next variation—multiple audiences with different egress policies—without another interface change.

Security reviewer: This change is shaped correctly: participant-view HTTP routes perform an authenticated audience-candidate check before participant lookup, while final authorization and mediation remain at the shared serialization boundary using trusted server-side evidence. The resolver seam receives stable projection coordinates and interaction kinds, preserving the next rollout variation across participants and egress types without introducing caller-controlled policy inputs. The source-level snapshot-presence classifier also stays separate from materialized defaults, avoiding invented historical security claims. The change crosses authentication, policy resolution, projection serialization, append-only crossing persistence, and audit concerns without exposing a concrete new attack path.

Blocking findings: 1

Finding 1 — class (3 instances)

• ID: F1
• Title: [core] Trusted evidence resolution omits the authenticated audience
• Location: implementations/python/packages/raes_runtime/participant_crossing_mediation.py:140
• Decision: fix
• Rationale: The new resolver receives the snapshot, participant, episode, interaction kind, and projection, but not the authenticated identity or the matched typed audience binding. The HTTP precheck confirms that some binding exists and then discards…
• Instances:
  • implementations/python/packages/raes_runtime/participant_crossing_mediation.py:140
  • implementations/python/packages/raes_runtime/participant_retrieval.py:354
  • implementations/python/packages/raes_runtime/control_plane_api_participant_retrieval.py:140