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

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

@@ -1,7 +1,9 @@
 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 docs *.md
 recursive-include examples *.yaml
 include examples/phase3_ecommerce_evidence.py

{deterministic_scenario_engine-2.1.1/src/deterministic_scenario_engine.egg-info → deterministic_scenario_engine-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deterministic-scenario-engine
-Version: 2.1.1
+Version: 2.2.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
@@ -25,6 +25,7 @@ License-File: LICENSE
 Requires-Dist: PyYAML==6.0.3
 Provides-Extra: pytest
 Requires-Dist: pytest<10,>=9.1; extra == "pytest"
+Requires-Dist: build<2,>=1; extra == "pytest"
 Provides-Extra: sqlalchemy
 Requires-Dist: SQLAlchemy<3,>=2.0; extra == "sqlalchemy"
 Provides-Extra: hypothesis
@@ -40,7 +41,7 @@ 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.1. Distribution release
+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.
@@ -71,12 +72,20 @@ 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
 
+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).
+
 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,
@@ -86,57 +95,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
 
@@ -147,6 +134,19 @@ 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)
@@ -161,13 +161,14 @@ 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)
 - [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.1;
+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.

{deterministic_scenario_engine-2.1.1 → deterministic_scenario_engine-2.2.0}/README.md

@@ -4,7 +4,7 @@
 
 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.1. Distribution release
+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.
@@ -35,12 +35,20 @@ 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
 
+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).
+
 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 +58,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,6 +97,19 @@ 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)
@@ -125,13 +124,14 @@ 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)
 - [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.1;
+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.

{deterministic_scenario_engine-2.1.1 → deterministic_scenario_engine-2.2.0}/docs/compatibility.md

@@ -80,6 +80,98 @@ and exact compatibility-tuple matches. 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,

{deterministic_scenario_engine-2.1.1 → deterministic_scenario_engine-2.2.0}/docs/phase2-architecture.md

@@ -275,7 +275,7 @@ From the 2026-09-03 freeze, the likely range is roughly late October through lat
 
 ## V1 Contract Validation
 
-Pre-mutation validation ran from repository root `/Users/smshahinulislam/Developer/scenario-engine` on branch `main`. HEAD/main/origin-main were `ee29f52f714e84f17e1048ce24192fcf1c69345a`, tree `2a61915d578dcb1c4ec94049350a24d2cabdf721`, divergence `0/0`, with zero staged, unstaged, or untracked paths. The sole remote was `origin`, resolving to public `imshahinul/deterministic-scenario-engine`; tag `1.0.0` peeled to the baseline and its tree.
+Pre-mutation validation ran from `<repository-root>` on branch `main`. HEAD/main/origin-main were `ee29f52f714e84f17e1048ce24192fcf1c69345a`, tree `2a61915d578dcb1c4ec94049350a24d2cabdf721`, divergence `0/0`, with zero staged, unstaged, or untracked paths. The sole remote was `origin`, resolving to public `imshahinul/deterministic-scenario-engine`; tag `1.0.0` peeled to the baseline and its tree.
 
 Validation used CPython 3.14.6 in isolated environment `/tmp/dse-phase2-0a-venv`, pytest 9.1.1, PyYAML 6.0.3, SQLAlchemy 2.0.52, Hypothesis 6.167.1, and Schemathesis 4.25.2, with repository `src` on `PYTHONPATH`. Canonical validation is `python -m pytest -q`; collection is `python -m pytest --collect-only -q`. It collected 280 tests and the full run passed: `280 passed, 136 subtests passed` in 41.94 seconds. Focused golden enforcement passed 4 tests and 3 subtests.
 

{deterministic_scenario_engine-2.1.1 → deterministic_scenario_engine-2.2.0}/docs/phase3-public-contract.md

@@ -23,8 +23,8 @@ intentionally internal.
 ```text
 scenario_engine count=33
 scenario_engine sha256=f19f9c8ebe3fd5574550fea1fdefc5a20fa004a4913978e8bf5ab1e447278a50
-scenario_engine.suite count=44
-scenario_engine.suite sha256=7db8a4edf260d1d16960203dfa43672d1d9cb8e4eed1624be87a9201ded59512
+scenario_engine.suite count=45
+scenario_engine.suite sha256=2aa92ef099e841092afdfac9d8fbf7f2b5bd48898383b8810afdd85ed3116e98
 scenario_engine.composition count=29
 scenario_engine.composition sha256=689f1fecb3bbbe4822ce523e09084857f9da625a31b4b1e9bbc447d3bc425fe7
 scenario_engine.matrix count=25