Define control-plane and participant-access trust boundaries

Administrative credentials can read both participant projections and full snapshots. This is unsafe if those credentials are also used as participant-view credentials; the deployment boundary is currently unclear.

Acceptance criteria

Inventory public runtime entry points and credentials, including snapshot, projection, operation, history, error, and event access. Specify who may use each surface and where authorization is enforced.
Decide whether participant clients access RAE directly or through a backend boundary. Specify the required principal, audience, participant, and episode bindings for the selected exposure model.
Cover alternate retrieval and mutation paths, cached/readback results, and cross-participant access. Authentication principals do not require new SDL participant declarations or roles.
Publish the accepted trust-boundary decision, route/authority matrix, deployment requirements, and affected API-404/ADR-104 clauses. Keep organizational identity and policy responsibilities with the backend.

References: Diagnosis, Control-plane authorization, Ecosystem responsibilities.

Requirements

API-404 — Secure, Durable, And Idempotent Control-Plane Semantics

🛠️ Picked up by /implement - driver codex, branch 1356-control-plane-participant-boundary, 2026-09-24T01:11:29.276Z.

gc workflow phase recorded: preflight (issue #1356). 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.

gc workflow phase recorded: plan (issue #1356). 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.

Scope and decision

API-404 is in scope because this issue narrows its served-transport interpretation. Select backend-mediated participant access. RAE P2 identities remain privileged target-bound service identities; a participant/audience binding on one view does not restrict the same identity's snapshot route. The organizational backend owns user/session authentication, entitlement, run/participant/episode/audience/operation binding, credential custody, and the final release decision.

Acceptance criteria and implementation

Entry points and credentials — Path D (design contract). Inventory every current P2 route family, in-process/store access, health/OpenAPI, operation readback, raw event/audit paths, errors, and cached results in the issue-1356 decision. State the existing FastAPI role dependency, core authorization where present, and the permitted service/operator consumer. Cross-check against control_plane_api/_auth.py, route registrations, control_plane.py, and control_plane_api_participant_retrieval.py.
Exposure and bindings — Path D. Record backend mediation in ADR-104 §7 and API-404-C3. Require backend user/session, target/run, participant, exact episode, audience, and operation bindings for each release. Require a configured API-423/RUN-319 crossing resolver for participant-facing retrieval; the legacy ungoverned projection path is not deployment evidence.
Alternate paths and isolation — Path D. Cover mutation receipts, idempotent replay, polling, direct store/in-process reads, histories, diagnostics, errors, events, callbacks, conditional responses, and caches. Reauthorize at every release and reject cross-participant, cross-episode, stale-policy, and stale-state reuse. Keep SDL participant declarations separate from authentication principals.
Publication — Path D. Keep the accepted decision and route/authority/deployment matrix in docs/decisions/issue-1356-control-plane-participant-access-preflight.md; amend ADR-104 and its pin/index, API-404, and runtime architecture guidance. Reconcile API-404 DOCUMENTS traceability.

Repository fit and limits

Security layers: reuse ControlPlaneSecurityConfig, _ControlPlaneApiAuth, request-size and redacted-error guards, API-408/API-423 projection and crossing validators, actor-scoped idempotency/readback, the P1 store lease, and the one mutation authority. No client-supplied route selector or service token grants backend entitlement. The deployment keeps P2 on a private service network with protected credentials, one worker, TLS/proxy identity stripping, and private store paths. Maintainability: reuse these incumbents without another principal, DTO, store, or policy engine. Extensibility: the backend-to-RAE adapter is the seam for a later route-scoped credential or participant-safe transport. Whole-repo impact includes the ADR index, requirement traceability, runtime architecture guidance, policy checks, and the existing HTTP/crossing tests. This design makes no new runtime guarantee, organizational backend implementation, SDL role, published schema, or P3 claim.

Verification

Review the matrix against the registered routes and current role dependencies. Run targeted ADR pin/amendment, local-link, repository policy, and whitespace checks plus focused existing HTTP authorization/crossing cases. Full verification remains in CI. Set RAES_REQUIREMENT_UID=API-404 for policy and publish gates because the issue branch has no UID. The documentation-only TDD carve-out is not asserted for organizational backend obligations: this repository has no backend deployment or entitlement implementation whose behavior could be tested here. The decision states that deployment requires separate backend-boundary evidence before participant access is enabled.

gc_codex_review — sanitized deferred publication for issue #1356, cycle 1 of 1
Reviewed revision: 51d27ad85fed05089755811373a14db1d1b8439f47523b904252e700ded53e08

Architectural read

Backend-mediated participant access preserves the privileged P2 service boundary, governed projection carriers, and existing mutation authority. No new runtime authorization guarantee is claimed.

Verdict: ship

Notes

The accepted trust-boundary design has no new runtime enforcement. Align the two issue-1356 API-404 traceability links with design evidence as DOCUMENTS.

Findings

(none)

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

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

Reviewer: codex
Cycle: 1
Verdict: ship

Architectural read:

Backend-mediated participant access preserves the privileged P2 service boundary, governed projection carriers, and existing mutation authority. No new runtime authorization guarantee is claimed.

Blocking findings: 0 (clean run)

Notes (non-blocking, no decisions):

The accepted trust-boundary design has no new runtime enforcement. Align the two issue-1356 API-404 traceability links with design evidence as DOCUMENTS.

Pre-PR base synchronization

Source: refs/remotes/origin/dev at b00aba06389ab75ffac3b3bdbd026a0dbecac487
Outcome: already_current
Published feature head: 45569dbc78a277eb9acd088dbe86f0fba37d58a3
Synchronized tree: 0d7bf2c7fd1f01f1a33220f710da5ef7892e3fdf

Pre-PR base synchronization

Source: refs/remotes/origin/dev at b00aba06389ab75ffac3b3bdbd026a0dbecac487
Outcome: already_current
Published feature head: bc7d7981cda25e2ae905c8658e0ac89092be6149
Synchronized tree: 73e37a9429903394975f4c3fe717eeeaa6e18bbe

Ready for review — issue #1356

PR: #1386
Plan: #1356 (comment)

Outcome

Participant-facing deployments now have a documented backend boundary: service credentials stay private, and each participant response requires backend entitlement and governed RAE projection. Operators have a route and deployment matrix for checking snapshots, readback, histories, errors, events, and caches.

In-scope requirements

Proposed state in this PR — authoritative only after merge.

API-404 (Secure, Durable, And Idempotent Control-Plane Semantics) — ACTIVE (proposed) — Participant-access boundary clarified; existing runtime profile guarantees unchanged.

Files changed

Added:

docs/decisions/issue-1356-control-plane-participant-access-preflight.md

Modified:

docs/decisions/adrs/adr-104-runtime-control-plane-architecture.md
docs/decisions/adrs/adr-index.yaml
docs/explain/sdl/runtime-architecture.md
docs/requirements/API-404/requirement.md
tools/policy/historical_identity_records.json

Reviews

codex: Pre-push review shipped with no findings; design traceability labels aligned to documentation evidence.

Traceability reconciliation

Proposed in this PR — verified against the merged tree in Phase E.

IMPLEMENTS / TESTS / DOCUMENTS added: 2
Links updated: 0
Stale links removed: 0

Status

CI: ✅ green
SonarCloud: ✅ passed
PR ready for user review and merge. Phase E validates the merged requirement state, posts the final report, and closes the issue automatically once this PR merges.

Delivery readiness recorded — Phase E finalizes issue #1356 automatically when PR #1386 merges.

Final report — issue #1356 complete

PR: #1386
Plan: #1356 (comment)

Outcome

Participant-facing deployments now have a documented backend boundary: service credentials stay private, and each participant response requires backend entitlement and governed RAE projection. Operators have a route and deployment matrix for checking snapshots, readback, histories, errors, events, and caches.

In-scope requirements

Verified at merge revision 492a613dacca.

API-404 (Secure, Durable, And Idempotent Control-Plane Semantics) — ACTIVE — Participant-access boundary clarified; existing runtime profile guarantees unchanged.

Files changed

Added:

docs/decisions/issue-1356-control-plane-participant-access-preflight.md

Modified:

docs/decisions/adrs/adr-104-runtime-control-plane-architecture.md
docs/decisions/adrs/adr-index.yaml
docs/explain/sdl/runtime-architecture.md
docs/requirements/API-404/requirement.md
tools/policy/historical_identity_records.json

Reviews

codex: Pre-push review shipped with no findings; design traceability labels aligned to documentation evidence.

Traceability reconciliation

IMPLEMENTS / TESTS / DOCUMENTS added: 2
Links updated: 0
Stale links removed: 0

Existing implementation and test links retained; no new runtime authorization claim.

Status

CI: ✅ green
SonarCloud: ✅ passed
PR ready for user review and merge.

gc workflow phase recorded: plan (issue #1356). 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.

Revised issue 1356 plan

The merged decision describes an organizational backend and an RAE credential as universal. That is inaccurate for P0/P1 SDK compositions and obscures where access is actually enforced. This continuation corrects the accepted contract on the same issue branch.

Acceptance mapping

Entry points and credentials (Path D). Split the inventory into P0/P1 direct Python methods, P2 HTTP routes, and store/maintenance access. State that P0/P1 have no RAES transport credential and that privileged object access is controlled by the embedding application. State that P2 has only deployment-configured bearer tokens or verified proxy identities; strict defaults grant none. Pin the actual role/target/audience checks and the full-snapshot privilege of P2 read roles.
Exposure decision and bindings (Path D). Define the trusted host as the application embedding RAES (for example, LilRAE or BigRAE), or the service calling optional P2. Participant-facing clients use that host's product boundary. BigRAE retains organizational IAM/policy, while local hosts own their own caller boundary. Require the host to bind its caller to target/run, participant, exact episode, audience and operation before release. Do not imply a separate server, an SDK token, or an SDL role.
Alternate paths and actual enforcement (Path D). Distinguish an enforced RAE check from a host/deployment obligation for snapshots, operation IDs, retries, caches, histories, errors, events, direct SDK calls and governed/legacy projections. Explicitly state that RAE does not stop an untrusted holder of the RuntimeControlPlane object or a P2 read identity from using privileged reads, and that the no-resolver legacy path still exists.
Publication (Path D). Revise the issue-1356 decision, ADR-104 §7, API-404 C1/C3 interpretation, runtime architecture guide, ADR amendment/index, and content-bound policy hash. Preserve existing requirement traceability and profile nonclaims.

Verification

Cross-check prose against control_plane.py, participant_retrieval.py, control_plane_api/_auth.py, route registration, and ControlPlaneSecurityConfig. Run focused existing tests for strict defaults, governed projection, actor-bound readback, and the shared P2 read privilege; run ADR pin, identity-cutover, file-local policy, links and whitespace checks. The change states deployment obligations honestly and introduces no runtime enforcement guarantee or new credential. CI owns broad suites. Set RAES_REQUIREMENT_UID=API-404 on the issue branch.

Pre-PR base synchronization

Source: refs/remotes/origin/dev at 492a613dacca839fbd8fd6aba34b2bca076b6e4b
Outcome: already_current
Published feature head: f78250cecc89a1b81ccfdda41c2375f1cecebbc9
Synchronized tree: e8c881a0f3c3260ebeffdd8248a6e0f897876605

Ready for review — issue #1356

PR: #1387
Plan: #1356 (comment)

Outcome

Participant access is now documented for both local SDK hosts and services using the optional HTTP adapter. The decision identifies what RAE actually checks and what the host must enforce before releasing participant views.

In-scope requirements

Proposed state in this PR — authoritative only after merge.

API-404 (Secure, Durable, And Idempotent Control-Plane Semantics) — ACTIVE (proposed) — Corrected participant-access interpretation in C1 and C3; no new runtime guarantee.

Files changed

Modified:

docs/decisions/issue-1356-control-plane-participant-access-preflight.md
docs/decisions/adrs/adr-104-runtime-control-plane-architecture.md
docs/decisions/adrs/adr-index.yaml
docs/requirements/API-404/requirement.md
docs/explain/sdl/runtime-architecture.md
tools/policy/historical_identity_records.json

Reviews

Codex: The earlier version used the issue's one pre-push review cycle. This follow-up proceeded at the cap under the user's instruction; its diff was manually checked and targeted checks passed.

Traceability reconciliation

Proposed in this PR — verified against the merged tree in Phase E.

IMPLEMENTS / TESTS / DOCUMENTS added: 0
Links updated: 1
Stale links removed: 0

Status

CI: ✅ green
SonarCloud: ✅ passed
PR ready for user review and merge. Phase E validates the merged requirement state, posts the final report, and closes the issue automatically once this PR merges.

Delivery readiness recorded — Phase E finalizes issue #1356 automatically when PR #1387 merges.

Final report — issue #1356 complete

PR: #1387
Plan: #1356 (comment)

Outcome

Participant access is now documented for both local SDK hosts and services using the optional HTTP adapter. The decision identifies what RAE actually checks and what the host must enforce before releasing participant views.

In-scope requirements

Verified at merge revision cbb596074be3.

API-404 (Secure, Durable, And Idempotent Control-Plane Semantics) — ACTIVE — Corrected participant-access interpretation in C1 and C3; no new runtime guarantee.

Files changed

Modified:

docs/decisions/issue-1356-control-plane-participant-access-preflight.md
docs/decisions/adrs/adr-104-runtime-control-plane-architecture.md
docs/decisions/adrs/adr-index.yaml
docs/requirements/API-404/requirement.md
docs/explain/sdl/runtime-architecture.md
tools/policy/historical_identity_records.json

Reviews

Codex: The earlier version used the issue's one pre-push review cycle. This follow-up proceeded at the cap under the user's instruction; its diff was manually checked and targeted checks passed.

Traceability reconciliation

IMPLEMENTS / TESTS / DOCUMENTS added: 0
Links updated: 1
Stale links removed: 0

Existing API-404 DOCUMENTS links to issue #1356 and its decision note remain valid; no new IMPLEMENTS or TESTS claim.

Status

CI: ✅ green
SonarCloud: ✅ passed
PR ready for user review and merge.

Define control-plane and participant-access trust boundaries #1356

Description

Acceptance criteria

Requirements

Activity

Brad-Edwards commented on Sep 24, 2026

Brad-Edwards commented on Sep 24, 2026

Brad-Edwards commented on Sep 24, 2026

Brad-Edwards commented on Sep 24, 2026

Scope and decision

Acceptance criteria and implementation

Repository fit and limits

Verification

Brad-Edwards commented on Sep 24, 2026

Architectural read

Notes

Findings

Brad-Edwards commented on Sep 24, 2026

Brad-Edwards commented on Sep 24, 2026

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

Brad-Edwards commented on Sep 24, 2026

Pre-PR base synchronization

Brad-Edwards commented on Sep 24, 2026

Pre-PR base synchronization

Brad-Edwards commented on Sep 24, 2026

Ready for review — issue #1356

Outcome

In-scope requirements

Files changed

Reviews

Traceability reconciliation

Status

Brad-Edwards commented on Sep 24, 2026

github-actions commented on Sep 25, 2026

Final report — issue #1356 complete

Outcome

In-scope requirements

Files changed

Reviews

Traceability reconciliation

Status

Brad-Edwards commented on Sep 25, 2026

Revised issue 1356 plan

Acceptance mapping

Verification

Brad-Edwards commented on Sep 25, 2026

Pre-PR base synchronization

Brad-Edwards commented on Sep 25, 2026

Ready for review — issue #1356

Outcome

In-scope requirements

Files changed

Reviews

Traceability reconciliation

Status

Brad-Edwards commented on Sep 25, 2026

github-actions commented on Sep 25, 2026

Final report — issue #1356 complete

Outcome

In-scope requirements

Files changed

Reviews

Traceability reconciliation

Status

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions