Metadata-Version: 2.4
Name: deterministic-scenario-engine
Version: 3.1.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
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
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
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
Requires-Dist: hypothesis<7,>=6; extra == "hypothesis"
Provides-Extra: schemathesis
Requires-Dist: hypothesis<7,>=6; extra == "schemathesis"
Requires-Dist: schemathesis<5,>=4; extra == "schemathesis"
Dynamic: license-file

# 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. 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

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
- DSL 2 logical-actor execution with an explicit independent schedule seed
- canonical Result/2, Manifest/2, and Schedule/1 evidence with exact replay
- finite, ordered serial Engine 2 suites with strict offline aggregate verification
- finite explicit schedule-seed sweeps over the Engine 2 suite runner
- 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
- 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
- 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 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).
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

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 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())'
```

The source distribution version is `3.1.0`. PyPI and GitHub Releases are
authoritative for actual publication and release history. 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
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]'
```

Installing the current checkout with `python3 -m pip install .` is a
source-development-only alternative.

## Minimal quickstart

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

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).

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)
- [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)
- [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)
- [3.1.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.1.0.md)
- [Engine 2 serial suites](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/engine2-suite.md)
- [Engine 2 schedule-seed exploration](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/engine2-exploration.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 3.1.0 and
public Engine 2.0.0. PyPI and GitHub Releases are authoritative for actual
publication and release history. 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. Module-qualified Engine 2 APIs provide ordered serial
suite execution, strict aggregate verification, exact native replay, and finite
explicit schedule-seed sweeps. These additive contracts do not produce or
reinterpret historical Suite Run/2. Exhaustive exploration, distributed or
parallel execution, cross-major promotion, remote URI input, and implicit
schedule-seed derivation remain unsupported. The project is Apache-2.0 licensed.
