deterministic-scenario-engine 2.2.0__tar.gz → 3.0.1__tar.gz

{deterministic_scenario_engine-2.2.0 → deterministic_scenario_engine-3.0.1}/MANIFEST.in

@@ -4,6 +4,7 @@ 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.2.0/src/deterministic_scenario_engine.egg-info → deterministic_scenario_engine-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deterministic-scenario-engine
-Version: 2.2.0
+Version: 3.0.1
 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,13 @@ 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.2.0. 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. Distribution 3.0.0 was published on October 9, 2026, on
+[PyPI](https://pypi.org/project/deterministic-scenario-engine/3.0.0/) and as a
+[GitHub Release](https://github.com/imshahinul/deterministic-scenario-engine/releases/tag/3.0.0).
+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.
+PyPI and GitHub Releases remain authoritative for public-release availability
+and history.
 
 ## Why it exists
 
@@ -58,6 +61,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
@@ -80,11 +86,9 @@ make expected behavior explicit.
 - canonical evidence bundles, ordered JSON/JSONL export, compatibility reports,
   explicit adapters, closed lossless migrations, and fixture-directory export
 
-Release 2.2.0 adds first-class run → replay artifacts and fail-closed replay
-diagnostics, actionable human and machine-readable errors, author-time
-scaffolding, scenario-definition diff, conservative impact analysis, offline
-trace views, and an installed compatibility-fixture export. See the
-[2.2.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-2.2.0.md).
+The 3.0.0 release adds Engine 2.0.0 and DSL 2 while preserving Engine 1/DSL 1
+behavior and immutable evidence. See the
+[3.0.0 release 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).
@@ -104,6 +108,18 @@ python3 -m pip install deterministic-scenario-engine
 scenario --help
 ```
 
+Verify that the same active Python interpreter sees the expected distribution
+and observe the module location it actually imports:
+
+```console
+python3 -c 'from importlib.metadata import version; from pathlib import Path; import scenario_engine; print("DSE distribution:", version("deterministic-scenario-engine")); print("Imported module:", Path(scenario_engine.__file__).resolve())'
+```
+
+For this release the distribution is `3.0.1`; a source-development editable
+install resolves the module under its `src/scenario_engine` directory. The DSE
+distribution version is distinct from Engine 1 (`1.0.0`) and Engine 2 (`2.0.0`)
+compatibility versions.
+
 Install only the named optional integrations you need:
 
 ```console
@@ -151,6 +167,7 @@ self-contained offline HTML file from supported result/evidence.
 
 - [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 +179,17 @@ self-contained offline HTML file from supported result/evidence.
 - [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 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.0.md)
+- [3.0.1 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.1.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.2.0;
-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 source tree reports published distribution version
+3.0.1 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.2.0 → deterministic_scenario_engine-3.0.1}/README.md

@@ -4,10 +4,13 @@
 
 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.2.0. 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. Distribution 3.0.0 was published on October 9, 2026, on
+[PyPI](https://pypi.org/project/deterministic-scenario-engine/3.0.0/) and as a
+[GitHub Release](https://github.com/imshahinul/deterministic-scenario-engine/releases/tag/3.0.0).
+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.
+PyPI and GitHub Releases remain authoritative for public-release availability
+and history.
 
 ## Why it exists
 
@@ -21,6 +24,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
@@ -43,11 +49,9 @@ make expected behavior explicit.
 - canonical evidence bundles, ordered JSON/JSONL export, compatibility reports,
   explicit adapters, closed lossless migrations, and fixture-directory export
 
-Release 2.2.0 adds first-class run → replay artifacts and fail-closed replay
-diagnostics, actionable human and machine-readable errors, author-time
-scaffolding, scenario-definition diff, conservative impact analysis, offline
-trace views, and an installed compatibility-fixture export. See the
-[2.2.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-2.2.0.md).
+The 3.0.0 release adds Engine 2.0.0 and DSL 2 while preserving Engine 1/DSL 1
+behavior and immutable evidence. See the
+[3.0.0 release 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).
@@ -67,6 +71,18 @@ python3 -m pip install deterministic-scenario-engine
 scenario --help
 ```
 
+Verify that the same active Python interpreter sees the expected distribution
+and observe the module location it actually imports:
+
+```console
+python3 -c 'from importlib.metadata import version; from pathlib import Path; import scenario_engine; print("DSE distribution:", version("deterministic-scenario-engine")); print("Imported module:", Path(scenario_engine.__file__).resolve())'
+```
+
+For this release the distribution is `3.0.1`; a source-development editable
+install resolves the module under its `src/scenario_engine` directory. The DSE
+distribution version is distinct from Engine 1 (`1.0.0`) and Engine 2 (`2.0.0`)
+compatibility versions.
+
 Install only the named optional integrations you need:
 
 ```console
@@ -114,6 +130,7 @@ self-contained offline HTML file from supported result/evidence.
 
 - [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 +142,17 @@ self-contained offline HTML file from supported result/evidence.
 - [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 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.0.md)
+- [3.0.1 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.1.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.2.0;
-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 source tree reports published distribution version
+3.0.1 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.2.0 → deterministic_scenario_engine-3.0.1}/docs/api.md

@@ -8,8 +8,14 @@ exports.
 
 ## Constants and value objects
 
-- `ENGINE_VERSION` — engine compatibility version recorded in manifests; for
-  current manifests it remains 1.0.0 independently of distribution version.
+- `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:
+  Engine 1 Manifest/1 records 1.0.0, while Engine 2 Manifest/2 records 2.0.0;
+  both are independent of the distribution version.
 - `MISSING` — singleton semantic missing value, distinct from null.
 - `LogicalID(value: str)` — deterministic logical identifier value; users
   normally receive it from `$id` generation.
@@ -58,6 +64,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-2.2.0 → deterministic_scenario_engine-3.0.1}/docs/compatibility.md

@@ -1,13 +1,28 @@
-# Scenario Engine 1.0 compatibility contract
+# 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
 
-`ENGINE_VERSION` is the engine compatibility/replay contract version recorded
-in every `ReproducibilityManifest`. For the 1.0 release candidate it is 1.0.0
-and intentionally equals the distribution version.
+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:
 
@@ -75,8 +90,8 @@ 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. The current engine requires exact `ENGINE_VERSION`
-and exact compatibility-tuple matches. Unsupported cross-version replay fails
+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.
 

{deterministic_scenario_engine-2.2.0 → deterministic_scenario_engine-3.0.1}/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:

deterministic_scenario_engine-3.0.1/docs/dsl2-reference.md

@@ -0,0 +1,41 @@
+# DSL 2 logical-actor reference
+
+**Status: RELEASED — DSE distribution 3.0.0, published October 9, 2026.** See
+the [GitHub Release](https://github.com/imshahinul/deterministic-scenario-engine/releases/tag/3.0.0).
+
+DSL 2 is selected only by integer `dsl_version: 2` and executes with Engine
+2.0.0. It preserves DSL 1 expression, deterministic value, resource, plugin,
+clock, and atomic-step foundations while declaring ordered logical actors. Each
+actor has a canonical `scenario:/actor/<id>` address and an ordered `steps`
+sequence. Unknown keys, duplicate identifiers, noncanonical addresses, invalid
+types, and exceeded bounds fail before execution.
+
+## Execution and evidence
+
+Execution requires two independent coordinates:
+
+- `root_seed` controls addressed generation;
+- `schedule_seed` is an explicit unsigned 64-bit integer controlling scheduler
+  selection and is never inferred from the root seed.
+
+The public workflow is `scenario_engine.engine2.validate_engine2()`,
+`execute_engine2()`, and `replay_engine2()`. It produces canonical
+`scenario.result/2`, embedded `scenario.manifest/2`, and replay-authoritative
+`scenario.schedule/1`. Exact replay rejects missing, altered, mixed-major, or
+incompletely linked evidence.
+
+## Analysis and limits
+
+Result/2 supports actor-aware inspect/explain, conservative analysis, and the
+offline static trace viewer. Inclusive resource ceilings cover actors, steps,
+scheduler selections, canonical schedule bytes (8 MiB), canonical result bytes
+(32 MiB), nesting depth, and input bytes. Duplicate JSON keys, remote URIs,
+filesystem link traversal, noncanonical semantic addresses, invalid seeds, and
+secret reflection are rejected or redacted.
+
+## Unsupported capabilities
+
+DSL 1/Engine 2 and DSL 2/Engine 1 execution are unsupported. There is no silent
+migration, package-version inference, schedule-seed derivation, wall-clock or
+network discovery, or Engine 2 suite orchestration. `suite.run/2` is a strict
+schema/reader contract only.