API-423 — Participant Crossing Policy And Evidence Contracts

[Brad-Edwards]

Requirements

• API-423

Bounded outcome

Publish portable participant-crossing policy-decision and evidence contracts that compose existing action, observation, lifecycle, intervention, inject, provenance, and evidence carriers.

Non-goals

• A transport protocol, payload bag, second participant carrier family, or runtime/backend realization.
• Duplicating action, observation, lifecycle, exposure, or intervention payloads.
• Encoding policy bodies in metadata.

Dependencies

• Assess and design formal participant I/O control with information-flow and bisimulation semantics #794
• SEM-230 — Participant Information-Flow And Control Semantics #796 (SEM-230)
• Participant Exposure And Visibility-Boundary Semantics (SEM-226) #296 (SEM-226 exposure)
• Participant External Input And Intervention Contracts (API-409) #252 (API-409 intervention contracts)
• DSL-142 — Participant-Directed Inject Binding And Delivery #797 (DSL-142 participant-directed injects)

Acceptance criteria

• Record participant/episode, direction and interaction kind, actor/controller/authority, action/projection/inject/intervention refs, order/time, policy identity/revision, markings, decision/disposition, transformation, disclosure/declassification/redaction, loss/weakening, backend posture, evidence, and provenance.
• Use typed refs to existing payload carriers and closed vocabularies; do not introduce a generic message DTO.
• Distinct records preserve requested, decided, transformed, delivered/attempted, observed, and audited facts.
• Publication ledger, schema bundle, fixtures, concept authority, compatibility, and all package consumers remain aligned.
• 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

• Contract/schema parity and valid/invalid fixtures.
• Round-trip, canonicalization, compatibility, and consumer tests.
• Negative tests for policy bags, raw secrets, unknown refs, contradictory decisions, and missing evidence.

Parent program: #794.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 798-participant-crossing-contracts, 2026-07-26T02:24:10.380Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #798). 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 #798). 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. Add participant-crossing-occurrence-v1 to the existing participant-runtime family. Reuse ParticipantRuntimeBaseEnvelopeModel unchanged and define one top-level occurrence per independently addressable request/candidate, decision, transformation, disclosure/declassification, delivery attempt, delivery, observation, or audit-retention fact. Each closed variant will carry the API-423 coordinates it owns: participant/episode, ingress or egress kind, actor/controller/authority, typed subject and predecessor refs, explicit order/time model, exact policy identity/revision/digest, markings, disposition, backend posture, evidence/provenance, and loss/weakening. No generic payload, message, metadata, policy-body, raw-secret, or backend-object field will be introduced.
2. Add one resolver-backed validate_participant_crossing_occurrence_context() seam, following the API-409 and SEM-220 validators. It will index typed incumbent subjects and policy revisions, reject unknown/stale/mismatched refs, reused identities, participant/episode disagreement, retroactive policy use, contradictory deny-first decisions, source mutation/transformation cycles, unauthorized marking weakening, unsupported required posture, realization without its owning fact, and unresolved required evidence. Local Pydantic/JSON Schema checks remain limited to closed shape, uniqueness, branch requiredness, and single-record invariants.
3. Publish the contract through schema_bundle() and tools/generate_contract_schemas.py; add the hand-governed schema, valid/invalid fixtures, and schema-publication entry with its content hash and last_change. Export the model/validator through raes_contracts.contracts, register structural validation where package consumers use the published bundle, and add controlled concept vocabulary entries/tests for the new direction, interaction, stage, disposition, operation, loss/weakening, and support terms without duplicating incumbent carrier vocabularies.
4. Add focused API-423 tests covering every stage, round-trip/canonical model parity, schema/bundle/publication compatibility, typed incumbent references, and resolver joins. Negative cases will cover policy/payload bags, raw-secret fields, unknown or stale refs, contradictory allow/deny gates, missing evidence, transformation identity reuse/cycles, retroactive policy revisions, marking weakening without declassification, and delivery/observation/audit claims without the owning occurrence.
5. Update the participant section of docs/explain/sdl/lineage.md with the adopted SEM-230/ADR-085 lineage, exact RAES artifact mappings, delivered model/schema/fixture evidence, and explicit nonclaims. Keep the normative lineage ledger and source audit unchanged because this composes already-adopted authorities and changes no derivation or compatibility claim. Retain the preflight design note as the architecture record; no new ADR is needed.
6. Include the one-line .ground-control.yaml compatibility repair discovered by the mandatory policy gate (routing.default_fallback is unsupported by the canonical validator). This changes no product behavior and restores the repository workflow context.

Whole-repository constraints

• Security: closed models and Draft 2020-12 schemas reject smuggling; the semantic validator fails closed; portable data contains only safe refs/digests/codes; diagnostics remain value-independent and bounded. API-423 adds no auth, HTTP, environment, secret-loader, filesystem, subprocess, socket, argv, persistence, or backend surface.
• Maintainability: reuse ContractModel, the shared envelope/primitives, _add_aces_invariant(), API-409/SEM-220 validator patterns, the canonical schema generator/publication ledger, and existing fixture/policy tooling. No second registry, validator stack, exception hierarchy, logger, or carrier family.
• Extensibility: the stable seam is a closed stage variant plus resolver-backed typed subject relation. A future carrier kind or streaming/partial-order realization adds a governed variant/resolver capability without changing existing carriers or opening a metadata bag.
• Verification: set ACES_REQUIREMENT_UID=API-423; run targeted API-423 and consumer tests, schema generation/publication/compatibility checks, then implementations/python/.venv/bin/python tools/check_repo_policy.py, tools/check_requirement_governance.py, tools/verify_all.py, and the pinned nox verify command. Do not edit the changelog, package version, or retired compatibility namespace. Keep Ground Control IMPLEMENTS/TESTS links aligned with changed code and tests.

[Brad-Edwards]

Execution obligation ISSUE-798-MISSING-POLICY-ENTRYPOINT — Opened

Category: workflow
Observed state: The API-423 implementation passes the configured full verification command, but the required standalone policy command is absent.
Impact: The mechanical completion and branch-synchronization gates cannot complete even though the configured Nox verification command passes.
Current obligation: Provide the required make policy repository entry point by delegating to the existing pinned canonical Nox policy session, then verify both policy and completion gates on the resulting tree.

Evidence

• make policy exited 2: No rule to make target 'policy'.
• The repository has no Makefile, while /implement Step 6 and synchronization require make policy.
• The canonical repository policy graph already exists as the pinned Nox policy session in noxfile.py.

[Brad-Edwards]

Execution obligation ISSUE-798-MISSING-POLICY-ENTRYPOINT — Resolved

Category: workflow
Observed state: The missing entry point has been repaired and both required gates pass.
Impact: The mechanical completion and synchronization workflows now have the required repository policy entry point.
Current obligation: Provide the required make policy repository entry point by delegating to the existing pinned canonical Nox policy session, then verify both policy and completion gates on the resulting tree.

Evidence

• make policy now exits successfully and all Nox policy stages pass.
• The configured full nox -s verify completion command passes on the same tree: 4,833 tests passed, 51 integration tests passed, 93% coverage, schema/contract/policy/lint/docs gates green.

Disposition: fix
Corrective action: Added a root Makefile policy target that delegates to the repository's existing pinned Nox policy session, preserving the single canonical verification graph.

Verification

• ACES_REQUIREMENT_UID=API-423 make policy
• ACES_REQUIREMENT_UID=API-423 uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s verify

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #798 (branch 798-participant-crossing-contracts)

Core review

Verdict: don't-ship

The overall shape is appropriate: a closed, discriminated occurrence family reuses the participant-runtime envelope, publishes through the existing schema and concept-authority surfaces, and centralizes cross-record joins in one resolver-backed validator. The design seam leaves room for additional carrier kinds and realization variants. However, that validator does not enforce semantic continuity between several stages or resolve stage-specific evidence references, so the contract currently accepts histories that contradict its advertised deny-first and stage-separation invariants.

Blocking findings (2):

1. [class] Stage transitions do not preserve the decision and outcome semantics — implementations/python/packages/raes_contracts/contracts/participant_crossing_validation.py:176
   The resolver establishes existence, shared coordinates, and ordering, but several successor branches do not validate the predecessor's exact semantic outcome. A transform decision requiring redaction can be realized by a different operation; disclosure can skip the transformation required by a transform decision; delivery can reference a withheld or unsupported attempt; observation can follow a delivery record whose disposition is failed, unknown, or unsupported; and delivery or observation can name a different same-coordinate decision from the one used by their predecessor. These histories pass the validator while contradicting the published stage-separation invariant. Bind every successor to the exact predecessor chain and require compatible decision operations and predecessor dispositions.
2. [class] Stage-specific evidence references are never resolved — implementations/python/packages/raes_contracts/contracts/participant_crossing.py:259
   The context validator checks only the envelope's evidence_refs. Request and decision required_evidence_refs and audit retained_evidence_refs are not checked against any resolver-owned registry, so nonexistent evidence requirements or retained evidence can pass contextual validation despite the contract's fail-closed evidence claim. Add the appropriate requirement and evidence indexes to the validation context and resolve every stage-specific collection.

Security review

Verdict: don't-ship

The closed, stage-discriminated occurrence family and centralized resolver-backed validator are the correct design seam for participant-crossing facts. However, the new seam does not enforce several security-critical relationships it claims to own: declassification authority is not resolved, required transformations can be altered or skipped, and realization references lose their participant and carrier scope. Because downstream consumers are expected to trust this validator’s accepted policy and evidence relations, these are security-boundary failures rather than contract-hardening opportunities.

Blocking findings (3):

1. [class] Attacker-supplied basis references authorize marking removal — implementations/python/packages/raes_contracts/contracts/participant_crossing.py:348
   Attacker model: a producer permitted to submit crossing records but not to declassify the underlying subject. Both transformation and disclosure validation allow source markings to be removed whenever declassification_basis_ref is any non-empty string. The context validator has no authoritative declassification-binding input and never resolves this reference, so an attacker can invent a basis, change a restricted marking to a public marking, and obtain a record that passes model and context validation. A downstream delivery path trusting that record could release protected content. Resolve the basis against an authoritative grant bound to the exact policy revision, participant, episode, audience, controller, operation, and effective order; require the decision’s declassification gate to permit; and allow marking removal only for the authorized declassification operation.
2. [class] Required security transformations can be changed or skipped — implementations/python/packages/raes_contracts/contracts/participant_crossing_validation.py:178
   Attacker model: a producer receives a transform decision requiring a protective operation such as redaction. The transformation branch verifies only that the decision disposition is transform; it never checks that the submitted transformation operation equals decision.required_operation. The producer can therefore substitute a weaker operation and proceed to a delivery attempt. Separately, the disclosure branch treats the same transform decision as sufficient permission when transformation_ref is absent, allowing disclosure of the original subject without any transformation. Enforce exact equality between the decision’s required operation and the transformation occurrence, and require the validated transformation predecessor on every disclosure or realization path consuming a transform decision.
3. [class] Bare reference resolution permits cross-scope realization claims — implementations/python/packages/raes_contracts/contracts/participant_crossing_validation.py:299
   Attacker model: a producer can submit a crossing fact while the resolver contains subjects from multiple participants, episodes, or carrier kinds. _resolve_external_ref accepts an owning occurrence or observation when any known subject has the same bare subject_ref; it ignores subject kind, contract, participant address, and episode. An attacker who knows or guesses another scope’s reference—or selects an unrelated known carrier—can therefore validate a delivery or observation as being backed by that object, forging security-relevant realization evidence and creating a cross-tenant linkage. Replace the string-only fields with typed references or resolve them using the expected carrier kind and the current record’s participant and episode scope.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #798 on branch '798-participant-crossing-contracts'. 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.