Metadata-Version: 2.4
Name: deterministic-scenario-engine
Version: 2.1.2
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. 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.

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