deterministic-scenario-engine 2.1.2__tar.gz → 3.0.0__tar.gz

{deterministic_scenario_engine-2.1.2 → deterministic_scenario_engine-3.0.0}/MANIFEST.in

@@ -1,7 +1,10 @@
 include LICENSE
 include README.md
+include setup.py
 include pyproject.toml
 recursive-include src *.py
+recursive-include src/scenario_engine/data/compatibility/phase4_11 *
+recursive-include src/scenario_engine/data/compatibility/phase5_10 *
 recursive-include docs *.md
 recursive-include examples *.yaml
 include examples/phase3_ecommerce_evidence.py

{deterministic_scenario_engine-2.1.2/src/deterministic_scenario_engine.egg-info → deterministic_scenario_engine-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deterministic-scenario-engine
-Version: 2.1.2
+Version: 3.0.0
 Summary: Reproducible, state-consistent business scenarios with deterministic ground truth
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/imshahinul/deterministic-scenario-engine
@@ -41,10 +41,11 @@ Dynamic: license-file
 
 Deterministic Scenario Engine (DSE) creates reproducible, state-consistent
 business histories and deterministic scenario suites with ground truth for
-testing. The source-tree distribution version is 2.1.2. Distribution release
-identity and deterministic compatibility identity are separate:
-`ENGINE_VERSION` remains 1.0.0 and DSL version remains 1. For authoritative
-public-release availability and history, see PyPI and GitHub Releases.
+testing. This source tree is the prepublication distribution 3.0.0 candidate.
+Distribution and execution compatibility identities are separate: public
+`ENGINE_VERSION` is 2.0.0, while the preserved DSL 1 path records Engine 1.0.0.
+This statement does not assert package-index publication; PyPI and GitHub
+Releases remain authoritative for public-release availability and history.
 
 ## Why it exists
 
@@ -58,6 +59,9 @@ make expected behavior explicit.
 ## Core capabilities
 
 - DSL 1 parsing, compilation, and deterministic execution
+- DSL 2 logical-actor execution with an explicit independent schedule seed
+- canonical Result/2, Manifest/2, and Schedule/1 evidence with exact replay
+- actor-aware inspect/explain and deterministic offline trace viewing
 - addressed randomness and logical IDs that do not depend on a shared stream
 - current state plus append-only committed history and artifacts
 - whole-step atomicity
@@ -72,12 +76,18 @@ make expected behavior explicit.
 - ordered Cartesian matrices with stable case IDs and original indexes
 - immutable ordered batch plans and worker-independent results
 - structured, redacted inspect/explain evidence and typed RFC 6901 semantic diff
-- twelve-command `scenario` CLI for local and CI workflows, including bounded
+- validated scenario-definition structural diff with canonical semantic addresses
+- self-contained, deterministic offline HTML trace views of local result evidence
+- `scenario` CLI for local and CI workflows, including bounded
   local evidence export, verification, and lossless migration
 - explicit immutable Domain Pack registries and pure Oracle Assertions
 - canonical evidence bundles, ordered JSON/JSONL export, compatibility reports,
   explicit adapters, closed lossless migrations, and fixture-directory export
 
+The 3.0.0 candidate adds Engine 2.0.0 and DSL 2 while preserving Engine 1/DSL 1
+behavior and immutable evidence. See the
+[3.0.0 candidate notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.0.md).
+
 Core execution does not require a database, network service, plugin, or property
 testing framework. See [security assumptions and non-goals](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/security-and-non-goals.md).
 Neither Phase 2 nor Phase 3 adds hidden discovery, network, randomness,
@@ -87,57 +97,35 @@ additive evidence surface is frozen in the [Phase 3 public contract](https://git
 
 ## Installation
 
-From a source checkout, use a virtual environment and install the checkout:
+Supported Python versions are 3.11, 3.12, 3.13, and 3.14.
+
+Install the published package and use its `scenario` entry point:
 
 ```console
-python3 -m venv /tmp/scenario-engine-docs-venv
-/tmp/scenario-engine-docs-venv/bin/python -m pip install .
+python3 -m pip install deterministic-scenario-engine
+scenario --help
 ```
 
 Install only the named optional integrations you need:
 
 ```console
-/tmp/scenario-engine-docs-venv/bin/python -m pip install '.[pytest]'
-/tmp/scenario-engine-docs-venv/bin/python -m pip install '.[sqlalchemy]'
-/tmp/scenario-engine-docs-venv/bin/python -m pip install '.[hypothesis]'
-/tmp/scenario-engine-docs-venv/bin/python -m pip install '.[schemathesis]'
+python3 -m pip install 'deterministic-scenario-engine[pytest]'
+python3 -m pip install 'deterministic-scenario-engine[sqlalchemy]'
+python3 -m pip install 'deterministic-scenario-engine[hypothesis]'
+python3 -m pip install 'deterministic-scenario-engine[schemathesis]'
 ```
 
-Install the package with `pip install deterministic-scenario-engine`, or select
-an optional integration with a command such as
-`pip install 'deterministic-scenario-engine[pytest]'`.
+Installing the current checkout with `python3 -m pip install .` is a
+source-development-only alternative.
 
 ## Minimal quickstart
 
-The public [cart scenario](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/examples/cart.yaml) is an executable DSL 1 document.
-Run it from the repository root:
-
-```python
-from pathlib import Path
-
-from scenario_engine import (
-    compile_document,
-    parse_yaml,
-    replay_scenario,
-    run_scenario,
-)
-
-yaml_text = Path("examples/cart.yaml").read_text(encoding="utf-8")
-document = parse_yaml(yaml_text)
-scenario = compile_document(document)
-result = run_scenario(scenario, root_seed="quickstart", run_index=0)
-
-print(result.final_state["checkout_complete"])
-print(result.trace())
-stable_bytes = result.to_json_bytes()
-manifest = result.manifest
-
-replayed = replay_scenario(yaml_text, manifest)
-assert replayed.to_json_bytes() == stable_bytes
-```
-
-`ScenarioResult.final_state` is the supported state-reading property; the stable
-normalized result contains the same data under its `state` field.
+The [canonical installed-package workflows](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/quickstart.md)
+start by creating a complete portable DSL file under `/tmp/dse-demo`; they do
+not require a source checkout or files from this repository. The guide covers
+validate, run → replay, inspect/explain, both diff commands, conservative impact
+analysis, export → verify, the static trace viewer, scaffold → validate, and the
+human/machine diagnostic contract.
 
 ## Determinism contract
 
@@ -148,10 +136,24 @@ Unsupported cross-version replay fails explicitly. See the [determinism model](h
 [reproducibility guide](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/reproducibility.md), and normative
 [compatibility contract](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/compatibility.md).
 
+The installed public compatibility corpus can be discovered with
+`scenario --help` and exported without a source checkout using
+`scenario compatibility-fixtures export --out /absolute/path`.
+
+## Canonical command workflows
+
+Use the [quickstart](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/quickstart.md#canonical-installed-package-workflows)
+as the single canonical workflow document. In particular, `scenario diff`
+compares execution artifacts, while `scenario diff-definition` structurally
+compares validated scenario definitions. `scenario impact` is a separate,
+conservative static may-impact analysis. `scenario trace-view` creates one
+self-contained offline HTML file from supported result/evidence.
+
 ## Documentation
 
 - [Quickstart](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/quickstart.md)
 - [DSL 1 reference](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/dsl-reference.md)
+- [DSL 2 reference](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/dsl2-reference.md)
 - [Determinism model](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/determinism.md)
 - [Reproducibility and replay](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/reproducibility.md)
 - [Testing, faults, and oracle](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/testing-oracle.md)
@@ -162,13 +164,17 @@ Unsupported cross-version replay fails explicitly. See the [determinism model](h
 - [Public Python API](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/api.md)
 - [Security assumptions and non-goals](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/security-and-non-goals.md)
 - [Compatibility contract](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/compatibility.md)
+- [2.2.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-2.2.0.md)
+- [3.0.0 candidate notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.0.md)
 - [Phase 2 public contract, CLI, and hard bounds](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase2-public-contract.md)
 - [Phase 3 public contract and evidence interchange](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase3-public-contract.md)
 
 ## Status
 
 Distribution release identity and deterministic engine compatibility are
-separate contracts. This source tree reports distribution version 2.1.2;
-generated core manifests retain `ENGINE_VERSION` 1.0.0 and DSL 1. PyPI and
-GitHub Releases are the authoritative sources for public-release availability
-and history. The project is licensed under Apache-2.0.
+separate contracts. This prepublication source tree reports distribution
+version 3.0.0 and public Engine 2.0.0. Engine 1 manifests remain exactly 1.0.0
+with integer DSL 1; Engine 2 manifests use 2.0.0 with integer DSL 2. Supported
+Python versions are 3.11–3.14. Suite Run/2 is reader/schema support only; Engine
+2 suite orchestration, cross-major promotion, remote URI input, and implicit
+schedule-seed derivation are unsupported. The project is Apache-2.0 licensed.

{deterministic_scenario_engine-2.1.2 → deterministic_scenario_engine-3.0.0}/README.md

@@ -4,10 +4,11 @@
 
 Deterministic Scenario Engine (DSE) creates reproducible, state-consistent
 business histories and deterministic scenario suites with ground truth for
-testing. The source-tree distribution version is 2.1.2. Distribution release
-identity and deterministic compatibility identity are separate:
-`ENGINE_VERSION` remains 1.0.0 and DSL version remains 1. For authoritative
-public-release availability and history, see PyPI and GitHub Releases.
+testing. This source tree is the prepublication distribution 3.0.0 candidate.
+Distribution and execution compatibility identities are separate: public
+`ENGINE_VERSION` is 2.0.0, while the preserved DSL 1 path records Engine 1.0.0.
+This statement does not assert package-index publication; PyPI and GitHub
+Releases remain authoritative for public-release availability and history.
 
 ## Why it exists
 
@@ -21,6 +22,9 @@ make expected behavior explicit.
 ## Core capabilities
 
 - DSL 1 parsing, compilation, and deterministic execution
+- DSL 2 logical-actor execution with an explicit independent schedule seed
+- canonical Result/2, Manifest/2, and Schedule/1 evidence with exact replay
+- actor-aware inspect/explain and deterministic offline trace viewing
 - addressed randomness and logical IDs that do not depend on a shared stream
 - current state plus append-only committed history and artifacts
 - whole-step atomicity
@@ -35,12 +39,18 @@ make expected behavior explicit.
 - ordered Cartesian matrices with stable case IDs and original indexes
 - immutable ordered batch plans and worker-independent results
 - structured, redacted inspect/explain evidence and typed RFC 6901 semantic diff
-- twelve-command `scenario` CLI for local and CI workflows, including bounded
+- validated scenario-definition structural diff with canonical semantic addresses
+- self-contained, deterministic offline HTML trace views of local result evidence
+- `scenario` CLI for local and CI workflows, including bounded
   local evidence export, verification, and lossless migration
 - explicit immutable Domain Pack registries and pure Oracle Assertions
 - canonical evidence bundles, ordered JSON/JSONL export, compatibility reports,
   explicit adapters, closed lossless migrations, and fixture-directory export
 
+The 3.0.0 candidate adds Engine 2.0.0 and DSL 2 while preserving Engine 1/DSL 1
+behavior and immutable evidence. See the
+[3.0.0 candidate notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.0.md).
+
 Core execution does not require a database, network service, plugin, or property
 testing framework. See [security assumptions and non-goals](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/security-and-non-goals.md).
 Neither Phase 2 nor Phase 3 adds hidden discovery, network, randomness,
@@ -50,57 +60,35 @@ additive evidence surface is frozen in the [Phase 3 public contract](https://git
 
 ## Installation
 
-From a source checkout, use a virtual environment and install the checkout:
+Supported Python versions are 3.11, 3.12, 3.13, and 3.14.
+
+Install the published package and use its `scenario` entry point:
 
 ```console
-python3 -m venv /tmp/scenario-engine-docs-venv
-/tmp/scenario-engine-docs-venv/bin/python -m pip install .
+python3 -m pip install deterministic-scenario-engine
+scenario --help
 ```
 
 Install only the named optional integrations you need:
 
 ```console
-/tmp/scenario-engine-docs-venv/bin/python -m pip install '.[pytest]'
-/tmp/scenario-engine-docs-venv/bin/python -m pip install '.[sqlalchemy]'
-/tmp/scenario-engine-docs-venv/bin/python -m pip install '.[hypothesis]'
-/tmp/scenario-engine-docs-venv/bin/python -m pip install '.[schemathesis]'
+python3 -m pip install 'deterministic-scenario-engine[pytest]'
+python3 -m pip install 'deterministic-scenario-engine[sqlalchemy]'
+python3 -m pip install 'deterministic-scenario-engine[hypothesis]'
+python3 -m pip install 'deterministic-scenario-engine[schemathesis]'
 ```
 
-Install the package with `pip install deterministic-scenario-engine`, or select
-an optional integration with a command such as
-`pip install 'deterministic-scenario-engine[pytest]'`.
+Installing the current checkout with `python3 -m pip install .` is a
+source-development-only alternative.
 
 ## Minimal quickstart
 
-The public [cart scenario](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/examples/cart.yaml) is an executable DSL 1 document.
-Run it from the repository root:
-
-```python
-from pathlib import Path
-
-from scenario_engine import (
-    compile_document,
-    parse_yaml,
-    replay_scenario,
-    run_scenario,
-)
-
-yaml_text = Path("examples/cart.yaml").read_text(encoding="utf-8")
-document = parse_yaml(yaml_text)
-scenario = compile_document(document)
-result = run_scenario(scenario, root_seed="quickstart", run_index=0)
-
-print(result.final_state["checkout_complete"])
-print(result.trace())
-stable_bytes = result.to_json_bytes()
-manifest = result.manifest
-
-replayed = replay_scenario(yaml_text, manifest)
-assert replayed.to_json_bytes() == stable_bytes
-```
-
-`ScenarioResult.final_state` is the supported state-reading property; the stable
-normalized result contains the same data under its `state` field.
+The [canonical installed-package workflows](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/quickstart.md)
+start by creating a complete portable DSL file under `/tmp/dse-demo`; they do
+not require a source checkout or files from this repository. The guide covers
+validate, run → replay, inspect/explain, both diff commands, conservative impact
+analysis, export → verify, the static trace viewer, scaffold → validate, and the
+human/machine diagnostic contract.
 
 ## Determinism contract
 
@@ -111,10 +99,24 @@ Unsupported cross-version replay fails explicitly. See the [determinism model](h
 [reproducibility guide](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/reproducibility.md), and normative
 [compatibility contract](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/compatibility.md).
 
+The installed public compatibility corpus can be discovered with
+`scenario --help` and exported without a source checkout using
+`scenario compatibility-fixtures export --out /absolute/path`.
+
+## Canonical command workflows
+
+Use the [quickstart](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/quickstart.md#canonical-installed-package-workflows)
+as the single canonical workflow document. In particular, `scenario diff`
+compares execution artifacts, while `scenario diff-definition` structurally
+compares validated scenario definitions. `scenario impact` is a separate,
+conservative static may-impact analysis. `scenario trace-view` creates one
+self-contained offline HTML file from supported result/evidence.
+
 ## Documentation
 
 - [Quickstart](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/quickstart.md)
 - [DSL 1 reference](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/dsl-reference.md)
+- [DSL 2 reference](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/dsl2-reference.md)
 - [Determinism model](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/determinism.md)
 - [Reproducibility and replay](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/reproducibility.md)
 - [Testing, faults, and oracle](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/testing-oracle.md)
@@ -125,13 +127,17 @@ Unsupported cross-version replay fails explicitly. See the [determinism model](h
 - [Public Python API](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/api.md)
 - [Security assumptions and non-goals](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/security-and-non-goals.md)
 - [Compatibility contract](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/compatibility.md)
+- [2.2.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-2.2.0.md)
+- [3.0.0 candidate notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.0.md)
 - [Phase 2 public contract, CLI, and hard bounds](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase2-public-contract.md)
 - [Phase 3 public contract and evidence interchange](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase3-public-contract.md)
 
 ## Status
 
 Distribution release identity and deterministic engine compatibility are
-separate contracts. This source tree reports distribution version 2.1.2;
-generated core manifests retain `ENGINE_VERSION` 1.0.0 and DSL 1. PyPI and
-GitHub Releases are the authoritative sources for public-release availability
-and history. The project is licensed under Apache-2.0.
+separate contracts. This prepublication source tree reports distribution
+version 3.0.0 and public Engine 2.0.0. Engine 1 manifests remain exactly 1.0.0
+with integer DSL 1; Engine 2 manifests use 2.0.0 with integer DSL 2. Supported
+Python versions are 3.11–3.14. Suite Run/2 is reader/schema support only; Engine
+2 suite orchestration, cross-major promotion, remote URI input, and implicit
+schedule-seed derivation are unsupported. The project is Apache-2.0 licensed.

{deterministic_scenario_engine-2.1.2 → deterministic_scenario_engine-3.0.0}/docs/api.md

@@ -8,6 +8,11 @@ exports.
 
 ## Constants and value objects
 
+- `scenario_engine.ENGINE_VERSION` — public current Engine coordinate, `2.0.0`.
+- `scenario_engine._version.VERSION` — distribution coordinate, `3.0.0`.
+- `scenario_engine._version.ENGINE1_VERSION` — explicit historical Engine 1
+  execution coordinate, `1.0.0`; not added to the frozen package-root exports.
+
 - `ENGINE_VERSION` — engine compatibility version recorded in manifests; for
   current manifests it remains 1.0.0 independently of distribution version.
 - `MISSING` — singleton semantic missing value, distinct from null.
@@ -58,6 +63,43 @@ checks recorded compatibility before returning a replayed `ScenarioResult`.
 `evaluate_scenario()` returns `OracleEvaluation` and optionally raises on an
 oracle mismatch.
 
+### Engine 2 explicit public workflow
+
+These names are explicitly public from `scenario_engine.engine2` (execution and
+replay) and `scenario_engine.compatibility` (classification). They are not added
+to the compatibility-frozen package root.
+
+```python
+validate_engine2(yaml_text: str) -> CompiledScenarioV2
+execute_engine2(scenario: CompiledScenarioV2, root_seed: str | int, schedule_seed: int, *, run_index: int = 0, inputs: Mapping[str, Any] | None = None, plugins: PluginRegistry | None = None) -> tuple[Engine2Result, ScheduleArtifact]
+replay_engine2(result: Engine2Result | bytes | str, schedule: ScheduleArtifact | bytes | str, scenario: CompiledScenarioV2, *, inputs: Mapping[str, Any] | None = None, plugins: PluginRegistry | None = None) -> Engine2Result
+classify_engine_contract(*, dsl_version: int | None, engine_version: str | None, result_contract: str | None, operation: str) -> CompatibilityDecision
+```
+
+`validate_engine2()` accepts only DSL 2. `execute_engine2()` requires both the
+generation root seed and independent schedule seed and returns immutable,
+canonically serializable Result/2 and Schedule/1 evidence. `replay_engine2()`
+strictly reads supplied evidence when bytes or text are given, independently
+executes every recorded scheduler choice, verifies all coordinates and final
+observations, and returns the verified immutable Result/2. It never reconstructs
+missing schedule evidence. Compatibility classification is explicit and does not
+execute, migrate, or promote evidence. Existing Engine 1 functions are unchanged.
+
+`schedule_seed` is a required independent unsigned 64-bit coordinate. It is not
+derived from `root_seed`. Engine 2 writes Result/2, Manifest/2, and Schedule/1;
+exact replay requires the matching result, schedule, scenario, and explicit
+inputs. Actor-aware analysis is exposed through the existing inspection,
+explanation, impact, and offline `scenario_engine.trace_view` surfaces.
+
+The immutable Engine 2 evidence access names are also public from their explicit
+modules: `Engine2Manifest`, `Engine2Result`, `ScheduleReference`,
+`read_manifest2()`, `read_result2()`, and their canonical byte functions from
+`scenario_engine.engine2`; and `ScheduleArtifact`, `read_schedule()`, and its
+canonical byte functions from `scenario_engine.schedule`. `read_suite_run2()` is
+schema/reader validation only and does not execute a suite. Errors remain in the
+`Engine2EvidenceError`/`Engine2EvidenceBoundError`/`Engine2ReplayMismatch` and
+`ScheduleError`/`ScheduleBoundError`/`ScheduleReplayMismatch` families.
+
 ## Canonical scenario functions
 
 ```python

deterministic_scenario_engine-3.0.0/docs/compatibility.md

@@ -0,0 +1,198 @@
+# Scenario Engine 3.0 compatibility contract
+
+This document is normative for the frozen DSL, deterministic result, manifest,
+and plugin contracts. Distribution metadata remains a packaging concern.
+
+## Version roles
+
+Distribution `VERSION` is 3.0.0 and public `ENGINE_VERSION` is 2.0.0. The
+historical Engine 1 coordinate is independently fixed at 1.0.0: every
+`scenario.manifest/1` produced by DSL 1 continues to record 1.0.0. Engine 2
+Manifest/2 records 2.0.0. Package version is never inferred as an execution
+coordinate.
+
+## Canonical compatibility matrix
+
+| DSL | Engine | Execution/replay |
+| --- | --- | --- |
+| integer `1` | `1.0.0` | supported: Result/1, Manifest/1, Suite Run/1 |
+| integer `2` | `2.0.0` | supported: Result/2, Manifest/2, Schedule/1 |
+| integer `1` | `2.0.0` | unsupported cross-major |
+| integer `2` | `1.0.0` | unsupported cross-major |
+
+Unknown, mixed-major, missing, and incomplete tuples fail closed. Reading does
+not silently migrate evidence. Suite Run/2 support is schema/reader-only and
+does not provide Engine 2 suite orchestration.
+
+Engine SemVer has these meanings:
+
+* **Major:** breaks a public API, accepted DSL, result schema, manifest schema,
+  replay gate, or deterministic semantic contract.
+* **Minor:** adds backward-compatible behavior or a newly and explicitly
+  versioned deterministic algorithm.
+* **Patch:** makes backward-compatible corrections without silently changing
+  deterministic bytes inside the documented contract. A correctness or
+  security correction that must change such bytes requires an explicit
+  compatibility/version response.
+
+## DSL 1.0
+
+DSL version 1 is the integer `1`, never a boolean. Unknown fields are errors.
+Accepted syntax, defaults, order, and types are not silently reinterpreted;
+breaking changes require a new DSL version and/or major engine contract.
+
+Parsing uses safe YAML construction. Duplicate mapping keys at every depth,
+aliases, merge keys, arbitrary tags, floats as semantic values, and non-string
+semantic mapping keys are rejected. Plain `true` and `false` are booleans;
+legacy YAML 1.1 words (`yes`, `no`, `on`, `off`) are strings. Decimal integer
+syntax is accepted; ambiguous legacy integer forms are strings. Standard null
+spellings resolve to null. Semantic decimal, datetime, duration, and missing
+values use their explicit typed wrappers.
+
+Arithmetic operators accept only integers (excluding booleans) and finite
+`Decimal` values. Addition, subtraction, and multiplication return an integer
+for two integer operands and a `Decimal` if either operand is decimal. Division
+always returns `Decimal`; division by zero is an expression error. Decimal
+operations use precision 28 with round-half-even and never the caller's ambient
+decimal context. Strings, lists, booleans, null, missing, duration, and arbitrary
+Python operator overloads are not arithmetic operands.
+
+Optional empty-container behavior remains compatibility-frozen: `validators`,
+`invariants`, and `faults` may be empty; `resources`, `constraints`, and
+`subflows` may not be explicitly empty. Empty `oracle.expected.constraints` and
+`oracle.expected.invariants` collections are accepted.
+
+## Result and manifest
+
+`ScenarioResult` required stable normalized top-level fields are `artifacts`,
+`clock`, `history`, `manifest`, `next`, `scenario_id`, `state`, and
+`terminal_transition`. `provenance` is optional stable and appears only when it
+has records. `next` is retained as a compatibility alias and is always identical
+to `terminal_transition`. Runner, resources, and snapshot backing fields are
+internal and not separately serialized.
+
+Artifact fields are `address`, `id`, `name`, `type`, and `value`. History fields
+are `address`, `artifacts`, `faults_applied`, `patch`, `post`, `pre`, `timestamp`,
+and `transition`. Addresses are canonical JSON strings. Provenance and manifest
+records use their normalized public mappings. Canonical result bytes are UTF-8,
+semantic normalization, sorted keys, compact comma/colon separators, and no
+trailing newline.
+
+The stable manifest fields are `root_seed`, `scenario_canonical_hash`,
+`engine_version`, `dsl_version`, `input_resource_hashes`,
+`domain_pack_versions`, `generator_versions`, `rng_algorithm_version`,
+`id_algorithm_version`, `locale`, `reference_clock_start`, and `run_index`.
+Mappings normalize in key order. `domain_pack_versions` is reserved and must be
+empty; replay rejects it otherwise. All other fields are active execution
+coordinates or compatibility gates. A future additive field needs explicit
+default and reader rules; unknown data is not silently treated as compatible.
+
+Exact replay requires a compatible recorded engine contract, DSL version,
+RNG/ID and generator/plugin algorithm versions, canonical scenario hash,
+input/resource hashes, root seed, run index, locale, reference clock, and other
+explicit execution context. Each engine requires its exact immutable execution
+coordinate and compatibility-tuple match. Unsupported cross-version replay fails
+explicitly; indefinite replay across incompatible future major versions is not
+promised.
+
+## Cross-version assurance
+
+Inspection support is intentionally independent from replay support: an artifact
+may remain safely inspectable while exact replay is rejected. Migration is an
+explicit, non-destructive operation and is available only for already-supported
+routes; reading never silently migrates an artifact. Unsupported and unknown
+contracts or versions fail closed rather than being treated as current-compatible.
+
+These boundaries are tested against a small immutable corpus whose bytes,
+provenance, SHA-256 values, and per-operation expectations are frozen under the
+`scenario.compatibility-fixtures/1` manifest. The corpus represents selected
+public states and synthetic negative cases; it is not a promise of universal
+backward compatibility.
+
+### Consuming the compatibility fixture bundle
+
+Starting only from an installed Scenario Engine, discover this workflow through
+`scenario --help`, then export the complete frozen corpus to an absent absolute
+local directory (no source checkout or network access is required):
+
+```sh
+scenario compatibility-fixtures export --out /absolute/path/phase4_11
+cd /absolute/path/phase4_11
+```
+
+The fixture manifest's optional `scenario_resource` and `inputs_resource`
+fields identify the immutable public resources needed to construct replay
+commands. The bundle contains current, historical, and synthetic artifacts for
+replay, inspect, migrate, and compatibility exercises. Its bytes are frozen.
+`--inputs` takes a bounded JSON object, so the companion file is read as the
+argument instead of copying a magic value into shell quoting.
+
+The current fixture replays with its published scenario and inputs:
+
+```sh
+scenario --json replay artifacts/current-2.1.2-suite-run-v1.json \
+  --scenario scenarios/compatibility_case.yaml \
+  --inputs "$(cat inputs/current-2.1.2-suite-run-v1.inputs.json)"
+```
+
+The historical 2.0.0 suite fixture remains replayable with its own published
+inputs:
+
+```sh
+scenario --json replay artifacts/historical-2.0.0-suite-run-v1.json \
+  --scenario scenarios/compatibility_case.yaml \
+  --inputs "$(cat inputs/historical-2.0.0-suite-run-v1.inputs.json)"
+```
+
+The historical 1.0.0 result is inspectable and migratable but is not a supported
+replay artifact. This command fails closed with exit 5 and
+`ENGINE_VERSION_UNSUPPORTED` in the `scenario.error/1` envelope:
+
+```sh
+scenario --json replay artifacts/historical-1.0.0-result-v1.json \
+  --scenario scenarios/compatibility_case.yaml
+```
+
+Omitting the current artifact's required inputs fails with
+`REPLAY_DATA_INCOMPLETE`:
+
+```sh
+scenario --json replay artifacts/current-2.1.2-suite-run-v1.json \
+  --scenario scenarios/compatibility_case.yaml
+```
+
+An unknown engine compatibility value fails closed with
+`ENGINE_VERSION_UNSUPPORTED`:
+
+```sh
+scenario --json replay artifacts/synthetic-unknown-engine-suite-run-v1.json \
+  --scenario scenarios/compatibility_case.yaml --inputs '{"selected":7}'
+```
+
+Its existing lossless migration route can be exercised without repository or
+maintainer-local paths. The migration CLI requires absolute local source and
+destination paths, so derive both from the fixture workspace:
+
+```sh
+BUNDLE="$(pwd)"
+scenario --json migrate "$BUNDLE/artifacts/historical-1.0.0-result-v1.json" \
+  "$BUNDLE/migrated-historical-1.0.0" --artifact-kind result \
+  --schema-version scenario.result/1 --product-version 1.0.0 \
+  --source-sha256 ea7068eac7888857800c2784eb1e662dbe7de4bb62f89e2e26f23b9150dc3a67
+```
+
+Replay input values are external execution data, not recoverable from their
+recorded fingerprints. When an artifact records required external inputs,
+omitting them or supplying data that cannot be resolved fails closed with exit
+5, `REPLAY_DATA_INCOMPLETE`, and the next action
+`PROVIDE_REQUIRED_REPLAY_INPUTS`; it never reveals a hash preimage.
+
+## Plugins
+
+A plugin name identifies a generator family. Its version is an exact,
+immutable deterministic algorithm-contract identifier and is recorded under
+`plugin:<name>` in `generator_versions`. Behavior-changing implementations must
+use another version. Replay requires an explicitly registered compatible name
+and version; unavailable or incompatible versions fail and are never silently
+substituted. Package-release and deterministic-algorithm versions may differ.
+There is no discovery, migration, network retrieval, or global registry contract.

{deterministic_scenario_engine-2.1.2 → deterministic_scenario_engine-3.0.0}/docs/dsl-reference.md

@@ -3,6 +3,10 @@
 This reference describes the frozen Scenario Engine DSL 1 grammar and semantics.
 Unknown keys are rejected in every schema-defined mapping.
 
+DSL 1 remains bound to Engine 1.0.0, Result/1, Manifest/1, and Suite Run/1 in
+distribution 3.0.0. Public Engine 2.0.0 does not promote or reinterpret DSL 1.
+See [DSL 2](dsl2-reference.md) for logical actors.
+
 ## Root document
 
 Required root keys are: