Repository navigation
feat(sdl): add authored participant episode policies to behavior specifications - #1463
Conversation
0decfe7 to
fa88b95
Compare
…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.
fa88b95 to
cbf38ee
Compare
…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.
cbf38ee to
a621809
Compare
|
Recommendation: do not merge as is. Reviewed head
Required action:
Coverage and outstanding work: #307 is unblocked by the landed #122 design; typed authored intent beside ADR-013 state is a sound direction. EBM-01 and single-policy/reference/terminal-reason invariants are represented, but full DSL-120 fulfillment cannot be verified with missing schema evidence and skipped governance. Verification limits: No clean source/schema recommendation; incomplete API diff/body and current-base conflicts. |
…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.
Collected on this branch's source (e7b36f5, implementation digest cc000d9b4e7c, dev 326fd78 merged) 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.
…e-surface No conflicts. dev 7b3918d (#1635) changes contracts, processor and trial-realization source but none of this branch's files, and 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.
Collected on this branch's source (370cac2, implementation digest 1d1e32e77c5b, dev 7b3918d merged) 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.
Complete schema diffHead
|
|
Addressed the 2026-10-25 review at
|
Conflicts were all in research evidence: #309's numbered releases (specification coverage 70.0.0, formal validation 71.0.0), their index rows and the revision pins in tools/ and the three evidence test modules. They take #1463's side, which carries dev's published history, and #309's issue-309 bundle is removed. Fresh content-addressed captures replace them. The #309 code, fixtures, docs and traceability merged without conflict.
…e-structure dev 2553c54 adds #1636, #1639, #1640, #1641 and #1644 beyond the dev that #1463's head contains. One conflict: contracts/schema-publication/entries/sdl-authoring-input-v1.json. dev's #1636 and #307 both change sdl-authoring-input-v1.json. The schemas were regenerated from schema_bundle() on the merged source and equal the merged files. The entry keeps #307's summary, because #307's episode policy is this branch's change against dev, and its content hash is recorded against the merged content. materialized-scenario-v1.json stays at 469,101 bytes: neither dev's new commits nor #309 change it.
…e-surface One conflict, in contracts/schema-publication/entries/sdl-authoring-input-v1.json: dev 2553c54 (#1636, issue #1625) and this branch both record a last_change for sdl-authoring-input-v1. The published schemas, rebuilt by tools/generate_contract_schemas.py, match the auto-merge byte for byte. The entry keeps this branch's #307 summary, since that is the change this branch adds to dev's schema, and its content_hash is recomputed with check_schema_publication.schema_content_hash for the combined schema. check_generated_schemas.py and check_schema_publication.py (also with --base-rev origin/dev) pass; materialized-scenario-v1.json is 469,101 bytes. dev also changes package source (#1636, #1639, #1640, #1641), so the issue #307 captures recorded for the previous source are dropped in the next commit and recollected on this combined source.
dev 2553c54 changes package source (#1636, #1639, #1640, #1641), so the captures recorded on 370cac2 (implementation digest 1d1e32e7) no longer match the combined implementation digest e1d21a62. Remove them, their receipts and their scope bindings before recording fresh captures on the merged source.
Collected on this branch's source (3d2cfc4, implementation digest e1d21a62301b, dev 2553c54 merged) 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 (formal 5118e02a, specification 8aa11e53).
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.
#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.
…cipant-episode-surface # 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/tests/test_formal_semantic_validation.py # specs/concept-authority/semantic-profiles.md # specs/sdl/references.md
…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.
Summary
Add optional authored participant episode policies to behavior specifications for DSL-120. Policies declare initialization, turn structure, terminal and truncation conditions, and reset intent through existing SDL references. Compilation emits participant metadata while preserving the existing episode lifecycle contracts.
Requirement UIDs
participant-episode-policy-languageanddocs/governance/requirement-scopes/307.json.Related Issues
Closes #307
Related: schema publication size #1556, requirement ownership #1510, and Isabelle acquisition #1637.
This PR verifies its own schema size and publication parity. It does not claim the combined post-integration result required by #1556. The original stack includes three PRs that closed without merging, and #1465 remains open; #1556 therefore retains its separate integration acceptance.
ADR Impact
ADR-013's amendment permits this authored surface. Runtime identity, generation, history and observed lifecycle state retain their existing owners. The episode-policy module is declared as a public SDL interface for processor imports under ADR-121. No second episode state machine or external contract family is added.
Changes
devcontrol-context declarations, contract-owned imports, normative reference catalogs, immutable research validation and schema-publication entry format during conflict resolution.episode_policyin the normative ACT-606 aggregate inventory.SemanticValidatorand its ancestors, so composed helpers cannot replace its entry-point evidence. Cover false positives and concealed violations.Test Plan
Targeted pytest coverage for episode policies, requirement ownership, schema publication size, SDL catalog parity, retained compilation fingerprints and the ACT-606 inventory: 226 passed in a local sandbox with no credentials or network access. The sandbox could not write repository source files.
Three isolated omission mutations were detected: removing aggregate recognition failed all four standalone-policy cases; removing the schema structure constraint failed the empty-policy regression; omitting nonempty compiled policies failed their fingerprint regression.
Ruff checks and formatting pass for the affected Python files. Targeted structural analysis reports no new private imports, 33 validator ancestors and no unresolved bases. The semantic coverage and ownership tests also pass (48 cases). Pinned Vale and shared STE checks report no findings across nine edited prose files.
The retained fingerprint dimension test also passes with the new absent-policy compatibility rule. Diagnostic-boundary and requirement-ownership regressions pass together (24 cases).
Hosted CI run 43105505531 passes for
f6a6bfacc49810c4263e02385c14f4eb946b742e: all eight test shards, integration, repository policy, proof, model checking, coverage reduction,verifyand Sonar checks. Documentation, CodeQL, supply-chain, fuzz, runtime supervision and Python compatibility checks also pass. SonarCloud reports quality gate OK, no open issues and no open security hotspots. The remaining maintainer gate requires Brad-Edwards's GitHub approval.Ground Control Checks
Traceability
docs/requirements/DSL-120/requirement.mdlinks the policy model, validator, composition, compiler and schemas.test_issue_307_dsl_120_participant_episode_policy.pyandtest_issue_307_policy_ownership.py.Checklist
Documentation
The normative episode structure contract now permits standalone policies and rejects empty structures in both parsing and schemas. The reference catalog retains
dev's five-column format and the episode reference rows. The semantic-profile explanation preserves ADR-013's authoring amendment. The ACT-606 inventory now includes the episode policy, and its coverage excerpts retain the same meaning after sentence edits. These claims were checked against the policy model, aggregate validator, compiled records and regenerated schemas.The episode authoring example and lineage explanation now live in
docs/explain/sdl/participant-episode-policies.md. They retain the existing fixture, contract and source references. Pinned Vale and shared STE pass for nine edited prose files. The exact DSL-120 requirement record uses the existing per-record reading-metric exception pattern: fixed requirement terms and structured trace labels score 14.00. Its other style rules and the shared sentence and paragraph checks remain enabled and pass. Requirement wording retains the same obligation, and the frontmatter title is unchanged.SonarCloud's project-specific
Python-Strict RAESprofile already haspython:S104inactive. No SonarCloud file-length rule was changed. The repository's separate 1,000-line source-file policy remains in place.