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

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
• nine-command scenario CLI for local and CI workflows
• explicit immutable Domain Pack registries and pure Oracle Assertions

Core execution does not require a database, network service, plugin, or property testing framework. See security assumptions and non-goals. 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.

Installation

From a source checkout, use a virtual environment and install the checkout:

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:

/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]'

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]'.

Minimal quickstart

The public cart scenario is an executable DSL 1 document. Run it from the repository root:

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, reproducibility guide, and normative compatibility contract.

Documentation

• Quickstart
• DSL 1 reference
• Determinism model
• Reproducibility and replay
• Testing, faults, and oracle
• Plugins
• SQLAlchemy adapter
• Hypothesis integration
• Schemathesis integration
• Public Python API
• Security assumptions and non-goals
• Compatibility contract
• Phase 2 public contract, CLI, and hard bounds

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.