Participant Episode, Reset, And Termination Semantics (SEM-222)

[Brad-Edwards]

SEM-222 | FUNCTIONAL | MUST | Wave TBD | DRAFT

Statement

The ecosystem shall define explicit semantics for participant episode boundaries, initialization, reset behavior, completion, timeout, truncation, interruption, and other termination outcomes.

Status

Implementation issue. Joint design #122 is merged (design artifact specs/formal/participant-episode-model/README.md, PR #1055); this issue implements the SEM-222 executable ownership from that design: episode/termination semantic gates, the RL termination/truncation closure record, and invariant-oracle coverage, bound to the ADR-013 ParticipantEpisode* contract surface. CI branch UID: SEM-222.

Requirements

• SEM-222

---

Tracks Ground Control requirement SEM-222

[Brad-Edwards]

🛠️ Picked up by /implement - driver claude, branch 305-sem-222-episode-termination, 2026-08-02T16:33:00.630Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #305). 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 #305). 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 — SEM-222 Participant Episode, Reset, And Termination Semantics

Executable child of the merged joint design specs/formal/participant-episode-model/README.md (issue #122 / PR #1055). Per the child-issue mapping, #305 owns episode/termination semantic gates, the RL termination–truncation closure record, and invariant-oracle coverage, bound to the ADR-013 ParticipantEpisode* contract surface. Architecture preflight (comment above) added no ADR/design change and confirmed this scope.

What already exists (reuse, do not duplicate)

• ADR-013 contract surface — raes_contracts/participant_episode.py: ParticipantEpisode{Status,TerminalReason,ControlAction,HistoryEventType}, the terminal-event→reason / control-event→action maps, ParticipantEpisodeExecutionState / ParticipantEpisodeHistoryEvent with full type/status/sequence validators. Published Pydantic contracts + schemas: contracts/participant_runtime.py (ParticipantEpisodeStateModel, ParticipantEpisodeHistoryEventModel) → contracts/schemas/control-plane/participant-episode-{state-envelope,history-event-stream}-v1.json.
• Reset generation + lineage + terminal-reason consistency (EBM-02/03/08 enforcement) already live in raes_contracts/participant_episode_snapshot.py (iter_participant_episode_snapshot_violations: monotonic sequence, reset/restart-only advance, episode_id stability within a generation, result↔history-head reconciliation incl. terminal-reason match) and are wired into runtime validation via raes_runtime/participant_result_contracts.py.

SEM-222's job is therefore not to re-implement those gates but to (a) add the greenfield closure record (EBM-10), (b) prove the episode-facet EBM invariants with an executable oracle, and (c) reconcile governance (coverage row, assurance-fulfillment, traceability).

Greenfield: RL termination–truncation closure record (EBM-10 / formal invariant I28)

Fills ADR-054 (:279 per-participant termination/truncation signals kept separate from the ACES episode terminal reason) and the formal invariant I28 (specs/formal/participant-runtime/README.md:4159). Absent an explicit closure record, an RL/game termination/truncation step signal and the ADR-013 episode terminal reason stay unrelated coordinates.

• Typed contract raes_contracts/participant_episode_closure.py: frozen dataclass ParticipantEpisodeClosureRecord carrying record_schema_version, participant_address, episode_id, sequence_number (episode generation), source_signal (governed discriminator: rl_termination | rl_truncation), mapped_terminal_reason (ParticipantEpisodeTerminalReason), deriving_authority, evidence_refs (tuple of non-empty refs), derived_at. from_payload/to_payload + __post_init__ type/shape validation (closed shape; no free-form blob). Governed source_signal uses a ParticipantEpisodeClosureSignal(str, Enum) so future signal kinds extend the catalog, not the schema shape (extensibility seam from preflight).
• Fail-closed validation helper iter_participant_episode_closure_violations(closure_records, participant_episode_results, participant_episode_history) (episode-snapshot-iterator style, (address, message) tuples): each closure record must resolve to an existing (participant_address, episode_id, sequence_number) history head; mapped_terminal_reason must equal the head's realized terminal reason; a closure record may only relate a terminal head that actually exists — it can never assert a terminal fact absent from history, mutate a historical terminal fact, or cross episode/generation. Stale, future, cross-episode, cross-generation, ambiguous, or unmapped signals fail closed. Signal→reason mapping is explicit and evidence-bearing (rl_termination→completed, rl_truncation→truncated) — never inferred from a done-style flag, objective/scenario outcome, or backend process state.
• Runtime diagnostics wrapper participant_episode_closure_contract_diagnostics(...) in raes_runtime/participant_result_contracts.py, wrapping violations as runtime.backend-contract-invalid diagnostics — the same seam as participant_episode_contract_diagnostics, the design's "runtime episode validation" enforcement point. No new RuntimeSnapshot field, no persistence redesign, no endpoint (preflight non-goals): the helper validates closure records supplied to it, matching SEM-222's semantic (not RUN-realization) scope.
• Published portable schema (the record is evidence-bearing and portable — the requirement's rationale): ParticipantEpisodeClosureRecordModel(ContractModel) in contracts/participant_runtime.py; register "participant-episode-closure-record-v1": ...model_json_schema() in _runtime_schema_bundle() (contracts/bundle.py:239); add PARTICIPANT_EPISODE_CLOSURE_RECORD_SCHEMA_VERSION to versions.py; export via contracts/{__init__,_exports}.py; regenerate contracts/schemas/control-plane/participant-episode-closure-record-v1.json with tools/generate_contract_schemas.py; add the contracts/schema-publication/entries/participant-episode-closure-record-v1.json ledger entry (stability draft, content_hash, last_change). tools/check_generated_schemas.py then confirms generator↔schema parity.
• Fixtures: contracts/schemas/control-plane/valid/… (backend truncation mapped via closure record) and .../invalid/… (open/extra-field payload; missing evidence refs).

Invariant-oracle coverage (fulfils the waived property_based_or_differential_tests + unit_tests)

implementations/python/tests/test_sem_222_episode_termination_oracle.py, modelled on test_participant_semantics_invariant_oracle.py:

• A test-local episode-progression model (generations of ParticipantEpisodeExecutionState, an ordered ParticipantEpisodeHistoryEvent stream, and ParticipantEpisodeClosureRecords) with a canonical_progression() positive control.
• One predicate + one targeted mutation factory per SEM-222-owned EBM invariant — EBM-02 (four terminal reasons distinct; truncation not aliased to timeout/exhaustion/cancellation/backend-failure/workflow-completion), EBM-03 episode facet (reset/restart ⇒ new generation + previous_episode_id, history never rewritten), EBM-06 episode facet (a terminal reason is reached only through an explicit terminal-condition/closure transition, never silently), EBM-08 episode facet (history + closure events ordered, generation-fenced, append-only; stale/future/cross-generation fail closed), EBM-10 (RL signal related to a terminal reason only via a valid closure record).
• A spec-sync test that parses the | EBM-0x | rows of specs/formal/participant-episode-model/README.md whose Primary clauses name SEM-222 and asserts set-equality with the oracle catalog (keeps the executable oracle honest against the authored invariant list — read-only; the joint design doc is not edited).
• Hypothesis-generated valid progressions satisfy every cataloged invariant; each mutation is rejected. Predicates reuse the real iter_participant_episode_snapshot_violations / iter_participant_episode_closure_violations so the oracle exercises production code, not a parallel re-encoding.

test_sem_222_episode_termination_semantics.py holds the direct unit tests for the closure contract + validation helper (positive + each negative fixture) and the terminal-reason distinctness gates over the real contracts.

Both test files open with the SEM-222 module docstring binding (the repo's test↔UID convention) and are TESTS-linked in Ground Control.

Governance reconciliation (same change)

• Coverage row docs/explain/reference/shared-semantic-integrity.md:247 (owners RUN-311, SEM-222, DSL-120, ACT-623): add the new realizing artifacts (closure module, closure-record schema, the two test files). Status stays partial — DSL-120 (Participant Episode Structure And Termination Surface (DSL-120) #307) and ACT-623 (Participant Episode Structure (ACT-623) #309) are not yet shipped, so the family is not fully active; partial requires ≥1 phase + ≥1 non-test artifact (satisfied). Validated by tools/check_semantic_coverage.py.
• Assurance fulfillment specs/formal/assurance-fulfillment.yaml (participant-episode-model, :530): move Participant Episode, Reset, And Termination Semantics (SEM-222) #305 out of the unit_tests (Participant Episode, Reset, And Termination Semantics (SEM-222) #305–Participant Interaction Budgets And Quotas (ACT-624) #310) and property_based_or_differential_tests (Participant Episode, Reset, And Termination Semantics (SEM-222) #305, Participant Budget, Quota, And Exhaustion Semantics (SEM-223) #306) waivers and record Participant Episode, Reset, And Termination Semantics (SEM-222) #305's delivered test artifacts, leaving the other issues' waivers intact. Validated by tools/check_assurance_policy.py.
• Ground Control traceability: IMPLEMENTS links SEM-222 → participant_episode_closure.py, the closure ContractModel, and the runtime diagnostics helper; TESTS links SEM-222 → both new test files (check_requirement_governance.py requires an IMPLEMENTS link for every changed packages/ code file and a TESTS link for every changed tests/ file under the resolved UID). The requirement itself transitions DRAFT → ACTIVE in Phase E (Step 15) after merge.
• Spec section: add a concise ## SEM-222 - Episode Boundary And Termination Semantics section to specs/formal/participant-semantics/README.md (the canonical SEM home, mirroring the SEM-233 addition) — design commitments + a source-to-contract-to-test matrix + a "Current implementation artifacts" list pointing at the delivered code/tests, citing participant-episode-model/README.md as the governing design. Fills the "no spec section" gap the design noted.

Design-lens reconciliation (FAANG L6+ / preflight four questions)

• Security: closure records carry only safe references — evidence_refs, deriving_authority, governed enum signal — never credentials, tokens, raw backend payloads, hidden benchmark state, or evidence bodies; ContractModel is extra="forbid"; violations surface as bounded existing Diagnostics, not native exceptions. No listener/subprocess/env/argv surface added.
• Maintainability: reuses the incumbent iter_*_snapshot_violations iterator idiom, the participant_*_contract_diagnostics wrapper seam, the ContractModel/schema_bundle()/publication-ledger machinery, the ParticipantEpisodeTerminalReason enum, and the existing oracle test pattern. No new engine, DTO family, exception hierarchy, logger, or metadata/details side channel.
• Extensibility: new backend signal kinds extend the governed ParticipantEpisodeClosureSignal catalog + explicit mapping under ordinary schema-compatibility review — not another lifecycle root, scheduler, or backend branch.
• Whole-repo view: touches the published-schema surface (generator, bundle, publication ledger, generated-schema check), the coverage-table and assurance-fulfillment governance gates, and Ground Control traceability — each addressed above. No authority artifacts added outside specs/, contracts/, docs/, implementations/. No CHANGELOG.md / changelog.d/ / _version.py edits (Release Please owns those).

TDD order

1. Closure contract + iter_* violations helper → unit tests (positive + negatives) red→green.
2. Oracle model + predicates + mutations + spec-sync → red→green.
3. ContractModel + version + bundle registration → regenerate schema → publication entry + fixtures → check_generated_schemas green.
4. Runtime diagnostics wrapper + its unit test.
5. Governance: coverage row, assurance-fulfillment, spec section, GC IMPLEMENTS/TESTS links.

Verification (before completion, with RAES_REQUIREMENT_UID=SEM-222)

implementations/python/.venv/bin/python tools/check_repo_policy.py, … tools/check_requirement_governance.py, … tools/verify_all.py, then the workflow verify / verify-completion gates and make policy. Targeted tests during the loop: the two new SEM-222 test files plus test_run_311_participant_episode_lifecycle.py and the contract-schema checks.

PR title (Conventional Commit, title-guard): feat(sdl): SEM-222 participant episode termination semantics and RL closure record (publishes a new portable schema → feat).

[Brad-Edwards]

Plan revision — closure record delivered as a typed contract, not a published wire schema

During implementation the posted plan's "published portable schema" step was dropped. Rationale (durable record):

• Registering the closure schema forced growth of two shared barrel/registry files that sit exactly at the repo's 500-line cap (raes_contracts/contracts/__init__.py = 500, contracts/bundle.py = 499). The cap explicitly forbids allowlisting and calls for splitting those barrels — a cross-cutting refactor outside SEM-222's scope and risk envelope.
• The published wire schema was optional: the architecture preflight framed it conditionally ("if a portable closure-record schema changes…") and the joint preflight's anti-patterns warn against adding schemas/DTOs unless needed. SEM-222 is the semantic layer; a portable wire schema is a runtime-realization concern.
• The design's EBM-10 readiness-bar row asks for a typed contract/helper + runtime-episode-validation enforcement + positive/negative fixtures — all delivered: ParticipantEpisodeClosureRecord (closed, versioned frozen contract with a governed signal→reason mapping), iter_participant_episode_closure_violations (fail-closed against the append-only history head), the participant_episode_closure_contract_diagnostics runtime seam, and the test_sem_222_* unit + oracle suites (positive control + the mandated negatives: reason mismatch, absent/cross-generation, ungoverned mapping, missing evidence).

Net effect: identical semantic gate and enforcement; no published-schema surface. A portable wire schema for closure records can be added cleanly once/if a backend needs to serialize them, on top of the contracts-barrel split (separate infra concern).