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

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

@@ -4,6 +4,7 @@ include pyproject.toml
 recursive-include src *.py
 recursive-include docs *.md
 recursive-include examples *.yaml
+include examples/phase3_ecommerce_evidence.py
 recursive-include tests *.py
 global-exclude *.py[cod]
 global-exclude __pycache__

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

@@ -1,8 +1,13 @@
 Metadata-Version: 2.4
 Name: deterministic-scenario-engine
-Version: 2.0.0
+Version: 2.1.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
+Project-URL: Documentation, https://github.com/imshahinul/deterministic-scenario-engine/tree/main/docs
+Project-URL: Source, https://github.com/imshahinul/deterministic-scenario-engine
+Project-URL: Issues, https://github.com/imshahinul/deterministic-scenario-engine/issues
+Project-URL: Release Notes, https://github.com/imshahinul/deterministic-scenario-engine/releases
 Keywords: deterministic,scenario,testing,fixtures,replay
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
@@ -35,10 +40,10 @@ Dynamic: license-file
 
 Deterministic Scenario Engine (DSE) creates reproducible, state-consistent
 business histories and deterministic scenario suites with ground truth for
-testing. The Phase 2 contract is frozen in this source tree as an unpublished
-2.0.0 release candidate; no PyPI or GitHub release has occurred yet. Its
-distribution version is 2.0.0 while its deterministic compatibility version
-remains `ENGINE_VERSION == "1.0.0"` and its DSL version remains integer 1.
+testing. The source-tree distribution version is 2.1.1. 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.
 
 ## Why it exists
 
@@ -66,14 +71,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
-- nine-command `scenario` CLI for local and CI workflows
+- twelve-command `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
 
 Core execution does not require a database, network service, plugin, or property
-testing framework. See [security assumptions and non-goals](docs/security-and-non-goals.md).
-Phase 2 adds no hidden discovery, network, randomness, wall-clock, or ambient
-environment semantics. Its public imports, CLI contract, bounds, compatibility
-posture, and adoption guidance are frozen in the [Phase 2 public contract](docs/phase2-public-contract.md).
+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,
+wall-clock, or ambient environment semantics. The historical Phase 2 contract
+is frozen in the [Phase 2 public contract](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase2-public-contract.md); the
+additive evidence surface is frozen in the [Phase 3 public contract](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase3-public-contract.md).
 
 ## Installation
 
@@ -93,13 +102,13 @@ Install only the named optional integrations you need:
 /tmp/scenario-engine-docs-venv/bin/python -m pip install '.[schemathesis]'
 ```
 
-The release-candidate distribution is `deterministic-scenario-engine` 2.0.0. 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]'`.
+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]'`.
 
 ## Minimal quickstart
 
-The public [cart scenario](examples/cart.yaml) is an executable DSL 1 document.
+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
@@ -134,31 +143,31 @@ normalized result contains the same data under its `state` field.
 Generation derives from semantic `ExecutionAddress` values, not consumption of
 a mutable global random stream. Exact replay requires the same canonical
 scenario, explicit inputs, algorithms/plugins, and recorded execution context.
-Unsupported cross-version replay fails explicitly. See the [determinism model](docs/determinism.md),
-[reproducibility guide](docs/reproducibility.md), and normative
-[compatibility contract](docs/compatibility.md).
+Unsupported cross-version replay fails explicitly. See the [determinism model](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/determinism.md),
+[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).
 
 ## Documentation
 
-- [Quickstart](docs/quickstart.md)
-- [DSL 1 reference](docs/dsl-reference.md)
-- [Determinism model](docs/determinism.md)
-- [Reproducibility and replay](docs/reproducibility.md)
-- [Testing, faults, and oracle](docs/testing-oracle.md)
-- [Plugins](docs/plugins.md)
-- [SQLAlchemy adapter](docs/sqlalchemy.md)
-- [Hypothesis integration](docs/hypothesis.md)
-- [Schemathesis integration](docs/schemathesis.md)
-- [Public Python API](docs/api.md)
-- [Security assumptions and non-goals](docs/security-and-non-goals.md)
-- [Compatibility contract](docs/compatibility.md)
-- [Phase 2 public contract, CLI, and hard bounds](docs/phase2-public-contract.md)
+- [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)
+- [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)
+- [Plugins](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/plugins.md)
+- [SQLAlchemy adapter](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/sqlalchemy.md)
+- [Hypothesis integration](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/hypothesis.md)
+- [Schemathesis integration](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/schemathesis.md)
+- [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)
+- [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 unpublished candidate has distribution version 2.0.0,
-but generated core manifests retain `ENGINE_VERSION` 1.0.0 and DSL 1. Phase 2
-suite, composition, matrix, inspection, diff, Domain Pack, and Oracle Assertion
-contracts keep their own explicit schema versions. No 2.0.0 tag or publication
-has occurred. The project is licensed under Apache-2.0.
+separate contracts. This source tree reports distribution version 2.1.1;
+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/README.md

@@ -0,0 +1,137 @@
+# Deterministic Scenario Engine
+
+**Generate test scenarios, not just test records.**
+
+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
+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.
+
+## Why it exists
+
+Fake-data libraries and random record generators produce values; fixtures often
+describe isolated records. Scenario Engine executes histories: each committed
+step sees a consistent state, produces traceable state changes and artifacts,
+and advances an explicit logical clock. The same scenario and execution context
+can be replayed byte-for-byte, while invariants, controlled faults, and an oracle
+make expected behavior explicit.
+
+## Core capabilities
+
+- DSL 1 parsing, compilation, and deterministic execution
+- 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
+- explicit external inputs, resource DAG resolution, validators, and constraints
+- subflows, ordered branches, and bounded repeat
+- invariants, deterministic fault injection, provenance, and oracle evaluation
+- canonical result bytes and a `ReproducibilityManifest` for exact replay
+- an explicit, versioned plugin boundary and a reference ecommerce plugin pack
+- a JSON-file adapter
+- optional pytest, SQLAlchemy Core, Hypothesis, and Schemathesis integrations
+- secure, explicit local-file composition with namespaced modules
+- 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
+  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
+
+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,
+wall-clock, or ambient environment semantics. The historical Phase 2 contract
+is frozen in the [Phase 2 public contract](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase2-public-contract.md); the
+additive evidence surface is frozen in the [Phase 3 public contract](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase3-public-contract.md).
+
+## Installation
+
+From a source checkout, use a virtual environment and install the checkout:
+
+```console
+python3 -m venv /tmp/scenario-engine-docs-venv
+/tmp/scenario-engine-docs-venv/bin/python -m pip install .
+```
+
+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]'
+```
+
+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]'`.
+
+## 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.
+
+## Determinism contract
+
+Generation derives from semantic `ExecutionAddress` values, not consumption of
+a mutable global random stream. Exact replay requires the same canonical
+scenario, explicit inputs, algorithms/plugins, and recorded execution context.
+Unsupported cross-version replay fails explicitly. See the [determinism model](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/determinism.md),
+[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).
+
+## 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)
+- [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)
+- [Plugins](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/plugins.md)
+- [SQLAlchemy adapter](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/sqlalchemy.md)
+- [Hypothesis integration](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/hypothesis.md)
+- [Schemathesis integration](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/schemathesis.md)
+- [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)
+- [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;
+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.0.0 → deterministic_scenario_engine-2.1.1}/docs/api.md

@@ -1,15 +1,15 @@
 # Public Python API
 
 This is the canonical top-level Phase 1.0 contract, preserved unchanged by the
-Phase 2 freeze. Importable implementation symbols not listed here are not
-implicitly promoted to top-level public API. Specialized Phase 2 APIs are
-public through the explicit subpackages documented below, not package-root
-convenience exports.
+Phase 2 and Phase 3 freezes. Importable implementation symbols not listed here
+are not implicitly promoted to top-level public API. Specialized APIs are public
+through the explicit subpackages documented below, not package-root convenience
+exports.
 
 ## Constants and value objects
 
 - `ENGINE_VERSION` — engine compatibility version recorded in manifests; for
-  the 1.0 release candidate it intentionally equals distribution version 1.0.0.
+  current manifests it remains 1.0.0 independently of distribution version.
 - `MISSING` — singleton semantic missing value, distinct from null.
 - `LogicalID(value: str)` — deterministic logical identifier value; users
   normally receive it from `$id` generation.
@@ -185,3 +185,39 @@ paths are stable while helpers outside `__all__` are intentionally internal.
 
 The schema/version constants and all exact export manifests are executable
 contract tests. See the [complete Phase 2 contract](phase2-public-contract.md).
+
+## Phase 3 evidence APIs
+
+Phase 3 adds no package-root names. Its stable APIs are the names in `__all__`
+of `scenario_engine.evidence` and `scenario_engine.reference_packs`; helpers in
+their implementation modules are intentionally internal. Typical imports are:
+
+```python
+from scenario_engine.evidence import (
+    ArtifactDescriptor,
+    EvidenceBundle,
+    EvidenceEntry,
+    EvidenceProvenance,
+    EvidenceRelationship,
+    EvidenceType,
+    compatibility_report,
+    export_evidence_bundle,
+    plan_migration,
+    read_evidence_bundle,
+)
+from scenario_engine.reference_packs import (
+    EcommerceEvidenceWorkflow,
+    ecommerce_domain_pack,
+    export_ecommerce_evidence,
+)
+```
+
+The evidence subpackage exposes immutable bundle/entry/relationship/provenance
+models and canonicalization; bounded local reading and atomic export; canonical
+JSON/JSONL records; explicit adapter capability/publication/receipt contracts;
+finite compatibility reports and metadata-only migration plans; six closed,
+lossless executable wrapper routes; and deterministic fixture-directory export.
+`scenario_engine.reference_packs` exposes the ecommerce demonstrator and its
+existing registry factory, not a generic workflow framework. The exact public
+names, errors, schemas, limits, and compatibility posture are normative in the
+[Phase 3 public contract](phase3-public-contract.md).

{deterministic_scenario_engine-2.0.0 → deterministic_scenario_engine-2.1.1}/docs/determinism.md

@@ -81,5 +81,17 @@ evidence. Worker scheduling, filesystem enumeration, host paths, locale defaults
 environment variables, network responses, and process history are not semantic
 coordinates.
 
+Phase 3 evidence identity is the SHA-256 of canonical bundle index bytes. Entries
+bind explicit artifact paths, sizes, schemas, and content SHA-256 values;
+canonical export preserves those bytes and publishes an absent destination
+atomically. JSONL records follow caller order. Compatibility reports and
+migration plans use finite tables and deterministic canonical bytes; migration
+results bind source/target hashes and an ordered transformation tuple. Fixture
+IDs are explicit and stable, adapter receipts retain submission ordinal, and the
+ecommerce reference bundle identity is independent of destination path and
+worker scheduling. None of these downstream identities changes Phase 2 result
+or manifest semantics.
+
 See [reproducibility](reproducibility.md) for recorded context and
-[compatibility](compatibility.md) for the normative replay contract.
+[compatibility](compatibility.md) for the normative replay contract, and the
+[Phase 3 public contract](phase3-public-contract.md) for evidence identity.

{deterministic_scenario_engine-2.0.0 → deterministic_scenario_engine-2.1.1}/docs/phase2-public-contract.md

@@ -1,13 +1,16 @@
 # Phase 2 Public Contract Freeze
 
-This document defines the upcoming Phase 2 / 2.0 public contract implemented in
-this source tree. It is an unpublished 2.0.0 release candidate; no PyPI or
-GitHub release has occurred yet. Distribution metadata is 2.0.0, while the
+This document defines the historical Phase 2 / 2.0 public contract. Version
+2.0.0 has since been published to PyPI and as a GitHub Release. Distribution
+metadata remains 2.0.0 in the current source tree, while the
 deterministic core compatibility token recorded in manifests remains
 `ENGINE_VERSION == "1.0.0"`. DSL version remains integer 1. Distribution release
 identity and engine compatibility are distinct concepts. Composition, matrix,
 suite, inspection, diff, Domain Pack, and Oracle Assertion contracts retain
 their independent schema versions and do not reinterpret valid v1 documents.
+The additive, currently unreleased Phase 3 evidence contract is documented
+separately in the [Phase 3 public contract](phase3-public-contract.md); its
+eventual distribution target is 2.1.0.
 
 ## Supported product surface