Skip to content

feat(sdl): make episode structure a first-class member of participant behavior - #1465

Open
doublewhy wants to merge 52 commits into
devfrom
309-participant-episode-structure
Open

doublewhy wants to merge 52 commits into
devfrom
309-participant-episode-structure

Conversation

@doublewhy

@doublewhy doublewhy commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

#309 (ACT-623) makes the DSL-120 episode policy a first-class member of the participant behavior aggregate, and carries it through runtime binding and conformance.

  • A behavior specification can have an episode policy as its only behavior surface. The policy attaches under each behavior_mode, and with no behavior_mode. The autonomous execution profile cannot contain one.
  • The compiled aggregate names its policy through episode_policy_address.
  • ParticipantEpisodeRuntimeBinding binds each governed participant to one implementation selection. The control plane applies, authorizes, or admits an episode-governed plan only under the binding of its exact compiled model.
  • The runtime keeps reset actions and terminal reasons within the policy on ordinary dispatch, mixed-control lifecycle dispatch, and autonomous clock resets. It refuses returned, composed, or restored history that violates the policy.
  • run_target_conformance reports a participant-episode-structure case from recorded history. It inspects history only and claims no native execution.

#1463 (DSL-120) merged into dev. This branch now merges dev and contains only the #309 changes.

Requirement UIDs

Related Issues

Closes #309

ADR Impact

Changes

  • b81ac29e merges dev. It takes dev's final Add authored participant episode policies over the existing lifecycle (DSL-120) #307 files and rewires the Attach episode structure across participant implementation kinds (ACT-623) #309 code onto dev's public interfaces. It removes the duplicate episode guides and the research captures recorded on the pre-merge source.
  • 4f556829 fixes the review findings:
    • Plan admission (manager_plan_admission.py, interaction.py, runtime_experiment_admission.py) admits an episode-governed plan under its exact binding. Before this change, apply refused every such plan.
    • time_control.py refuses an autonomous clock reset that the reset policy does not admit, before the time runtime is called.
    • interaction_results.py refuses composed time and scheduler results that violate the policy.
    • target.py and target_probes.py compile the probe scenario once and reuse its model for the episode case.
  • The published schemas do not change. Regeneration on the merged tree gives dev's bytes.

Test Plan

  • Unit tests pass
  • Integration tests pass if applicable (CI runs them)
  • Completion command passes (not run locally)
  • No coverage regression (CI and Sonar report it)

Targeted pytest on the merged tree passes: the #309 and #307 modules, conformance facade, versioned evidence, formal semantic validation, catalog parity, clock-reset, trial, mixed-runtime, runtime-conformance, and mapping-export modules.

test_issue_309_episode_runtime_admission.py is new. With the admission fix removed, all four cases fail. With only the clock-reset check removed, the refusal case fails.

make policy, ruff, pinned Vale, the shared STE linter, tools/check_formal_semantic_validation.py, and tools/check_specification_coverage.py pass. Full verification runs in CI.

Ground Control Checks

  • Repository policy command passes
  • Pre-push code review and test-quality review completed, or not run for this lane

make policy and tools/check_requirement_governance.py --base-rev origin/dev --requirement-uid ACT-623 exit 0.

Traceability

  • IMPLEMENTS: see docs/requirements/ACT-623/requirement.md
  • TESTS: test_issue_309_act_623_participant_episode_structure.py, test_issue_309_episode_runtime_binding.py, test_issue_309_episode_runtime_admission.py, test_issue_309_episode_target_conformance.py, test_issue_309_policy_ownership.py

Checklist

…ifications

Add the optional behavior_specifications.*.episode_policy record (DSL-120):
initialization precondition assertions, decision-epoch turn structure,
completion and timeout terminal conditions, truncation conditions, and a
reset policy with admitted control actions and a participant-memory scope.
Every condition maps to exactly one ADR-013 terminal reason and names the
evidence requirements that back the transition; interruption is never
authored. The closed record rejects realized episode coordinates by name.

Validate references, assertion roles, owner-bound timeouts and evidence
fail closed, rewrite references under module composition, and compile each
policy to participant.episode-policy.<name> keyed to the selected
participants' participant.behavior.<agent> addresses. Regenerate the five
scenario schemas with their publication entries, add the reference-catalog
rows, valid and invalid fixtures, normative and explain documentation,
lineage notes and DSL-120 traceability.
…nct from completion

Resolve reset_policy.memory_reset_authority_ref to exactly one declared
targetable SDL element during semantic validation. Dangling and ambiguous
refs fail closed, and ${var} refs wait for the post-instantiation pass.
Module composition now namespaces the authority. Compilation records the
element's canonical sdl.* address as memory_reset_authority_address, adds
it to the policy's refresh dependencies, and re-asserts that only an
episode_local_reset scope names one. Add the matching reference-catalog
row.

Reject a truncation condition that reuses the exact assertion set of a
completion condition, so one evidenced fact cannot end an episode as both
completed and truncated.

Reword the reset-policy comment, the normative section and the explain
guide: the ADR-095 assurance and information-state contracts require the
same pairing, but the policy does not supply their values. State that a
condition holds only when every assertion it names holds and that
validation checks only that its evidence requirements are declared, and
point the public participant-control guide at the episode policy fixture.
… behavior

Treat the DSL-120 episode policy as a first-class member of the behavior
specification aggregate (ACT-623). A specification may aggregate an episode
policy as its only behavior surface, and the compiled aggregate names its
member through episode_policy_address. The member relies on the semantic
validation rule, added with the DSL-120 policy, that one episode policy
governs each participant. The policy attaches to participants of every
behavior mode, while the closed autonomous execution profile cannot carry
one.

Add participant_episode_structure_conformance_diagnostics() to
raes_conformance: for a governed participant, recorded ADR-013 history may end
an episode only with a reason an authored condition produces or with an
interruption, and may reset or restart only as the reset policy admits.
Record standalone and autonomous-profile fixtures, specification and guide
paragraphs, lineage notes, ACT-623 traceability and assurance fulfillment.
…ence tests

State in the normative section and the explain guide that conformance
admits any recorded reset or restart for a policy without a reset_policy,
and re-wrap the ACT-623 paragraphs in the specification and lineage notes.

Trace the three research-evidence modules this change republishes to
ACT-623, and describe the module's uniqueness case as the conformance
refusal it is.

Assert the full recorded event sequence in the conforming-history test, and
cover a policy without a reset policy and history that snapshot integrity
reports: a non-list history, non-mapping events and malformed events.
@Brad-Edwards

Copy link
Copy Markdown
Collaborator

Recommendation: do not merge as is.

Reviewed head 85d7370fdb004bd54b53979f4a5c6bacb246065c, targeting dev.

  1. Merge conflicts against dev (DIRTY), with unmerged feat(sdl): add authored participant episode policies to behavior specifications #1463/Add authored participant episode policies over the existing lifecycle (DSL-120) #307 in the diff.
  2. Applicable ACT-623 governance passes only against the feature-stack parent, not the actual dev target; stacked DSL-120 files have ownership/traceability failures (Requirement ownership roots do not cover the files of DSL-117, DSL-120, DSL-121, ACT-624, SEM-223 and SEM-204 #1510).
  3. Numbered release/index/pin edits violate current research capture policy; materialized-scenario-v1.json patch is unavailable and The materialized-scenario-v1 schema exceeds its 512,000-byte budget if #1463 lands before #1467 #1556 records the combined-base size risk.

Required action:

  • Resolve feat(sdl): add authored participant episode policies to behavior specifications #1463's blockers and bring this branch onto current dev with a real merge.
  • Run requirement governance with ACT-623 and the actual base/scope, resolving stacked DSL-120 ownership and traceability rather than skipping the gate.
  • Regenerate schemas within the size budget and provide their complete diff; record fresh content-addressed captures.
  • Verify first-class aggregation across behavior modes and conformance semantics with targeted tests and required CI.

Coverage and outstanding work: #309's standalone aggregate member and compiled episode_policy_address are implemented; #122 is landed design authority. The directly callable conformance helper is new, while runner adoption is explicitly tracked in #1523. Full combined-source fulfillment remains unverifiable because the parent/schema/governance blockers persist.

Verification limits: No clean recommendation over the omitted published schema patch.

…e-surface

Conflicts and their resolution:

- Research evidence (docs/research, tools/formal_semantic_validation,
  tools/check_specification_coverage.py and three evidence tests): take
  dev's side and drop this branch's numbered releases (specification
  coverage 69.0.0, formal validation 70.0.0), the shared index edits and
  the revision-pin edits. Feature branches record content-addressed
  captures instead (.gc/plan-rules.md, docs/develop/research-captures.md).
- participant_behavior_specification.py, validator/__init__.py,
  compiler/pipeline.py: keep dev's mixed-control policy, effect-target and
  delivery-control members beside the episode policy.
- specs/sdl/references.md: keep dev's delivery-control rows, then the nine
  episode-policy rows.
- Schemas and ledger: regenerated from schema_bundle() on the merged
  source; the five last_change entries are recorded against the new
  content. materialized-scenario-v1.json is 469,101 bytes, inside the
  512,000-byte budget, because dev's shared-subschema factoring (#1584)
  absorbs the policy's growth (#1556).

Semantic conflicts resolved in the same merge:

- dev's #1446 replaced the targetable flag with explicit reference
  purposes, so the reset-authority check and its compiled address resolve
  through ReferencePurpose.TARGETABLE, the purpose the references.md row
  already names, and the editor table gains the same entry.
- dev's composition/_behavior.py is now 490 lines, so the episode-policy
  rewriter moves to composition/_episode_policy.py to stay under the
  500-line cap.
…t finds ambiguous

dev's composition now resolves an imported unit's tool_ref and behavior
authority scopes through the unit's own declaration index before the
import is namespaced. The episode policy's memory_reset_authority_ref was
still renamed through the combined name map, so a bare name the unit gave
to both an exported agent and a private node was bound to the agent, and
a reference that standalone validation rejects as ambiguous composed
cleanly.

Before the rename, composition now resolves each reset authority with the
targetable purpose that validation uses, and an ambiguous one fails with
the standalone diagnostic anchored at the unit file. The tests cover a
private and an exported clash and the qualified spelling beside the clash,
and share one module header with the composition test.
…e locator

The Cambridge mirror's dist directory now holds Isabelle2026 only, so
the locked Isabelle2025-2_linux.tar.gz answers 404 there and
canonical / generic-tool-local-inputs fails exact verification, which
skips the checks, integration and proof jobs. The official release
locator serves the same bytes; the fetch still verifies the unchanged
lock size and SHA-256.
…ce runs on this branch

DSL-120 reached sdl-language only through the shared ^DSL- pattern, whose
ownership roots exclude the episode-policy fixtures, the participant-control
guide, the semantic profile and the assurance record that #307 amends, so
forced requirement governance reported ownership mismatches and the branch
carried no UID (#1510). Add a participant-episode-policy-language phase
listed before sdl-language, with sdl-language's prerequisites (none). It
keeps the shared SDL roots DSL-120 already reached, without the paths named
there for other issues and requirements, and adds the files #307 changes and
the carried #1474 locator doc. The shared phase and the other #1510
requirements are unchanged.

docs/governance/requirement-scopes/307.json binds every delivery file to
DSL-120, so the canonical resolver selects DSL-120 for this issue branch and
CI evaluates requirement governance instead of skipping it. The DSL-120
record gains the IMPLEMENTS and TESTS links governance requires. The new
policy test pins the route and its bounds, keeps DSL-121 on the shared phase,
and evaluates the issue scope over its bound files.
Collected on this branch's source (0126d25, implementation digest
023dc3d0be7a) with collect_research_evidence.py: the 6 pinned
specification artifacts ran through the production pipeline (38 of 42
stages passed, 4 preregistered non-executions, load-bearing 10 of 10);
the 10 retained formal SDL cases were replayed with replay_case, the 4
production cases ran with their raes processor argv, and the 14
participant functions ran (18 passed); 20 of 20 observations matched.

The compile repeatability and non-vacuity controls record a
compiled-representation-change deviation: the compiled runtime model now
carries the empty participant_episode_policies map, which changes the
compiled digest while the replayed outcomes stay the same. Both captures
were recorded with research_capture record against dev's newest admitted
manifests.
Bind the two capture directories and their capture-records receipts in requirement-scopes/307.json, so every delivery file keeps an exact DSL-120 assignment.
…ent formal capture

The issue #307 capture records compiled-representation-change deviations
for the compile repeatability and non-vacuity controls, because the
compiled runtime model now carries the participant_episode_policies map.
test_current_retest_bundle_is_coherent_and_clean asserted that the current
capture has no deviations; it now names those two controls and checks that
only their result digests changed while the outcomes stayed the same, as
the earlier materialization capture test does. The DSL-120 record and the
issue scope list the test module.
…e-surface

No conflicts. dev 326fd78 (#1633, #1634) changes runtime and experiment source but none of this branch's files except docs/public/participant-control.md, where the two edits touch different paragraphs. The five SDL schemas regenerate unchanged. The issue #307 captures recorded for the previous source are dropped in the next commit and recollected on this combined source.
Bind the two capture directories and their capture-records receipts in requirement-scopes/307.json, so every delivery file keeps an exact DSL-120 assignment.
@doublewhy

doublewhy commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor Author

Addressed the 2026-10-25 review at d5786e47:

  1. Merged feat(sdl): add authored participant episode policies to behavior specifications #1463's head (c0393184, then its re-synced 8474efc2; Attach episode structure across participant implementation kinds (ACT-623) #309's numbered releases and pins take feat(sdl): add authored participant episode policies to behavior specifications #1463's side) and dev 2553c540 (one ledger-entry conflict, rehashed). This PR must merge after feat(sdl): add authored participant episode policies to behavior specifications #1463.
  2. ACT-623 has its own participant-episode-structure phase (Requirement ownership roots do not cover the files of DSL-117, DSL-120, DSL-121, ACT-624, SEM-223 and SEM-204 #1510 option 2, ACT-623 only; participant-model unchanged) and requirement-scopes/309.json. The scope binds Attach episode structure across participant implementation kinds (ACT-623) #309's files to ACT-623 and the stacked Add authored participant episode policies over the existing lifecycle (DSL-120) #307 files to DSL-120, so both ownership and traceability checks run against dev. Governance with --base-rev origin/dev exits 0; canonical / checks passed in run 40290563113.
  3. Schemas regenerate identically; Attach episode structure across participant implementation kinds (ACT-623) #309 adds no bytes, and materialized-scenario-v1.json is 469,101 of 512,000. Complete diff: feat(sdl): make episode structure a first-class member of participant behavior #1465 (comment). Numbered releases, index rows and pins are gone; fresh captures: 9a262e4d.
  4. The Attach episode structure across participant implementation kinds (ACT-623) #309 module (20 cases) covers all seven behavior modes and none, the standalone aggregate, the autonomous-profile rejection (parser and published schema), and history conformance. Required CI is green (run 40290563113). Runner adoption stays Run the participant conformance probes from run_target_conformance #1523.

doublewhy and others added 4 commits October 26, 2026 08:06
#1463 merged the same dev 2553c54 and replaced its issue #307 captures
(86bf80b8, a52b2f46) with captures recorded on that merged source. The merge
is clean: the old #1463 captures leave this branch, the new ones and the
updated 307.json arrive, and every package file and schema outside #309's
own changes now matches #1463's head. This branch's issue #309 captures
stay current, because no package source changed.
…0 in the issue #309 scope

309.json follows 307.json at #1463's head 8474efc: the stacked DSL-120 bindings name #1463's new capture directories and receipts instead of the dropped ones.
…cipant-episode-structure

# Conflicts:
#	contracts/schema-publication/entries/instantiated-scenario-snapshot-v1.json
#	contracts/schema-publication/entries/instantiated-scenario-v1.json
#	contracts/schema-publication/entries/materialized-scenario-v1.json
#	contracts/schema-publication/entries/scenario-satisfiability-evidence-v1.json
#	contracts/schema-publication/entries/sdl-authoring-input-v1.json
#	contracts/schemas/satisfiability/scenario-satisfiability-evidence-v1.json
#	contracts/schemas/sdl/instantiated-scenario-snapshot-v1.json
#	contracts/schemas/sdl/instantiated-scenario-v1.json
#	contracts/schemas/sdl/materialized-scenario-v1.json
#	contracts/schemas/sdl/sdl-authoring-input-v1.json
#	implementations/python/packages/raes/composition/_behavior.py
#	implementations/python/packages/raes/participant_behavior_specification.py
#	implementations/python/packages/raes_conformance/conformance/__init__.py
#	implementations/python/tests/test_conformance_facade_parity.py
#	implementations/python/tests/test_formal_semantic_validation.py
#	specs/concept-authority/semantic-profiles.md
@Brad-Edwards

Copy link
Copy Markdown
Collaborator

Bind compiled episode policies to admitted implementation manifests and selections at the control plane. Validate reset actions and terminal reasons before effects, validate restored/backend history, and reject plans without the matching installed binding. Run episode policy and snapshot-integrity checks through run_target_conformance; report missing evidence and not-applicable cases explicitly, and export the checker from the package facade. Resolve current dev conflicts, regenerate schemas under current publication rules, register the public module interfaces, and update documentation/traceability. Targeted checks: 196 tests passed, four affected existing target-runner cases passed, and three admission/observation mutations were killed. Requirement governance, file-local policy, catalog/schema parity, and publication checks passed. Recorded-history inspection does not claim native condition evaluation. Current-head CI remains the completion gate.

@Brad-Edwards

Copy link
Copy Markdown
Collaborator

Address current-dev CI findings without changing the structural baseline: compose episode validation rather than adding a validator ancestor, expose named collaborator interfaces, and use the control plane's public binding property. Preserve retained semantic fingerprints when episode metadata is absent while retaining authored-policy changes in fingerprints. Add the member to the formal behavior aggregate and make section reference lookup insensitive to heading case. The 146 targeted cases covering authoring, runtime binding, conformance, fingerprint stability, model parity, and reference lookup pass; structural checks, file-local policy, governance, schema parity, and changed-prose checks pass. Re-synchronized with dev e207f16 before publishing.

@Brad-Edwards

Copy link
Copy Markdown
Collaborator

Resolve the remaining CI findings: apply lifecycle admission to the public installed-binding property, and align the complete-capture fingerprint test with empty optional intent normalization. Move all episode-specific guidance and lineage into focused linked pages, preserving the large existing guides unchanged. Split long sentences and paragraphs in the smaller maintained references while retaining normative obligations, identifiers, and pinned source facts. The exact locked shared STE checker reports zero findings across all 11 changed maintained Markdown files (17,489 words); Vale also passes. Targeted lifecycle, fingerprint, ownership, model-parity, and reference-lookup regressions pass.

@Brad-Edwards

Copy link
Copy Markdown
Collaborator

Preserve the formal behavior invariant table as single-line Markdown rows and retain its indexed excerpt prefixes while keeping the shorter sentences. Match the project import ordering used by CI. Local verify-fast-feedback passed all policy, hygiene and lint stages and 300 directly changed tests; the 30 semantic coverage checks and the delayed-result run-context regression also pass.

@Brad-Edwards

Copy link
Copy Markdown
Collaborator

Address all 13 findings from the completed Sonar analysis: separate per-case report validation and episode-plan admission, replace nested conditionals with explicit branches, wrap the long report scope line, and construct test inputs before exception assertions. Runtime and conformance semantics remain unchanged. Repository policy and Ruff pass; 64 targeted episode/conformance regressions pass, along with the conformance-reporting module.

@Brad-Edwards
Brad-Edwards marked this pull request as ready for review November 11, 2026 05:48
…e-structure

Resolve the conflicts with the merged #1463 (DSL-120) work:

- Take dev's final version of every #307 file. Rewire the #309 code
  onto dev's public interfaces, and add one shared
  participant_episode_policy_address helper.
- Take dev's published schemas. Regeneration gives the same bytes,
  so #309 changes no schema.
- Keep the absent-policy fingerprint rule and add the empty
  episode_policy_address of the aggregate to it.
- Remove the duplicate episode guides and the research captures
  recorded on the pre-merge source.
- Admit a plan with episode policies on apply, run-program, planner,
  and trial paths when the installed binding holds its exact compiled
  model. Before this change every such plan was refused.
- Refuse an autonomous clock reset that resets a governed participant
  against its reset policy, before the time runtime is called.
- Refuse composed time and scheduler results whose episode history
  violates the installed policy.
- Compile the conformance probe scenario once, and reuse its model for
  the episode-structure case.
- Make the conformance diagnostic constructor public, as dev does for
  shared helpers.
- Bind the issue 309 scope to ACT-623 only, and replace the duplicate
  guides with one runtime binding guide.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants