Document participant I/O control authoring, operations, and claim boundaries

[Brad-Edwards]

Requirements

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

Bounded outcome

Publish author, participant-implementation, runtime-operator, backend-implementor, and researcher guidance for the adopted participant-control model after implementation and migration ship.

Non-goals

• Defining semantic authority in explanatory prose.
• Claiming universal noninterference, equivalence, or bisimulation from examples or conformance runs.
• Duplicating normative contracts or the relation catalog.

Dependencies

• Assess and design formal participant I/O control with information-flow and bisimulation semantics #794
• Migrate participant I/O control semantics and existing carriers #802 (migration)
• ASR-535 — Participant Information-Flow And Relation Assurance #800 (ASR-535)

Acceptance criteria

• Explain participant-relative world/view/history, ingress/egress decisions, mixed control, participant-directed injects, transformations, backend support, and failure/downgrade behavior.
• Provide examples for denial, withholding, redaction, declassification, intervention, inject delivery, and unsupported capability.
• Provide a claim-selection guide distinguishing noninterference, projected-history equality, trace inclusion, simulation, refinement, bisimulation, and bounded evidence.
• Link examples to normative authority and update the participant-control index and scientific-completeness documentation.
• 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

• Sphinx link/build checks.
• Executable example validation where examples carry contracts.
• Behavioral-relation claim policy and documentation coverage checks.

Parent program: #794.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 803-participant-control-guidance, 2026-07-29T02:38:18.568Z.

[Brad-Edwards]

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

Scope and authority

Implement issue #803 as a documentation-only explanation of the already delivered SEM-230, API-423, RUN-319, API-407, API-409, DSL-142, ASR-535, and issue #802 surfaces. The normative authorities remain ADR-085/095, specs/formal/participant-semantics/information-flow-control.md, the API-423 contract/schema/context validator, and raes-behavioral-relations@rev4. Do not change runtime behavior, schemas, capability declarations, the scientific-completeness assessment status, the lineage ledger, or the source audit.

Test-first executable documentation

1. Extend the existing public-documentation example suite with a focused failing test for a claim-bearing example in the new guide.
2. Extract the example from the hosted Markdown, validate it with BehavioralClaimBindingModel and validate_behavioral_claim_binding(), and assert that it reports only bounded-probe-success over named finite cases with finite evidence, tested assurance, limitations, and explicit stronger-relation nonclaims.
3. Add that test node to PUBLIC_DOCS_EXAMPLE_TESTS so the canonical docs workflow executes it. Confirm the test fails before the guide exists, then implement to green. This reuses the existing governed claim contract and does not add a documentation schema or parser.

Hosted role-routed guidance

4. Add one task-oriented page at docs/public/participant-control.md, reachable from docs/public/index.md, for scenario authors, participant-implementation authors, runtime operators, backend implementors, and researchers.
5. Link stable repository authorities instead of copying normative definitions. Keep world truth, participant view, participant-visible history, and archival/audit evidence separate; distinguish request, decision, transformation, disclosure, attempted delivery, delivery, observation, and audit.
6. Explain ingress/egress decisions, mixed control, participant-directed injects, transformations/interventions, API-407 support selection, fail-closed behavior, policy-authorized downgrade, and asymmetric rollback. Preserve separate authentication, target, participant/controller, audience, admission, visibility, marking, declassification, transformation, and backend-support gates.
7. Provide bounded examples for denial, withholding, redaction, governed declassification, intervention/transformation, participant-directed inject delivery, and unsupported capability. Each example names its evidence layer, expected side effects, canonical owner/evidence, and nonclaim. Preserve current limits: RUN-319 does not emit a distinct withhold disposition; the finite declassification case drives projection; inject delivery does not yet bind the compiled DSL-142/DSL-111 identity; the reference backend declares all six policy features unsupported; legacy API-408 retrieval without a resolver is not governed egress.
8. Add a claim-selection guide using exact rev4 relation ids for bounded probe success, projected-history equality, policy noninterference, trace inclusion, forward/backward simulation, data refinement, and strong/weak bisimulation. State direction, projection/quantifier obligations, evidence boundary, and explicit nonclaims without claiming any unproved universal relation.

Repository navigation and evidence views

9. Update docs/research/participant-io-control/index.md from design-only wording to a current adoption/navigation index linking the hosted guide, normative authority, delivered implementation/migration, finite assurance, and remaining limitations.
10. Update docs/explain/sdl/scientific-scenario-completeness.md to describe the shipped participant-control evidence and correct the explanatory taxonomy revision to rev4 while retaining the canonical participant-action-observation status as partial and promoting no profile.
11. Append issue Document participant I/O control authoring, operations, and claim boundaries #803 to docs/explain/sdl/lineage.md with adopted lineage, exact documentation/implementation/evidence mapping, delivery status, and nonclaims. Leave the lineage ledger and source audit unchanged because no derivation or compatibility claim changes.
12. Retain the architecture preflight note as the decision record for the documentation boundary.

Cross-cutting verification

13. Run the focused public-example test and nearby public-doc policy tests, behavioral-relation claim policy, authority/project-positioning checks, scientific-completeness check, lineage check, requirement governance with RAES_REQUIREMENT_UID=RUN-319, Vale, Sphinx warning-strict HTML, public output inventory, and linkcheck.
14. Run the repository’s canonical full mechanical verifier, then the required implementation and test-quality review cycles. Address findings without adding duplicate DTOs, validators, registries, stores, loggers, exception families, configuration, secrets, processes, or workflow branches.
15. Record clause-level evidence for SEM-230, API-423, RUN-319, issue acceptance criteria, security, maintainability, extensibility, and whole-repository fit; publish traceability, commit, open the PR against dev, monitor CI, and stop at merge readiness for the user’s approval.

[Brad-Edwards]

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

Core review

Verdict: ship

This is shaped correctly: it adds role-routed explanatory guidance while preserving the existing authority seams—ADR-085/SEM-230 for semantics, API-423 for crossing facts, RUN-319 for runtime behavior, API-407 for capability declarations, and ASR-535 for bounded evidence. The documentation consistently distinguishes shipped finite evidence from unsupported backend capabilities and stronger formal claims, and the executable example validates the published claim through the canonical contract model and validator rather than creating a parallel documentation schema. The change leaves the obvious next variation—additional supported capabilities or stronger assurance states—to the existing contracts and catalogs rather than foreclosing it in prose.

No blocking findings.

Security review

Verdict: ship

This is shaped correctly as a documentation and contract-example change: it updates participant-control guidance, navigation, lineage, and research status while adding a fixed-path test that parses the embedded JSON example through the existing typed model and behavioral-claim validator. The change does not alter runtime request handling, authorization boundaries, repository scoping, secret processing, dynamic execution, or user-controlled file access, and it preserves the documented seam between explanatory guidance and normative contracts. I found no concrete, exploitable security issue introduced by this diff.

No blocking findings.

[Brad-Edwards]

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

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: This is shaped correctly: it adds role-routed explanatory guidance while preserving the existing authority seams—ADR-085/SEM-230 for semantics, API-423 for crossing facts, RUN-319 for runtime behavior, API-407 for capability declarations, and ASR-535 for bounded evidence. The documentation consistently distinguishes shipped finite evidence from unsupported backend capabilities and stronger formal claims, and the executable example validates the published claim through the canonical contract model and validator rather than creating a parallel documentation schema. The change leaves the obvious next variation—additional supported capabilities or stronger assurance states—to the existing contracts and catalogs rather than foreclosing it in prose.

Security reviewer: This is shaped correctly as a documentation and contract-example change: it updates participant-control guidance, navigation, lineage, and research status while adding a fixed-path test that parses the embedded JSON example through the existing typed model and behavioral-claim validator. The change does not alter runtime request handling, authorization boundaries, repository scoping, secret processing, dynamic execution, or user-controlled file access, and it preserves the documented seam between explanatory guidance and normative contracts. I found no concrete, exploitable security issue introduced by this diff.

Blocking findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #803

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 803-participant-control-guidance
Cycle: 1 / 1
Findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 complete for issue #803 on branch '803-participant-control-guidance'. 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_review invocation to count cycles.

[Brad-Edwards]

Review decision record — test-quality cycle 1 (issue #803)

Reviewer: test-quality
Cycle: 1

Architectural read:

This diff adds one test, test_participant_control_claim_example_is_bounded, to an existing docs-boundary policy suite. It follows the file's established idiom exactly (regex-extract a fenced block between HTML comment markers, parse it, assert on the parsed object — the same shape as the neighboring test_readme_quickstart_matches_checked_in_scenario). Crucially, it round-trips the doc's embedded JSON example through the real production validator (BehavioralClaimBindingModel.model_validate_json + validate_behavioral_claim_binding against the live catalog), not a mock, and then pins down the specific field values (relation id, finite/tested scope, the full seven-case evidence boundary, and the two required non-claims about noninterference and bisimulation) that make this example a bounded rather than an overclaiming assurance statement. That is exactly the property the surrounding participant-control.md guide is trying to guard — catching both doc/catalog drift (wrong taxonomy revision, removed relation) and doc self-drift (someone silently weakening or strengthening the claim text without updating the JSON, or vice versa). The seam is correct: this is a documentation-fixture regression test, not a claim about validate_behavioral_claim_binding's own correctness, and that narrower behavior is already covered by dedicated negative-case tests in test_behavioral_relation_claims.py (unbound-claim rejection, universal-scope promotion rejection). I would ship this as-is.

Blocking findings: 0 (clean run)