deterministic-scenario-engine 1.0.0__py3-none-any.whl

scenario_engine/pytest_plugin.py

@@ -0,0 +1,95 @@
+"""Optional pytest integration for deterministic scenario execution."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from scenario_engine.errors import PytestIntegrationError
+
+try:
+    import pytest
+except ModuleNotFoundError as error:
+    if error.name != "pytest":
+        raise
+    raise PytestIntegrationError(
+        "pytest integration requires the optional 'pytest' extra"
+    ) from None
+
+from scenario_engine.dsl import compile_document, evaluate_scenario, parse_yaml, replay_scenario, run_scenario
+from scenario_engine.manifest import ReproducibilityManifest
+from scenario_engine.result import ScenarioResult
+
+
+class ScenarioHarness:
+    """Ergonomic glue over the frozen DSL runtime and exact replay APIs."""
+
+    def run_text(
+        self,
+        yaml_text: str,
+        *,
+        root_seed: str | int,
+        run_index: int = 0,
+        locale: str = "C",
+        inputs=None,
+        plugins=None,
+    ) -> ScenarioResult:
+        scenario = compile_document(parse_yaml(yaml_text))
+        return run_scenario(scenario, root_seed, run_index, locale, inputs, plugins)
+
+    def run_file(
+        self,
+        path: str | Path,
+        *,
+        root_seed: str | int,
+        run_index: int = 0,
+        locale: str = "C",
+        inputs=None,
+        plugins=None,
+    ) -> ScenarioResult:
+        return self.run_text(
+            Path(path).read_text(encoding="utf-8"),
+            root_seed=root_seed,
+            run_index=run_index,
+            locale=locale,
+            inputs=inputs,
+            plugins=plugins,
+        )
+
+    def replay_text(
+        self,
+        yaml_text: str,
+        manifest: ReproducibilityManifest,
+        *,
+        inputs=None,
+        plugins=None,
+    ) -> ScenarioResult:
+        return replay_scenario(yaml_text, manifest, inputs=inputs, plugins=plugins)
+
+    def replay_file(
+        self,
+        path: str | Path,
+        manifest: ReproducibilityManifest,
+        *,
+        inputs=None,
+        plugins=None,
+    ) -> ScenarioResult:
+        return self.replay_text(Path(path).read_text(encoding="utf-8"), manifest, inputs=inputs, plugins=plugins)
+
+    def evaluate_text(self, yaml_text: str, *, root_seed: str | int, run_index: int = 0,
+                      locale: str = "C", inputs=None, raise_on_mismatch: bool = False,
+                      plugins=None):
+        return evaluate_scenario(compile_document(parse_yaml(yaml_text)), root_seed, run_index,
+                                 locale, inputs, raise_on_mismatch, plugins)
+
+    def evaluate_file(self, path: str | Path, *, root_seed: str | int, run_index: int = 0,
+                      locale: str = "C", inputs=None, raise_on_mismatch: bool = False,
+                      plugins=None):
+        return self.evaluate_text(Path(path).read_text(encoding="utf-8"), root_seed=root_seed,
+            run_index=run_index, locale=locale, inputs=inputs,
+            raise_on_mismatch=raise_on_mismatch, plugins=plugins)
+
+
+@pytest.fixture
+def scenario_engine() -> ScenarioHarness:
+    """Provide an isolated deterministic scenario harness."""
+    return ScenarioHarness()

scenario_engine/reference_packs/__init__.py

@@ -0,0 +1 @@
+"""In-repository deterministic reference plugin packs."""

scenario_engine/reference_packs/ecommerce.py

@@ -0,0 +1,57 @@
+"""Small deterministic ecommerce generator reference pack.
+
+The algorithms use only addressed services supplied by
+``PluginGenerationContext`` and explicit arguments.  Version ``"1"`` freezes
+their current behavior.  Importing this module performs no registration.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from scenario_engine.plugins import GeneratorPlugin, PluginGenerationContext, PluginRegistry
+
+
+VERSION = "1"
+
+
+def _text(arguments: Mapping[str, Any], name: str, default: str) -> str:
+    value = arguments.get(name, default)
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{name} must be a non-empty string")
+    return value
+
+
+def customer_email(context: PluginGenerationContext, arguments: Mapping[str, Any]) -> str:
+    prefix = _text(arguments, "prefix", "customer").lower()
+    domain = _text(arguments, "domain", "example.test").lower()
+    token = context.rng.inclusive_int(100000, 999999)
+    return f"{prefix}.{token}@{domain}"
+
+
+def sku(context: PluginGenerationContext, arguments: Mapping[str, Any]) -> str:
+    prefix = _text(arguments, "prefix", "SKU").upper()
+    token = context.rng.inclusive_int(100000, 999999)
+    return f"{prefix}-{token}"
+
+
+def order_number(context: PluginGenerationContext, arguments: Mapping[str, Any]) -> str:
+    prefix = _text(arguments, "prefix", "ORD").upper()
+    token = context.ids.derive(context.address, "order-number").value[-12:].upper()
+    return f"{prefix}-{token}"
+
+
+def tracking_number(context: PluginGenerationContext, arguments: Mapping[str, Any]) -> str:
+    prefix = _text(arguments, "prefix", "SYN").upper()
+    token = context.ids.derive(context.address, "tracking-number").value[-14:].upper()
+    return f"{prefix}-{token}"
+
+
+def ecommerce_registry() -> PluginRegistry:
+    """Return a new immutable registry containing the four version-1 plugins."""
+    return PluginRegistry((
+        GeneratorPlugin("ecommerce.customer_email", VERSION, customer_email),
+        GeneratorPlugin("ecommerce.sku", VERSION, sku),
+        GeneratorPlugin("ecommerce.order_number", VERSION, order_number),
+        GeneratorPlugin("ecommerce.tracking_number", VERSION, tracking_number),
+    ))

scenario_engine/resources.py

@@ -0,0 +1,163 @@
+"""Deterministic external-input and named-resource resolution."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+
+from .errors import ScenarioEngineError
+from .values import canonical_bytes, fingerprint, normalize
+
+
+class ResourceError(ScenarioEngineError, ValueError):
+    pass
+
+
+class ResourceResolutionError(ResourceError):
+    pass
+
+
+class ResourceCycleError(ResourceResolutionError):
+    pass
+
+
+def _copy(value: Any) -> Any:
+    """Copy a validated semantic tree without invoking arbitrary protocols."""
+    normalize(value)
+    if isinstance(value, Mapping):
+        return {key: _copy(value[key]) for key in sorted(value)}
+    if isinstance(value, (list, tuple)):
+        return [_copy(item) for item in value]
+    return value
+
+
+def _freeze(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: _freeze(value[key]) for key in sorted(value)})
+    if isinstance(value, list):
+        return tuple(_freeze(item) for item in value)
+    return value
+
+
+def _path(text: Any, context: str) -> tuple[str, ...]:
+    if not isinstance(text, str) or not text or any(not part for part in text.split(".")):
+        raise ResourceResolutionError(f"{context}: expected non-empty dot-separated path")
+    return tuple(text.split("."))
+
+
+def _lookup(value: Any, parts: tuple[str, ...], context: str) -> Any:
+    current = value
+    for part in parts:
+        if not isinstance(current, Mapping) or part not in current:
+            raise ResourceResolutionError(f"{context}: missing path segment {part}")
+        current = current[part]
+    return current
+
+
+class ResolvedResources:
+    def __init__(self, values: Mapping[str, Any], consumed_inputs: Mapping[str, Any] | None = None):
+        self._values = _freeze(_copy(values))
+        self._consumed = _freeze(_copy(consumed_inputs or {}))
+
+    def lookup(self, path: str) -> Any:
+        parts = _path(path, "resource lookup")
+        if parts[0] not in self._values:
+            raise ResourceResolutionError(f"resource lookup {path}: unknown resource {parts[0]}")
+        return _copy(_lookup(self._values[parts[0]], parts[1:], f"resource lookup {path}"))
+
+    def snapshot(self) -> dict[str, Any]:
+        return _copy(self._values)
+
+    def normalized(self) -> Any:
+        return normalize(self._values)
+
+    def canonical_bytes(self) -> bytes:
+        return canonical_bytes(self._values)
+
+    def hashes(self) -> Mapping[str, str]:
+        hashes = {f"input:{name}": fingerprint(self._consumed[name]) for name in self._consumed}
+        hashes.update({f"resource:{name}": fingerprint(self._values[name]) for name in self._values})
+        return MappingProxyType({key: hashes[key] for key in sorted(hashes)})
+
+    def with_override(self, path: str, value: Any) -> "ResolvedResources":
+        parts = _path(path, "resource override")
+        values = self.snapshot()
+        current = values
+        for part in parts[:-1]:
+            if not isinstance(current, dict) or part not in current:
+                raise ResourceResolutionError(f"resource override {path}: missing path segment {part}")
+            current = current[part]
+        if not isinstance(current, dict) or parts[-1] not in current:
+            raise ResourceResolutionError(f"resource override {path}: missing path segment {parts[-1]}")
+        current[parts[-1]] = _copy(value)
+        return ResolvedResources(values, self._consumed)
+
+
+def _dependencies(node: Any, resource: str) -> set[str]:
+    found: set[str] = set()
+    if isinstance(node, Mapping):
+        if "$ref" in node:
+            if len(node) != 1:
+                raise ResourceResolutionError(f"resource {resource}: $ref node must contain exactly one operator")
+            found.add(_path(node["$ref"], f"resource {resource} $ref")[0])
+        elif "$input" in node:
+            if len(node) != 1:
+                raise ResourceResolutionError(f"resource {resource}: $input node must contain exactly one operator")
+            _path(node["$input"], f"resource {resource} $input")
+        else:
+            for key in sorted(node):
+                found.update(_dependencies(node[key], resource))
+    elif isinstance(node, (list, tuple)):
+        for item in node:
+            found.update(_dependencies(item, resource))
+    return found
+
+
+def resolve_resources(
+    declarations: Mapping[str, Any], inputs: Mapping[str, Any] | None = None,
+) -> ResolvedResources:
+    if inputs is None:
+        inputs = {}
+    if not isinstance(inputs, Mapping) or not all(isinstance(key, str) for key in inputs):
+        raise ResourceResolutionError("inputs must be a string-keyed mapping")
+    copied_inputs = _copy(inputs)
+    names = set(declarations)
+    dependencies = {name: _dependencies(declarations[name], name) for name in sorted(names)}
+    unknown = sorted(dep for deps in dependencies.values() for dep in deps if dep not in names)
+    if unknown:
+        raise ResourceResolutionError("unknown referenced resource(s): " + ", ".join(unknown))
+    remaining = set(names)
+    order: list[str] = []
+    while remaining:
+        ready = sorted(name for name in remaining if not (dependencies[name] & remaining))
+        if not ready:
+            raise ResourceCycleError("resource dependency cycle: " + ", ".join(sorted(remaining)))
+        order.extend(ready)
+        remaining.difference_update(ready)
+    resolved: dict[str, Any] = {}
+    consumed: dict[str, Any] = {}
+
+    def resolve_node(node: Any, owner: str) -> Any:
+        if isinstance(node, Mapping):
+            if "$input" in node:
+                parts = _path(node["$input"], f"resource {owner} $input")
+                if parts[0] not in copied_inputs:
+                    raise ResourceResolutionError(
+                        f"resource {owner}: unknown external input {'.'.join(parts)}"
+                    )
+                consumed[parts[0]] = _copy(copied_inputs[parts[0]])
+                return _copy(_lookup(copied_inputs[parts[0]], parts[1:],
+                                     f"resource {owner} input {'.'.join(parts)}"))
+            if "$ref" in node:
+                parts = _path(node["$ref"], f"resource {owner} $ref")
+                return _copy(_lookup(resolved[parts[0]], parts[1:],
+                                     f"resource {owner} reference {'.'.join(parts)}"))
+            return {key: resolve_node(node[key], owner) for key in sorted(node)}
+        if isinstance(node, (list, tuple)):
+            return [resolve_node(item, owner) for item in node]
+        return _copy(node)
+
+    for name in order:
+        resolved[name] = resolve_node(declarations[name], name)
+    return ResolvedResources(resolved, consumed)

scenario_engine/result.py

@@ -0,0 +1,99 @@
+"""Normalized, byte-stable observable scenario results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+from typing import Any, Mapping
+
+from .manifest import ReproducibilityManifest
+from .runner import ScenarioRunner
+from .values import normalize
+
+
+def _trace(runner: ScenarioRunner) -> list[Mapping[str, Any]]:
+    return [{
+        "address": record.address.canonical(),
+        "artifacts": [[item_id, kind] for item_id, kind in record.emitted_artifacts],
+        "faults_applied": list(record.faults_applied or ()),
+        "patch": record.state_patch,
+        "post": record.post_state_fingerprint,
+        "pre": record.pre_state_fingerprint,
+        "timestamp": record.logical_timestamp,
+        "transition": record.transition_selected,
+    } for record in runner.history.records]
+
+
+@dataclass(frozen=True, slots=True)
+class ScenarioResult:
+    scenario_id: str
+    runner: ScenarioRunner = field(compare=False, repr=False)
+    manifest: ReproducibilityManifest
+    resources: Any = field(default=None, compare=False, repr=False)
+    provenance: Any = field(default=None, compare=False, repr=False)
+    _normalized_snapshot: Mapping[str, Any] = field(init=False, compare=False, repr=False)
+
+    def __post_init__(self) -> None:
+        snapshot = normalize({
+            "artifacts": [{
+                "address": artifact.address.canonical(),
+                "id": artifact.logical_id,
+                "name": artifact.name,
+                "type": artifact.artifact_type,
+                "value": artifact.value,
+            } for artifact in self.runner.artifacts],
+            "clock": self.runner.clock.current,
+            "history": _trace(self.runner),
+            "manifest": self.manifest.normalized(),
+            "next": self.runner.next_step,
+            "scenario_id": self.scenario_id,
+            "state": self.runner.state.to_dict(),
+            "terminal_transition": self.runner.next_step,
+        })
+        if self.provenance is not None and self.provenance.records:
+            snapshot = normalize({**snapshot, "provenance": self.provenance.normalized()})
+        object.__setattr__(self, "_normalized_snapshot", snapshot)
+
+    @property
+    def final_state(self) -> Mapping[str, Any]:
+        return self.runner.state.to_dict()
+
+    @property
+    def history(self) -> Any:
+        return self.runner.history
+
+    @property
+    def resolved_resources(self) -> Any:
+        return self.resources
+
+    @property
+    def artifacts(self) -> tuple[Any, ...]:
+        return tuple(self.runner.artifacts)
+
+    @property
+    def logical_clock(self) -> Any:
+        return self.runner.clock.current
+
+    @property
+    def terminal_transition(self) -> str | None:
+        return self.runner.next_step
+
+    def normalized(self) -> Mapping[str, Any]:
+        return json.loads(json.dumps(self._normalized_snapshot, ensure_ascii=False))
+
+    def to_jsonable(self) -> Mapping[str, Any]:
+        return self.normalized()
+
+    def to_json(self) -> str:
+        return json.dumps(
+            self._normalized_snapshot,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+
+    def to_json_bytes(self) -> bytes:
+        return self.to_json().encode("utf-8")
+
+    def trace(self) -> list[Mapping[str, Any]]:
+        return self.normalized()["history"]

scenario_engine/rng.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import random
+
+from .address import ExecutionAddress
+
+
+RNG_VERSION = "scenario-engine-addressed-v1"
+
+
+class DeterministicRNG:
+    def __init__(self, root_seed: str | int, address: ExecutionAddress):
+        self._root_seed = str(root_seed)
+        self._address = address
+
+    def derivation_material(self, generator_type: str) -> bytes:
+        parts = (RNG_VERSION, self._root_seed, self._address.canonical(), generator_type)
+        return "\x1f".join(parts).encode("utf-8")
+
+    def inclusive_int(self, minimum: int, maximum: int) -> int:
+        if minimum > maximum:
+            raise ValueError("minimum must not exceed maximum")
+        digest = hashlib.sha256(self.derivation_material("inclusive-int")).digest()
+        local = random.Random(int.from_bytes(digest, "big"))
+        return local.randint(minimum, maximum)
+
+
+@dataclass(frozen=True, slots=True)
+class IntegerRange:
+    minimum: int
+    maximum: int
+
+    def generate(self, context: object) -> int:
+        return context.rng().inclusive_int(self.minimum, self.maximum)  # type: ignore[attr-defined]

scenario_engine/runner.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+from types import MappingProxyType
+from typing import Any, Callable, Mapping, Protocol
+
+from .address import ExecutionAddress
+from .artifacts import GeneratedArtifact
+from .clock import LogicalClock
+from .context import GenerationContext
+from .expressions import EvaluationEnvironment, Expression, resolve_derivations
+from .history import HistoryRecord, ScenarioHistory
+from .ids import DeterministicIDProvider
+from .state import ScenarioState
+from .values import fingerprint
+
+
+class Generator(Protocol):
+    def generate(self, context: GenerationContext) -> Any: ...
+
+
+EmissionBuilder = Callable[[GenerationContext, Mapping[str, Any], Mapping[str, Any], Mapping[str, Any]], tuple[GeneratedArtifact, ...]]
+TransitionResolver = Callable[[Mapping[str, Any]], str | None]
+Validator = Callable[[Mapping[str, Any]], None]
+HistoryBuilder = Callable[..., HistoryRecord]
+
+
+@dataclass(frozen=True, slots=True)
+class StepSpec:
+    step_id: str
+    generators: Mapping[str, Generator]
+    derivations: Mapping[str, Expression]
+    state_patch: Mapping[str, Expression]
+    advance: timedelta = timedelta(0)
+    validate: Validator = lambda state: None
+    emit: EmissionBuilder = lambda context, state, locals_, derived: ()
+    transition: TransitionResolver = lambda state: None
+    history_builder: HistoryBuilder = HistoryRecord
+
+
+@dataclass(frozen=True, slots=True)
+class CandidateStep:
+    post_state: Mapping[str, Any]
+    artifacts: tuple[GeneratedArtifact, ...]
+    timestamp: Any
+    transition: str | None
+    history_record: HistoryRecord
+
+
+class ScenarioRunner:
+    def __init__(self, root_seed: str | int, address: ExecutionAddress,
+                 state: ScenarioState, clock: LogicalClock):
+        self.root_seed = root_seed
+        self.address = address
+        self.state = state
+        self.clock = clock
+        self.history = ScenarioHistory()
+        self.artifacts: list[GeneratedArtifact] = []
+        self.next_step: str | None = None
+        self._ids = DeterministicIDProvider(root_seed)
+
+    def run_step(self, spec: StepSpec, candidate_validator=None) -> CandidateStep:
+        step_address = self.address.for_step(spec.step_id)
+        context = GenerationContext(self.root_seed, step_address, self.clock, self._ids)
+        pre_state = self.state.snapshot()
+        pre_fingerprint = self.state.fingerprint()
+
+        locals_: dict[str, Any] = {}
+        for name in sorted(spec.generators):
+            field_context = context.at(step_address.child("generate", name))
+            locals_[name] = spec.generators[name].generate(field_context)
+
+        base_env = EvaluationEnvironment(pre_state, MappingProxyType(locals_), MappingProxyType({}))
+        derived = resolve_derivations(spec.derivations, base_env)
+        resolved_env = EvaluationEnvironment(pre_state, MappingProxyType(locals_), MappingProxyType(derived))
+        patch = {name: spec.state_patch[name].evaluate(resolved_env) for name in sorted(spec.state_patch)}
+        post_state = self.state.candidate(patch)
+        safe_post_state = MappingProxyType(post_state)
+        spec.validate(safe_post_state)
+        timestamp = self.clock.prospective(spec.advance)
+        artifacts = tuple(spec.emit(context, safe_post_state, MappingProxyType(locals_), MappingProxyType(derived)))
+        transition = spec.transition(safe_post_state)
+        record = spec.history_builder(
+            address=step_address,
+            logical_timestamp=timestamp,
+            pre_state_fingerprint=pre_fingerprint,
+            state_patch=MappingProxyType(patch),
+            post_state_fingerprint=fingerprint(post_state),
+            emitted_artifacts=tuple((item.logical_id, item.artifact_type) for item in artifacts),
+            transition_selected=transition,
+            faults_applied=None,
+        )
+        candidate = CandidateStep(safe_post_state, artifacts, timestamp, transition, record)
+        if candidate_validator is not None:
+            candidate_validator(candidate, step_address)
+
+        self.state.commit(post_state)
+        self.history.append_committed(record)
+        self.artifacts.extend(artifacts)
+        self.clock.commit(timestamp)
+        self.next_step = transition
+        return candidate

scenario_engine/state.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from .values import fingerprint
+
+
+def _freeze(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: _freeze(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return tuple(_freeze(item) for item in value)
+    if isinstance(value, tuple):
+        return tuple(_freeze(item) for item in value)
+    return value
+
+
+class ScenarioState:
+    def __init__(self, initial: Mapping[str, Any] | None = None):
+        self._value = deepcopy(dict(initial or {}))
+
+    def snapshot(self) -> Mapping[str, Any]:
+        return _freeze(deepcopy(self._value))
+
+    def candidate(self, patch: Mapping[str, Any]) -> dict[str, Any]:
+        result = deepcopy(self._value)
+        result.update(deepcopy(dict(patch)))
+        return result
+
+    def commit(self, candidate: Mapping[str, Any]) -> None:
+        self._value = deepcopy(dict(candidate))
+
+    def to_dict(self) -> dict[str, Any]:
+        return deepcopy(self._value)
+
+    def fingerprint(self) -> str:
+        return fingerprint(self._value)