Skip to content

feat(sdl): add authored participant episode policies to behavior specifications - #1463

Merged
Brad-Edwards merged 28 commits into
devfrom
307-participant-episode-surface
Nov 11, 2026
Merged

Brad-Edwards merged 28 commits into
devfrom
307-participant-episode-surface

Conversation

@doublewhy

@doublewhy doublewhy commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

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

  • DSL-120, through participant-episode-policy-language and docs/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

  • Add typed policy and condition models, closed-reference validation, import rewriting, and compiled episode-policy records.
  • Permit an episode policy to be the behavior specification's only behavior surface. Continue rejecting specifications with no behavior surface.
  • Require at least one nonempty structure element in all five published scenario schemas. Null records and empty condition maps do not qualify.
  • Preserve current dev control-context declarations, contract-owned imports, normative reference catalogs, immutable research validation and schema-publication entry format during conflict resolution.
  • Keep the existing schema-size budget unchanged. The materialized schema is 501,254 bytes against a 512,000-byte limit.
  • Retain scoped DSL-120 governance and implementation/test traceability.
  • Compose episode validation into the existing behavior pass, without adding a validator ancestor. Use public reference-renaming and section-resolution interfaces and the public compiled-address renderer.
  • Preserve retained fingerprints when no episode policy is authored. Nonempty compiled policies remain part of the fingerprint, with a regression that detects their omission.
  • Include episode_policy in the normative ACT-606 aggregate inventory.
  • Scope the diagnostic-boundary guard to SemanticValidator and its ancestors, so composed helpers cannot replace its entry-point evidence. Cover false positives and concealed violations.
  • Put authoring and lineage guidance in a focused episode-policy reference, linked from the normative contract and fixture guide. Restore the two general SDL reference pages to their base content.

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, verify and 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

  • Repository policy command passes for the published head in hosted CI.
  • Pre-push code review and test-quality review completed, or not run for this lane.

Traceability

  • IMPLEMENTS: docs/requirements/DSL-120/requirement.md links the policy model, validator, composition, compiler and schemas.
  • TESTS: test_issue_307_dsl_120_participant_episode_policy.py and test_issue_307_policy_ownership.py.

Checklist

  • Preserve authored-intent and observed-state separation (EBM-01).
  • Preserve existing episode identity and lifecycle contracts.
  • Update the five published scenario schemas and retain their publication entries.
  • Preserve the schema-size budget.
  • Update the normative authoring contract and reference catalog.
  • Use a Conventional Commit PR title.

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 RAES profile already has python:S104 inactive. No SonarCloud file-length rule was changed. The repository's separate 1,000-line source-file policy remains in place.

…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.
@Brad-Edwards

Copy link
Copy Markdown
Collaborator

Recommendation: do not merge as is.

Reviewed head a62180963661b284fc67cc2c4b8f0ea1961e4651, targeting dev.

  1. Merge conflicts against dev (DIRTY).
  2. The PR deliberately omits DSL-120 from the branch because forced requirement governance reports ownership mismatches (Requirement ownership roots do not cover the files of DSL-117, DSL-120, DSL-121, ACT-624, SEM-223 and SEM-204 #1510). Repository instructions require RAES_REQUIREMENT_UID for UID-free branches; bypassing classification is not a passing requirement gate.
  3. Numbered research releases/shared index and revision-pin changes conflict with current capture policy.
  4. The API omits the materialized-scenario-v1.json patch and truncates the PR body, preventing complete schema/scope review. The materialized-scenario-v1 schema exceeds its 512,000-byte budget if #1463 lands before #1467 #1556 also records a schema-size failure when combined with newer dev.

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.
dev 326fd78 changes package source, so the captures recorded on 0126d25 no longer match the combined implementation digest. Remove them and their receipts, and their scope bindings, before recording fresh captures on the merged 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.
dev 7b3918d changes package source, so the captures recorded on e7b36f5 no longer match the combined implementation digest. Remove them, their receipts and their scope bindings before recording fresh captures on the merged 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.
@doublewhy

Copy link
Copy Markdown
Contributor Author

Complete schema diff

Head c0393184 against dev 7b3918dd. GitHub's API omits the materialized-scenario-v1.json patch, so this diff is generated field by field from the before and after schema files.

materialized-scenario-v1.json shares repeated subschemas as #/$defs/_rN (#1584). Both sides are compared with those refs expanded; test_shared_rules_expand_to_the_exact_unfactored_schema checks that this sharing changes representation only. In all five schemas, the only change outside the ten new $defs is the optional ParticipantBehaviorSpecification.properties.episode_policy. The four post-instantiation schemas differ from the authoring schema only by a not pattern that rejects ${var} in reference items, as for every other reference.

contracts/schemas/sdl/sdl-authoring-input-v1.json

814,011 → 824,182 bytes. After expanding shared-subschema refs: 10 added $defs, 1 other change(s).

  • Added $defs: ParticipantEpisodeCompletionCondition, ParticipantEpisodeInitialization, ParticipantEpisodeInteractionStructure, ParticipantEpisodeMemoryScope, ParticipantEpisodePolicy, ParticipantEpisodeResetAction, ParticipantEpisodeResetPolicy, ParticipantEpisodeTimeoutCondition, ParticipantEpisodeTruncationCondition, ParticipantEpisodeTurnOrderBasis
  • added /$defs/ParticipantBehaviorSpecification/properties/episode_policy: {"anyOf": [{"$ref": "#/$defs/ParticipantEpisodePolicy"}, {"type": "null"}], "default": null}

contracts/schemas/sdl/instantiated-scenario-v1.json

1,049,186 → 1,060,807 bytes. After expanding shared-subschema refs: 10 added $defs, 1 other change(s).

  • Added $defs: ParticipantEpisodeCompletionCondition, ParticipantEpisodeInitialization, ParticipantEpisodeInteractionStructure, ParticipantEpisodeMemoryScope, ParticipantEpisodePolicy, ParticipantEpisodeResetAction, ParticipantEpisodeResetPolicy, ParticipantEpisodeTimeoutCondition, ParticipantEpisodeTruncationCondition, ParticipantEpisodeTurnOrderBasis
  • added /$defs/ParticipantBehaviorSpecification/properties/episode_policy: {"anyOf": [{"$ref": "#/$defs/ParticipantEpisodePolicy"}, {"type": "null"}], "default": null}

contracts/schemas/sdl/instantiated-scenario-snapshot-v1.json

1,052,458 → 1,064,079 bytes. After expanding shared-subschema refs: 10 added $defs, 1 other change(s).

  • Added $defs: ParticipantEpisodeCompletionCondition, ParticipantEpisodeInitialization, ParticipantEpisodeInteractionStructure, ParticipantEpisodeMemoryScope, ParticipantEpisodePolicy, ParticipantEpisodeResetAction, ParticipantEpisodeResetPolicy, ParticipantEpisodeTimeoutCondition, ParticipantEpisodeTruncationCondition, ParticipantEpisodeTurnOrderBasis
  • added /$defs/ParticipantBehaviorSpecification/properties/episode_policy: {"anyOf": [{"$ref": "#/$defs/ParticipantEpisodePolicy"}, {"type": "null"}], "default": null}

contracts/schemas/sdl/materialized-scenario-v1.json

463,541 → 469,101 bytes; shared subschemas 214 → 217. After expanding shared-subschema refs: 10 added $defs, 1 other change(s).

  • Added $defs: ParticipantEpisodeCompletionCondition, ParticipantEpisodeInitialization, ParticipantEpisodeInteractionStructure, ParticipantEpisodeMemoryScope, ParticipantEpisodePolicy, ParticipantEpisodeResetAction, ParticipantEpisodeResetPolicy, ParticipantEpisodeTimeoutCondition, ParticipantEpisodeTruncationCondition, ParticipantEpisodeTurnOrderBasis
  • added /$defs/ParticipantBehaviorSpecification/properties/episode_policy: {"anyOf": [{"$ref": "#/$defs/ParticipantEpisodePolicy"}, {"type": "null"}], "default": null}

contracts/schemas/satisfiability/scenario-satisfiability-evidence-v1.json

1,040,814 → 1,052,435 bytes. After expanding shared-subschema refs: 10 added $defs, 1 other change(s).

  • Added $defs: ParticipantEpisodeCompletionCondition, ParticipantEpisodeInitialization, ParticipantEpisodeInteractionStructure, ParticipantEpisodeMemoryScope, ParticipantEpisodePolicy, ParticipantEpisodeResetAction, ParticipantEpisodeResetPolicy, ParticipantEpisodeTimeoutCondition, ParticipantEpisodeTruncationCondition, ParticipantEpisodeTurnOrderBasis
  • added /$defs/ParticipantBehaviorSpecification/properties/episode_policy: {"anyOf": [{"$ref": "#/$defs/ParticipantEpisodePolicy"}, {"type": "null"}], "default": null}

Added $defs content

Each definition appears once per distinct variant, with the schemas that carry it.

ParticipantEpisodeCompletionCondition (sdl-authoring-input-v1.json)

{
 "additionalProperties": false,
 "description": "Evidenced assertions that end the episode as completed.",
 "properties": {
  "assertion_refs": {
   "items": {
    "minLength": 1,
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Assertion Refs",
   "type": "array",
   "uniqueItems": true
  },
  "evidence_requirement_refs": {
   "items": {
    "minLength": 1,
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Evidence Requirement Refs",
   "type": "array",
   "uniqueItems": true
  },
  "terminal_reason": {
   "const": "completed",
   "title": "Terminal Reason",
   "type": "string"
  }
 },
 "required": [
  "terminal_reason",
  "assertion_refs",
  "evidence_requirement_refs"
 ],
 "title": "ParticipantEpisodeCompletionCondition",
 "type": "object"
}

ParticipantEpisodeCompletionCondition (instantiated-scenario-v1.json, instantiated-scenario-snapshot-v1.json, materialized-scenario-v1.json, scenario-satisfiability-evidence-v1.json)

{
 "additionalProperties": false,
 "description": "Evidenced assertions that end the episode as completed.",
 "properties": {
  "assertion_refs": {
   "items": {
    "minLength": 1,
    "not": {
     "pattern": "\\$\\{((?:(?:[a-z0-9][a-z0-9_-]{0,63}|__private)\\.)*[a-z0-9][a-z0-9_-]{0,63})\\}"
    },
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Assertion Refs",
   "type": "array",
   "uniqueItems": true
  },
  "evidence_requirement_refs": {
   "items": {
    "minLength": 1,
    "not": {
     "pattern": "\\$\\{((?:(?:[a-z0-9][a-z0-9_-]{0,63}|__private)\\.)*[a-z0-9][a-z0-9_-]{0,63})\\}"
    },
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Evidence Requirement Refs",
   "type": "array",
   "uniqueItems": true
  },
  "terminal_reason": {
   "const": "completed",
   "title": "Terminal Reason",
   "type": "string"
  }
 },
 "required": [
  "terminal_reason",
  "assertion_refs",
  "evidence_requirement_refs"
 ],
 "title": "ParticipantEpisodeCompletionCondition",
 "type": "object"
}

ParticipantEpisodeInitialization (sdl-authoring-input-v1.json)

{
 "additionalProperties": false,
 "description": "Preconditions of every new episode generation.",
 "properties": {
  "assertion_refs": {
   "items": {
    "minLength": 1,
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Assertion Refs",
   "type": "array",
   "uniqueItems": true
  }
 },
 "required": [
  "assertion_refs"
 ],
 "title": "ParticipantEpisodeInitialization",
 "type": "object"
}

ParticipantEpisodeInitialization (instantiated-scenario-v1.json, instantiated-scenario-snapshot-v1.json, materialized-scenario-v1.json, scenario-satisfiability-evidence-v1.json)

{
 "additionalProperties": false,
 "description": "Preconditions of every new episode generation.",
 "properties": {
  "assertion_refs": {
   "items": {
    "minLength": 1,
    "not": {
     "pattern": "\\$\\{((?:(?:[a-z0-9][a-z0-9_-]{0,63}|__private)\\.)*[a-z0-9][a-z0-9_-]{0,63})\\}"
    },
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Assertion Refs",
   "type": "array",
   "uniqueItems": true
  }
 },
 "required": [
  "assertion_refs"
 ],
 "title": "ParticipantEpisodeInitialization",
 "type": "object"
}

ParticipantEpisodeInteractionStructure (sdl-authoring-input-v1.json)

{
 "additionalProperties": false,
 "description": "Turn order authority and the actions a turn offers.",
 "properties": {
  "action_contract_refs": {
   "items": {
    "minLength": 1,
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Action Contract Refs",
   "type": "array",
   "uniqueItems": true
  },
  "order_basis": {
   "$ref": "#/$defs/ParticipantEpisodeTurnOrderBasis"
  }
 },
 "required": [
  "order_basis",
  "action_contract_refs"
 ],
 "title": "ParticipantEpisodeInteractionStructure",
 "type": "object"
}

ParticipantEpisodeInteractionStructure (instantiated-scenario-v1.json, instantiated-scenario-snapshot-v1.json, materialized-scenario-v1.json, scenario-satisfiability-evidence-v1.json)

{
 "additionalProperties": false,
 "description": "Turn order authority and the actions a turn offers.",
 "properties": {
  "action_contract_refs": {
   "items": {
    "minLength": 1,
    "not": {
     "pattern": "\\$\\{((?:(?:[a-z0-9][a-z0-9_-]{0,63}|__private)\\.)*[a-z0-9][a-z0-9_-]{0,63})\\}"
    },
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Action Contract Refs",
   "type": "array",
   "uniqueItems": true
  },
  "order_basis": {
   "$ref": "#/$defs/ParticipantEpisodeTurnOrderBasis"
  }
 },
 "required": [
  "order_basis",
  "action_contract_refs"
 ],
 "title": "ParticipantEpisodeInteractionStructure",
 "type": "object"
}

ParticipantEpisodeMemoryScope (sdl-authoring-input-v1.json, instantiated-scenario-v1.json, instantiated-scenario-snapshot-v1.json, materialized-scenario-v1.json, scenario-satisfiability-evidence-v1.json)

{
 "description": "ADR-095 participant-memory scope across a reset.",
 "enum": [
  "episode_local_reset",
  "persistent_across_episodes"
 ],
 "title": "ParticipantEpisodeMemoryScope",
 "type": "string"
}

ParticipantEpisodePolicy (sdl-authoring-input-v1.json, instantiated-scenario-v1.json, instantiated-scenario-snapshot-v1.json, materialized-scenario-v1.json, scenario-satisfiability-evidence-v1.json)

{
 "additionalProperties": false,
 "description": "Versioned episode structure intent of a behavior specification.",
 "properties": {
  "initialization": {
   "anyOf": [
    {
     "$ref": "#/$defs/ParticipantEpisodeInitialization"
    },
    {
     "type": "null"
    }
   ],
   "default": null
  },
  "interaction_structure": {
   "anyOf": [
    {
     "$ref": "#/$defs/ParticipantEpisodeInteractionStructure"
    },
    {
     "type": "null"
    }
   ],
   "default": null
  },
  "profile": {
   "const": "participant-episode-policy/v1",
   "title": "Profile",
   "type": "string"
  },
  "reset_policy": {
   "anyOf": [
    {
     "$ref": "#/$defs/ParticipantEpisodeResetPolicy"
    },
    {
     "type": "null"
    }
   ],
   "default": null
  },
  "terminal_conditions": {
   "additionalProperties": false,
   "patternProperties": {
    "^[a-z0-9]": {
     "discriminator": {
      "mapping": {
       "completed": "#/$defs/ParticipantEpisodeCompletionCondition",
       "timed_out": "#/$defs/ParticipantEpisodeTimeoutCondition"
      },
      "propertyName": "terminal_reason"
     },
     "oneOf": [
      {
       "$ref": "#/$defs/ParticipantEpisodeCompletionCondition"
      },
      {
       "$ref": "#/$defs/ParticipantEpisodeTimeoutCondition"
      }
     ]
    }
   },
   "propertyNames": {
    "maxLength": 64,
    "minLength": 1,
    "not": {
     "pattern": "[^a-z0-9_-]"
    }
   },
   "title": "Terminal Conditions",
   "type": "object"
  },
  "truncation_conditions": {
   "additionalProperties": false,
   "patternProperties": {
    "^[a-z0-9]": {
     "$ref": "#/$defs/ParticipantEpisodeTruncationCondition"
    }
   },
   "propertyNames": {
    "maxLength": 64,
    "minLength": 1,
    "not": {
     "pattern": "[^a-z0-9_-]"
    }
   },
   "title": "Truncation Conditions",
   "type": "object"
  }
 },
 "required": [
  "profile"
 ],
 "title": "ParticipantEpisodePolicy",
 "type": "object"
}

ParticipantEpisodeResetAction (sdl-authoring-input-v1.json, instantiated-scenario-v1.json, instantiated-scenario-snapshot-v1.json, materialized-scenario-v1.json, scenario-satisfiability-evidence-v1.json)

{
 "description": "ADR-013 control actions that start a later episode.",
 "enum": [
  "reset",
  "restart"
 ],
 "title": "ParticipantEpisodeResetAction",
 "type": "string"
}

ParticipantEpisodeResetPolicy (sdl-authoring-input-v1.json)

{
 "additionalProperties": false,
 "allOf": [
  {
   "else": {
    "properties": {
     "memory_reset_authority_ref": {
      "type": "null"
     }
    }
   },
   "if": {
    "properties": {
     "participant_memory_scope": {
      "const": "episode_local_reset"
     }
    }
   },
   "then": {
    "properties": {
     "memory_reset_authority_ref": {
      "type": "string"
     }
    },
    "required": [
     "memory_reset_authority_ref"
    ]
   }
  }
 ],
 "description": "Admitted reset actions, memory scope, reset authority, and evidence.",
 "properties": {
  "control_actions": {
   "items": {
    "$ref": "#/$defs/ParticipantEpisodeResetAction"
   },
   "minItems": 1,
   "title": "Control Actions",
   "type": "array",
   "uniqueItems": true
  },
  "evidence_requirement_refs": {
   "items": {
    "minLength": 1,
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Evidence Requirement Refs",
   "type": "array",
   "uniqueItems": true
  },
  "memory_reset_authority_ref": {
   "anyOf": [
    {
     "minLength": 1,
     "pattern": "\\S",
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Memory Reset Authority Ref"
  },
  "participant_memory_scope": {
   "$ref": "#/$defs/ParticipantEpisodeMemoryScope"
  }
 },
 "required": [
  "control_actions",
  "participant_memory_scope",
  "evidence_requirement_refs"
 ],
 "title": "ParticipantEpisodeResetPolicy",
 "type": "object"
}

ParticipantEpisodeResetPolicy (instantiated-scenario-v1.json, instantiated-scenario-snapshot-v1.json, materialized-scenario-v1.json, scenario-satisfiability-evidence-v1.json)

{
 "additionalProperties": false,
 "allOf": [
  {
   "else": {
    "properties": {
     "memory_reset_authority_ref": {
      "type": "null"
     }
    }
   },
   "if": {
    "properties": {
     "participant_memory_scope": {
      "const": "episode_local_reset"
     }
    }
   },
   "then": {
    "properties": {
     "memory_reset_authority_ref": {
      "type": "string"
     }
    },
    "required": [
     "memory_reset_authority_ref"
    ]
   }
  }
 ],
 "description": "Admitted reset actions, memory scope, reset authority, and evidence.",
 "properties": {
  "control_actions": {
   "items": {
    "$ref": "#/$defs/ParticipantEpisodeResetAction"
   },
   "minItems": 1,
   "title": "Control Actions",
   "type": "array",
   "uniqueItems": true
  },
  "evidence_requirement_refs": {
   "items": {
    "minLength": 1,
    "not": {
     "pattern": "\\$\\{((?:(?:[a-z0-9][a-z0-9_-]{0,63}|__private)\\.)*[a-z0-9][a-z0-9_-]{0,63})\\}"
    },
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Evidence Requirement Refs",
   "type": "array",
   "uniqueItems": true
  },
  "memory_reset_authority_ref": {
   "anyOf": [
    {
     "minLength": 1,
     "not": {
      "pattern": "\\$\\{((?:(?:[a-z0-9][a-z0-9_-]{0,63}|__private)\\.)*[a-z0-9][a-z0-9_-]{0,63})\\}"
     },
     "pattern": "\\S",
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Memory Reset Authority Ref"
  },
  "participant_memory_scope": {
   "$ref": "#/$defs/ParticipantEpisodeMemoryScope"
  }
 },
 "required": [
  "control_actions",
  "participant_memory_scope",
  "evidence_requirement_refs"
 ],
 "title": "ParticipantEpisodeResetPolicy",
 "type": "object"
}

ParticipantEpisodeTimeoutCondition (sdl-authoring-input-v1.json)

{
 "additionalProperties": false,
 "description": "Evidenced clock limit that ends the episode as timed out.",
 "properties": {
  "evidence_requirement_refs": {
   "items": {
    "minLength": 1,
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Evidence Requirement Refs",
   "type": "array",
   "uniqueItems": true
  },
  "temporal_constraint_ref": {
   "minLength": 1,
   "pattern": "\\S",
   "title": "Temporal Constraint Ref",
   "type": "string"
  },
  "terminal_reason": {
   "const": "timed_out",
   "title": "Terminal Reason",
   "type": "string"
  }
 },
 "required": [
  "terminal_reason",
  "temporal_constraint_ref",
  "evidence_requirement_refs"
 ],
 "title": "ParticipantEpisodeTimeoutCondition",
 "type": "object"
}

ParticipantEpisodeTimeoutCondition (instantiated-scenario-v1.json, instantiated-scenario-snapshot-v1.json, materialized-scenario-v1.json, scenario-satisfiability-evidence-v1.json)

{
 "additionalProperties": false,
 "description": "Evidenced clock limit that ends the episode as timed out.",
 "properties": {
  "evidence_requirement_refs": {
   "items": {
    "minLength": 1,
    "not": {
     "pattern": "\\$\\{((?:(?:[a-z0-9][a-z0-9_-]{0,63}|__private)\\.)*[a-z0-9][a-z0-9_-]{0,63})\\}"
    },
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Evidence Requirement Refs",
   "type": "array",
   "uniqueItems": true
  },
  "temporal_constraint_ref": {
   "minLength": 1,
   "not": {
    "pattern": "\\$\\{((?:(?:[a-z0-9][a-z0-9_-]{0,63}|__private)\\.)*[a-z0-9][a-z0-9_-]{0,63})\\}"
   },
   "pattern": "\\S",
   "title": "Temporal Constraint Ref",
   "type": "string"
  },
  "terminal_reason": {
   "const": "timed_out",
   "title": "Terminal Reason",
   "type": "string"
  }
 },
 "required": [
  "terminal_reason",
  "temporal_constraint_ref",
  "evidence_requirement_refs"
 ],
 "title": "ParticipantEpisodeTimeoutCondition",
 "type": "object"
}

ParticipantEpisodeTruncationCondition (sdl-authoring-input-v1.json)

{
 "additionalProperties": false,
 "description": "Evidenced assertions that end the episode as truncated.",
 "properties": {
  "assertion_refs": {
   "items": {
    "minLength": 1,
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Assertion Refs",
   "type": "array",
   "uniqueItems": true
  },
  "evidence_requirement_refs": {
   "items": {
    "minLength": 1,
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Evidence Requirement Refs",
   "type": "array",
   "uniqueItems": true
  }
 },
 "required": [
  "assertion_refs",
  "evidence_requirement_refs"
 ],
 "title": "ParticipantEpisodeTruncationCondition",
 "type": "object"
}

ParticipantEpisodeTruncationCondition (instantiated-scenario-v1.json, instantiated-scenario-snapshot-v1.json, materialized-scenario-v1.json, scenario-satisfiability-evidence-v1.json)

{
 "additionalProperties": false,
 "description": "Evidenced assertions that end the episode as truncated.",
 "properties": {
  "assertion_refs": {
   "items": {
    "minLength": 1,
    "not": {
     "pattern": "\\$\\{((?:(?:[a-z0-9][a-z0-9_-]{0,63}|__private)\\.)*[a-z0-9][a-z0-9_-]{0,63})\\}"
    },
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Assertion Refs",
   "type": "array",
   "uniqueItems": true
  },
  "evidence_requirement_refs": {
   "items": {
    "minLength": 1,
    "not": {
     "pattern": "\\$\\{((?:(?:[a-z0-9][a-z0-9_-]{0,63}|__private)\\.)*[a-z0-9][a-z0-9_-]{0,63})\\}"
    },
    "pattern": "\\S",
    "type": "string"
   },
   "minItems": 1,
   "title": "Evidence Requirement Refs",
   "type": "array",
   "uniqueItems": true
  }
 },
 "required": [
  "assertion_refs",
  "evidence_requirement_refs"
 ],
 "title": "ParticipantEpisodeTruncationCondition",
 "type": "object"
}

ParticipantEpisodeTurnOrderBasis (sdl-authoring-input-v1.json, instantiated-scenario-v1.json, instantiated-scenario-snapshot-v1.json, materialized-scenario-v1.json, scenario-satisfiability-evidence-v1.json)

{
 "description": "Authority that orders a participant's turns.",
 "enum": [
  "decision-epoch"
 ],
 "title": "ParticipantEpisodeTurnOrderBasis",
 "type": "string"
}

@doublewhy

Copy link
Copy Markdown
Contributor Author

Addressed the 2026-10-25 review at c0393184:

  1. Governance: DSL-120 now has its own participant-episode-policy-language phase before sdl-language (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, DSL-120 only; sdl-language unchanged) and requirement-scopes/307.json, so CI resolves DSL-120 for this branch and runs governance with it. check_requirement_governance.py --base-rev origin/dev exits 0 through the scope and with RAES_REQUIREMENT_UID=DSL-120 --require-governance; canonical / checks passed in run 40241006690.
  2. Merged dev with conflict resolution (94113b7a, then 2c96be81 and 7397ded4, now at 7b3918dd). The five schemas and ledger entries are regenerated. materialized-scenario-v1.json is 469,101 of 512,000 bytes (feat(sdl): add reusable mixed-control policies and occurrence contracts #1584's factoring), so this PR closes The materialized-scenario-v1 schema exceeds its 512,000-byte budget if #1463 lands before #1467 #1556. The merge also needed feat!: make reference eligibility explicit per purpose and align the editor with validation #1446's reference purposes and an imported reset-authority check (ec51ed94).
  3. The numbered releases, index edits and revision pins are gone. Fresh captures 86bf80b8 and a52b2f46 come from research_capture record.
  4. Schema diff: feat(sdl): add authored participant episode policies to behavior specifications #1463 (comment). The body is rewritten. Targeted checks and required CI are green in run 40241006690.

doublewhy added a commit that referenced this pull request Oct 26, 2026
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.
doublewhy added a commit that referenced this pull request Oct 26, 2026
…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.
@doublewhy
doublewhy marked this pull request as ready for review October 26, 2026 07:39
…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.
doublewhy added a commit that referenced this pull request Oct 26, 2026
#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.
doublewhy added a commit that referenced this pull request Oct 26, 2026
…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-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
@Brad-Edwards
Brad-Edwards added this pull request to the merge queue Nov 11, 2026
Merged via the queue into dev with commit b16b3b0 Nov 11, 2026
40 of 43 checks passed
Brad-Edwards added a commit that referenced this pull request Nov 12, 2026
…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.
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