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

scenario_engine/dsl/runtime.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+from types import MappingProxyType
+
+from scenario_engine.address import ExecutionAddress
+from scenario_engine.canonical import canonical_scenario_hash
+from scenario_engine.clock import LogicalClock
+from scenario_engine.ids import ID_VERSION
+from scenario_engine.manifest import ENGINE_VERSION, GENERATOR_VERSIONS, ReplayCompatibilityError, ReproducibilityManifest
+from scenario_engine.result import ScenarioResult
+from scenario_engine.rng import RNG_VERSION
+from scenario_engine.resources import resolve_resources
+from scenario_engine.runner import ScenarioRunner
+from scenario_engine.state import ScenarioState
+from scenario_engine.provenance import ProvenanceRecord, ScenarioProvenance
+from scenario_engine.invariants import InvariantViolation, evaluate_invariants
+from scenario_engine.faults import apply_step_faults
+from scenario_engine.oracle import OracleEvaluation, OracleMismatchError, OracleReport
+from scenario_engine.validation import ConstraintDefinitionError, ConstraintViolation, ResourceValidationError, validate_resources
+from scenario_engine.expressions import EvaluationEnvironment
+from scenario_engine.plugins import (
+    EMPTY_PLUGIN_REGISTRY, PluginCompatibilityError, PluginNotFoundError,
+    PluginRegistry, PluginVersionMismatchError,
+)
+
+from .compiler import compile_constraint, compile_document, compile_expression, compile_scoped_sequence
+from .models import CompiledScenario
+from .parser import parse_yaml
+
+
+def _plugin_requirements(document):
+    requirements = {}
+    sequences = (document.steps, *document.subflows.values())
+    for sequence in sequences:
+        for step in sequence:
+            for declaration in step.generate.values():
+                if "$plugin" not in declaration:
+                    continue
+                body = declaration["$plugin"]
+                prior = requirements.get(body["name"])
+                if prior is not None and prior != body["version"]:
+                    raise PluginCompatibilityError(
+                        f"scenario declares conflicting versions for plugin {body['name']}"
+                    )
+                requirements[body["name"]] = body["version"]
+    return MappingProxyType({name: requirements[name] for name in sorted(requirements)})
+
+
+def _registry(plugins):
+    if plugins is None:
+        return EMPTY_PLUGIN_REGISTRY
+    if not isinstance(plugins, PluginRegistry):
+        raise TypeError("plugins must be a PluginRegistry or None")
+    return plugins
+
+
+def _prevalidate_plugins(document, plugins):
+    requirements = _plugin_requirements(document)
+    for name, version in requirements.items():
+        try:
+            plugins.require(name, version)
+        except (PluginNotFoundError, PluginVersionMismatchError) as error:
+            raise PluginCompatibilityError(str(error)) from error
+    return requirements
+
+
+def _generator_versions(document):
+    return MappingProxyType({**dict(GENERATOR_VERSIONS), **{
+        f"plugin:{name}": version for name, version in _plugin_requirements(document).items()
+    }})
+
+
+def _manifest(scenario, root_seed, run_index, locale, base_resources):
+    return ReproducibilityManifest(root_seed=root_seed, scenario_canonical_hash=canonical_scenario_hash(scenario),
+        engine_version=ENGINE_VERSION, dsl_version=scenario.document.dsl_version,
+        generator_versions=_generator_versions(scenario.document), rng_algorithm_version=RNG_VERSION,
+        id_algorithm_version=ID_VERSION, locale=locale,
+        reference_clock_start=scenario.reference_clock_start, run_index=run_index,
+        input_resource_hashes=base_resources.hashes())
+
+
+def _prepare(scenario, inputs, provenance):
+    if scenario.resources is not None:
+        if inputs is not None: raise ValueError("inputs must be supplied before compilation or to an unresolved scenario")
+        base = scenario.resources
+    else:
+        base = resolve_resources(scenario.document.resources, inputs)
+    resources = base
+    applied=[]
+    for fault in scenario.document.faults:
+        if not fault["enabled"] or fault["at"] != "before_validation": continue
+        body=fault["operator"]["override_resource"]
+        value=compile_expression(body["value"],resources).evaluate(EvaluationEnvironment({}, {}, {}))
+        resources=resources.with_override(body["path"],value); applied.append(fault)
+        provenance.append(ProvenanceRecord("fault_application",fault["id"],hook="before_validation",target=body["path"],details=MappingProxyType({"operator":"override_resource"})))
+    validate_resources(resources,scenario.document.validators)
+    for item in scenario.document.constraints:
+        result=compile_constraint(item["check"],resources).evaluate(EvaluationEnvironment({}, {}, {}))
+        if type(result) is not bool: raise ConstraintDefinitionError(f"constraint {item['id']}: check must return boolean")
+        if not result:
+            provenance.append(ProvenanceRecord("constraint_violation",item["id"],outcome="violation"))
+            error=ConstraintViolation(f"constraint {item['id']} violated" + (f": {item['message']}" if item.get("message") else ""))
+            error.constraint_id=item["id"]; error.applied_faults=tuple(applied); error.provenance=ScenarioProvenance(tuple(provenance)); error.base_resources=base; error.resources=resources
+            raise error
+    return scenario,base,resources,applied
+
+
+def _execute(scenario, root_seed, run_index, locale, inputs, plugins=None):
+    if isinstance(run_index,bool) or not isinstance(run_index,int) or run_index<0: raise ValueError("run_index must be a nonnegative integer")
+    records=[]; plugins=_registry(plugins); _prevalidate_plugins(scenario.document,plugins)
+    try:
+        scenario,base,resources,applied=_prepare(scenario,inputs,records)
+    except ConstraintViolation as error:
+        unresolved=scenario
+        base=error.base_resources
+        error.manifest=_manifest(unresolved,root_seed,run_index,locale,base)
+        raise
+    runner=ScenarioRunner(root_seed,ExecutionAddress(scenario.scenario_id,run_index),ScenarioState(scenario.initial_state),LogicalClock(scenario.reference_clock_start))
+    scenario=compile_document(scenario.document,resources,plugins,runner.state)
+    manifest=_manifest(scenario,root_seed,run_index,locale,base)
+    invariants=tuple((item["id"],compile_expression(item["check"],resources)) for item in scenario.document.invariants)
+
+    def execute_invocation(control_id,target,bindings,scope,repetitions,path):
+        from scenario_engine.control_flow import evaluate_bindings, invocation_component
+        child_scope=evaluate_bindings(bindings,compile_expression,runner.state.snapshot(),resources,scope)
+        old=runner.address; runner.address=runner.address.with_subflow_invocation(invocation_component(control_id,target))
+        for index in repetitions: runner.address=runner.address.with_repetition(index)
+        try: execute_sequence(compile_scoped_sequence(scenario.document.subflows[target],resources,child_scope,plugins,runner.state),child_scope,path+(control_id,))
+        finally: runner.address=old
+
+    def execute_sequence(steps,scope=None,path=()):
+        from scenario_engine.control_flow import BranchConditionError,evaluate_bindings,invocation_component,validate_repeat_count
+        for node in steps:
+            if hasattr(node,"spec"):
+                spec,faults=apply_step_faults(node.spec,scenario.document.faults,runner.address,runner.state.snapshot(),resources,scope,path)
+                for fault in faults:
+                    op=next(iter(fault["operator"])); target=spec.step_id
+                    records.append(ProvenanceRecord("fault_application",fault["id"],runner.address.for_step(spec.step_id).canonical(),spec.step_id,"before_step",target,details=MappingProxyType({"operator":op})))
+                    applied.append(fault)
+                def validator(candidate,address):
+                    evaluate_invariants(invariants,candidate.post_state,spec.step_id,address,
+                        lambda iid,outcome,addr,sid: records.append(ProvenanceRecord("invariant_check",iid,addr.canonical(),sid,outcome=outcome)))
+                try: runner.run_step(spec,validator if invariants else None)
+                except InvariantViolation as error:
+                    applied.extend(fault for fault in faults if fault not in applied)
+                    records.append(ProvenanceRecord("invariant_violation",error.invariant_id,error.execution_address,error.step_id,outcome="violation"))
+                    error.runner=runner; error.applied_faults=tuple(applied); error.provenance=ScenarioProvenance(tuple(records)); error.manifest=manifest; error.resources=resources
+                    raise
+                continue
+            state=runner.state.snapshot()
+            if node.call is not None: execute_invocation(node.step_id,node.call["subflow"],node.call["with"],scope,(),path)
+            elif node.branch is not None:
+                selected=None; env=EvaluationEnvironment(state,{}, {},scope)
+                for case in node.branch["cases"]:
+                    condition=compile_expression(case["when"],resources).evaluate(env)
+                    if type(condition) is not bool: raise BranchConditionError("branch condition must evaluate to boolean")
+                    if condition: selected=case; break
+                if selected is None: selected=node.branch.get("else")
+                if selected is not None: execute_invocation(node.step_id,selected["subflow"],selected["with"],scope,(),path)
+            else:
+                repeat=node.repeat; env=EvaluationEnvironment(state,{}, {},scope)
+                count=validate_repeat_count(compile_expression(repeat["count"],resources).evaluate(env),repeat["max"])
+                for index in range(count):
+                    bindings=dict(repeat["with"]); child=evaluate_bindings(bindings,compile_expression,runner.state.snapshot(),resources,scope)
+                    if "index_as" in repeat: child=MappingProxyType({**dict(child),repeat["index_as"]:index})
+                    old=runner.address; runner.address=runner.address.with_subflow_invocation(invocation_component(node.step_id,repeat["subflow"])).with_repetition(index)
+                    try: execute_sequence(compile_scoped_sequence(scenario.document.subflows[repeat["subflow"]],resources,child,plugins,runner.state),child,path+(node.step_id,))
+                    finally: runner.address=old
+    execute_sequence(scenario.steps)
+    provenance=ScenarioProvenance(tuple(records))
+    return ScenarioResult(scenario.scenario_id,runner,manifest,resources,provenance),tuple(applied),provenance
+
+
+def run_scenario(scenario: CompiledScenario,root_seed,run_index=0,locale="C",inputs=None,plugins=None):
+    return _execute(scenario,root_seed,run_index,locale,inputs,plugins)[0]
+
+
+def evaluate_scenario(scenario: CompiledScenario,root_seed,run_index=0,locale="C",inputs=None,raise_on_mismatch=False,plugins=None):
+    result=None; observed_c=(); observed_i=(); applied=(); provenance=ScenarioProvenance()
+    try: result,applied,provenance=_execute(scenario,root_seed,run_index,locale,inputs,plugins); manifest=result.manifest
+    except ConstraintViolation as error:
+        observed_c=(error.constraint_id,); applied=error.applied_faults; provenance=error.provenance; manifest=error.manifest
+    except InvariantViolation as error:
+        observed_i=(error.invariant_id,); applied=error.applied_faults; provenance=error.provenance; manifest=error.manifest
+    oracle=scenario.document.oracle or {"expected":{"constraints":(),"invariants":()},"strict_unexpected":True}
+    expected_c=list(oracle["expected"]["constraints"]); expected_i=list(oracle["expected"]["invariants"])
+    for fault in applied:
+        for value in fault["expect"]["constraints"]:
+            if value not in expected_c: expected_c.append(value)
+        for value in fault["expect"]["invariants"]:
+            if value not in expected_i: expected_i.append(value)
+    unexpected=tuple([f"constraint:{x}" for x in observed_c if x not in expected_c]+[f"invariant:{x}" for x in observed_i if x not in expected_i])
+    missing=tuple([f"constraint:{x}" for x in expected_c if x not in observed_c]+[f"invariant:{x}" for x in expected_i if x not in observed_i])
+    strict=oracle["strict_unexpected"] or any(f["strict_unexpected"] for f in applied)
+    report=OracleReport(observed_c,observed_i,tuple(expected_c),tuple(expected_i),unexpected,missing,tuple(f["id"] for f in applied),strict,not missing and (not strict or not unexpected))
+    provenance=ScenarioProvenance(provenance.records+(ProvenanceRecord("oracle_evaluation","oracle",outcome="passed" if report.passed else "failed"),))
+    evaluation=OracleEvaluation(manifest,result,report,provenance)
+    if raise_on_mismatch and not report.passed: raise OracleMismatchError(evaluation)
+    return evaluation
+
+
+def replay_scenario(yaml_text,manifest,*,inputs=None,plugins=None):
+    document=parse_yaml(yaml_text); scenario=compile_document(document)
+    base=resolve_resources(document.resources,inputs)
+    registry=_registry(plugins); _prevalidate_plugins(document,registry)
+    expected={"scenario_canonical_hash":canonical_scenario_hash(scenario),"engine_version":ENGINE_VERSION,"dsl_version":document.dsl_version,
+        "rng_algorithm_version":RNG_VERSION,"id_algorithm_version":ID_VERSION,"generator_versions":_generator_versions(document),"reference_clock_start":document.reference_clock_start}
+    for field,current in expected.items():
+        if getattr(manifest,field)!=current: raise ReplayCompatibilityError(f"{field} mismatch")
+    if manifest.input_resource_hashes!=base.hashes(): raise ReplayCompatibilityError("input_resource_hashes mismatch")
+    if manifest.domain_pack_versions: raise ReplayCompatibilityError("domain_pack_versions unsupported in Phase 0.2A")
+    return run_scenario(scenario,manifest.root_seed,manifest.run_index,locale=manifest.locale,inputs=inputs,plugins=registry)

scenario_engine/errors.py

@@ -0,0 +1,13 @@
+"""Stable public exception root for Scenario Engine-owned failures."""
+
+
+class ScenarioEngineError(Exception):
+    """Root of all intended user-facing Scenario Engine exceptions."""
+
+
+class OptionalDependencyError(ScenarioEngineError, ImportError):
+    """An explicitly imported optional integration is not installed."""
+
+
+class PytestIntegrationError(OptionalDependencyError):
+    """The optional pytest integration cannot be loaded."""

scenario_engine/expressions.py

@@ -0,0 +1,330 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Context, Decimal, DecimalException, ROUND_HALF_EVEN, localcontext
+from typing import Any, Mapping
+
+from .errors import ScenarioEngineError
+from .values import canonical_bytes
+
+
+def _mutable(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {key: _mutable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_mutable(item) for item in value]
+    return value
+
+
+class ExpressionEvaluationError(ScenarioEngineError, ValueError):
+    pass
+
+
+# DSL 1.0 decimal arithmetic is independent of decimal.getcontext().  Precision
+# 28 and ROUND_HALF_EVEN preserve the engine's prior default-context behavior.
+_ARITHMETIC_CONTEXT = Context(prec=28, rounding=ROUND_HALF_EVEN)
+
+
+def _operand_error(operator: str, left: Any, right: Any) -> ExpressionEvaluationError:
+    return ExpressionEvaluationError(
+        f"incompatible operands for {operator}: {type(left).__name__}, {type(right).__name__}"
+    )
+
+
+def _numeric_pair(operator: str, left: Any, right: Any) -> tuple[int | Decimal, int | Decimal]:
+    if not _numeric(left) or not _numeric(right):
+        raise _operand_error(operator, left, right)
+    return left, right
+
+
+def _decimal_binary(operator: str, left: int | Decimal, right: int | Decimal) -> Decimal:
+    try:
+        with localcontext(_ARITHMETIC_CONTEXT):
+            left_decimal, right_decimal = Decimal(left), Decimal(right)
+            if operator == "$add":
+                return left_decimal + right_decimal
+            if operator == "$sub":
+                return left_decimal - right_decimal
+            if operator == "$mul":
+                return left_decimal * right_decimal
+            return left_decimal / right_decimal
+    except DecimalException as error:
+        raise ExpressionEvaluationError(f"{operator} decimal arithmetic failed") from error
+
+
+class ScopeResolutionError(ExpressionEvaluationError):
+    """A scoped expression could not be resolved in the active invocation."""
+
+
+def resolve_semantic_path(value: Mapping[str, Any] | None, path: str) -> Any:
+    if value is None:
+        raise ScopeResolutionError("$scope is unavailable outside a subflow invocation")
+    current: Any = value
+    for segment in path.split("."):
+        if not segment or not isinstance(current, Mapping) or segment not in current:
+            raise ScopeResolutionError(f"unknown $scope path {path}")
+        current = current[segment]
+    return current
+
+
+@dataclass(frozen=True, slots=True)
+class EvaluationEnvironment:
+    pre_state: Mapping[str, Any]
+    locals: Mapping[str, Any]
+    derived: Mapping[str, Any]
+    scope: Mapping[str, Any] | None = None
+
+
+class Expression:
+    def evaluate(self, env: EvaluationEnvironment) -> Any:
+        raise NotImplementedError
+
+    def dependencies(self) -> frozenset[str]:
+        return frozenset()
+
+
+@dataclass(frozen=True, slots=True)
+class Literal(Expression):
+    value: Any
+    def evaluate(self, env: EvaluationEnvironment) -> Any:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class StateRef(Expression):
+    name: str
+    def evaluate(self, env: EvaluationEnvironment) -> Any:
+        try:
+            return env.pre_state[self.name]
+        except KeyError:
+            raise ScopeResolutionError(
+                f"unknown semantic reference: namespace=state name={self.name}"
+            ) from None
+
+
+@dataclass(frozen=True, slots=True)
+class ScopeRef(Expression):
+    path: str
+    def evaluate(self, env: EvaluationEnvironment) -> Any:
+        return resolve_semantic_path(env.scope, self.path)
+
+
+@dataclass(frozen=True, slots=True)
+class LocalRef(Expression):
+    name: str
+    def evaluate(self, env: EvaluationEnvironment) -> Any:
+        try:
+            return env.locals[self.name]
+        except KeyError:
+            raise ScopeResolutionError(
+                f"unknown semantic reference: namespace=local name={self.name}"
+            ) from None
+
+
+@dataclass(frozen=True, slots=True)
+class DerivedRef(Expression):
+    name: str
+    def evaluate(self, env: EvaluationEnvironment) -> Any:
+        try:
+            return env.derived[self.name]
+        except KeyError:
+            raise ScopeResolutionError(
+                f"unknown semantic reference: namespace=derived name={self.name}"
+            ) from None
+    def dependencies(self) -> frozenset[str]:
+        return frozenset((self.name,))
+
+
+@dataclass(frozen=True, slots=True)
+class Binary(Expression):
+    left: Expression
+    right: Expression
+    def dependencies(self) -> frozenset[str]:
+        return self.left.dependencies() | self.right.dependencies()
+
+
+class Add(Binary):
+    def evaluate(self, env: EvaluationEnvironment) -> Any:
+        left, right = self.left.evaluate(env), self.right.evaluate(env)
+        _numeric_pair("$add", left, right)
+        if isinstance(left, Decimal) or isinstance(right, Decimal):
+            return _decimal_binary("$add", left, right)
+        return left + right
+
+
+class Multiply(Binary):
+    def evaluate(self, env: EvaluationEnvironment) -> Any:
+        left, right = self.left.evaluate(env), self.right.evaluate(env)
+        _numeric_pair("$mul", left, right)
+        if isinstance(left, Decimal) or isinstance(right, Decimal):
+            return _decimal_binary("$mul", left, right)
+        return left * right
+
+
+def _numeric(value: Any) -> bool:
+    return not isinstance(value, bool) and isinstance(value, (int, Decimal))
+
+
+class Subtract(Binary):
+    def evaluate(self, env: EvaluationEnvironment) -> Any:
+        left, right = self.left.evaluate(env), self.right.evaluate(env)
+        _numeric_pair("$sub", left, right)
+        if isinstance(left, Decimal) or isinstance(right, Decimal):
+            return _decimal_binary("$sub", left, right)
+        return left - right
+
+
+class Divide(Binary):
+    def evaluate(self, env: EvaluationEnvironment) -> Decimal:
+        left, right = self.left.evaluate(env), self.right.evaluate(env)
+        _numeric_pair("$div", left, right)
+        if right == 0:
+            raise ExpressionEvaluationError("$div division by zero")
+        return _decimal_binary("$div", left, right)
+
+
+class Equal(Binary):
+    def evaluate(self, env: EvaluationEnvironment) -> bool:
+        return canonical_bytes(self.left.evaluate(env)) == canonical_bytes(self.right.evaluate(env))
+
+
+class NotEqual(Equal):
+    def evaluate(self, env: EvaluationEnvironment) -> bool:
+        return not super().evaluate(env)
+
+
+def _ordered(left: Any, right: Any) -> tuple[Any, Any]:
+    from datetime import datetime
+    if _numeric(left) and _numeric(right):
+        return (Decimal(left), Decimal(right))
+    if isinstance(left, str) and isinstance(right, str):
+        return left, right
+    if isinstance(left, datetime) and isinstance(right, datetime):
+        if left.tzinfo is None or right.tzinfo is None:
+            raise ExpressionEvaluationError("ordering datetimes must be timezone-aware")
+        return left, right
+    raise ExpressionEvaluationError("ordering operands have incompatible semantic types")
+
+
+class LessThan(Binary):
+    def evaluate(self, env: EvaluationEnvironment) -> bool:
+        return _ordered(self.left.evaluate(env), self.right.evaluate(env))[0] < _ordered(self.left.evaluate(env), self.right.evaluate(env))[1]
+
+
+class LessThanOrEqual(Binary):
+    def evaluate(self, env: EvaluationEnvironment) -> bool:
+        left, right = _ordered(self.left.evaluate(env), self.right.evaluate(env)); return left <= right
+
+
+class GreaterThan(Binary):
+    def evaluate(self, env: EvaluationEnvironment) -> bool:
+        left, right = _ordered(self.left.evaluate(env), self.right.evaluate(env)); return left > right
+
+
+class GreaterThanOrEqual(Binary):
+    def evaluate(self, env: EvaluationEnvironment) -> bool:
+        left, right = _ordered(self.left.evaluate(env), self.right.evaluate(env)); return left >= right
+
+
+@dataclass(frozen=True, slots=True)
+class BooleanMany(Expression):
+    operands: tuple[Expression, ...]
+    use_and: bool
+    def evaluate(self, env: EvaluationEnvironment) -> bool:
+        result = True if self.use_and else False
+        for operand in self.operands:
+            value = operand.evaluate(env)
+            if type(value) is not bool:
+                raise ExpressionEvaluationError("boolean operator operands must be boolean")
+            result = result and value if self.use_and else result or value
+        return result
+    def dependencies(self) -> frozenset[str]:
+        return frozenset().union(*(operand.dependencies() for operand in self.operands))
+
+
+@dataclass(frozen=True, slots=True)
+class BooleanNot(Expression):
+    operand: Expression
+    def evaluate(self, env: EvaluationEnvironment) -> bool:
+        value = self.operand.evaluate(env)
+        if type(value) is not bool:
+            raise ExpressionEvaluationError("$not operand must be boolean")
+        return not value
+    def dependencies(self) -> frozenset[str]:
+        return self.operand.dependencies()
+
+
+@dataclass(frozen=True, slots=True)
+class Length(Expression):
+    operand: Expression
+    def evaluate(self, env: EvaluationEnvironment) -> int:
+        value = self.operand.evaluate(env)
+        if not isinstance(value, (str, list, tuple, Mapping)):
+            raise ExpressionEvaluationError("$len operand must be string, list, or map")
+        return len(value)
+    def dependencies(self) -> frozenset[str]:
+        return self.operand.dependencies()
+
+
+@dataclass(frozen=True, slots=True)
+class Append(Expression):
+    sequence: Expression
+    item: Expression
+    def evaluate(self, env: EvaluationEnvironment) -> list[Any]:
+        return _mutable(self.sequence.evaluate(env)) + [_mutable(self.item.evaluate(env))]
+    def dependencies(self) -> frozenset[str]:
+        return self.sequence.dependencies() | self.item.dependencies()
+
+
+@dataclass(frozen=True, slots=True)
+class Record(Expression):
+    fields: Mapping[str, Expression]
+    def evaluate(self, env: EvaluationEnvironment) -> dict[str, Any]:
+        return {key: self.fields[key].evaluate(env) for key in sorted(self.fields)}
+    def dependencies(self) -> frozenset[str]:
+        return frozenset().union(*(expr.dependencies() for expr in self.fields.values()))
+
+
+@dataclass(frozen=True, slots=True)
+class SumField(Expression):
+    sequence: Expression
+    field: str
+    def evaluate(self, env: EvaluationEnvironment) -> Any:
+        values = self.sequence.evaluate(env)
+        result: int | Decimal = 0
+        for item in values:
+            value = item[self.field]
+            _numeric_pair("$sum_field", result, value)
+            if isinstance(result, Decimal) or isinstance(value, Decimal):
+                result = _decimal_binary("$add", result, value)
+            else:
+                result += value
+        return result
+    def dependencies(self) -> frozenset[str]:
+        return self.sequence.dependencies()
+
+
+class DerivationCycleError(ExpressionEvaluationError):
+    pass
+
+
+def resolve_derivations(expressions: Mapping[str, Expression], env: EvaluationEnvironment) -> dict[str, Any]:
+    names = set(expressions)
+    dependencies = {name: set(expr.dependencies()) for name, expr in expressions.items()}
+    unknown = sorted({dep for deps in dependencies.values() for dep in deps if dep not in names})
+    if unknown:
+        raise ScopeResolutionError(
+            "unknown semantic references: namespace=derived names=" + ",".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 DerivationCycleError("derived dependency cycle: " + ", ".join(sorted(remaining)))
+        order.extend(ready)
+        remaining.difference_update(ready)
+    result: dict[str, Any] = {}
+    for name in order:
+        result[name] = expressions[name].evaluate(EvaluationEnvironment(env.pre_state, env.locals, result))
+    return result

scenario_engine/faults.py

@@ -0,0 +1,36 @@
+"""Declarative deterministic Phase 0.5 fault operators."""
+from dataclasses import replace
+from types import MappingProxyType
+from .dsl.compiler import LiteralGenerator, compile_expression
+from .errors import ScenarioEngineError
+
+class FaultError(ScenarioEngineError, ValueError): pass
+class FaultDefinitionError(FaultError): pass
+class FaultApplicationError(FaultError): pass
+
+def matches(fault, address, step_id, subflow_path=()):
+    selector = fault.get("selector", {})
+    return (selector.get("step") == step_id
+        and ("subflow_path" not in selector or tuple(selector["subflow_path"]) == tuple(subflow_path))
+        and ("repetition_indexes" not in selector or tuple(selector["repetition_indexes"]) == tuple(address.repetition_indexes)))
+
+def apply_step_faults(spec, faults, address, state, resources, scope, subflow_path=()):
+    applied = []
+    for fault in faults:
+        if not fault["enabled"] or fault["at"] != "before_step" or not matches(fault, address, spec.step_id, subflow_path): continue
+        name, body = next(iter(fault["operator"].items()))
+        if name == "override_write":
+            patch = dict(spec.state_patch); patch[body["path"]] = compile_expression(body["value"], resources, scope)
+            spec = replace(spec, state_patch=MappingProxyType(patch))
+        elif name == "override_local":
+            value = compile_expression(body["value"], resources, scope).evaluate(__import__('scenario_engine.expressions', fromlist=['EvaluationEnvironment']).EvaluationEnvironment(state, {}, {}, scope))
+            generators = dict(spec.generators); generators[body["name"]] = LiteralGenerator(value)
+            spec = replace(spec, generators=MappingProxyType(generators))
+        elif name == "suppress_emissions":
+            spec = replace(spec, emit=lambda context, post, locals_, derived: ())
+        applied.append(fault)
+    if applied:
+        original = spec.history_builder
+        ids = tuple(f["id"] for f in applied)
+        spec = replace(spec, history_builder=lambda **kw: original(**{**kw, "faults_applied": ids}))
+    return spec, tuple(applied)

scenario_engine/history.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from .address import ExecutionAddress
+from .ids import LogicalID
+
+
+@dataclass(frozen=True, slots=True)
+class HistoryRecord:
+    address: ExecutionAddress
+    logical_timestamp: datetime
+    pre_state_fingerprint: str
+    state_patch: Mapping[str, Any]
+    post_state_fingerprint: str
+    emitted_artifacts: tuple[tuple[LogicalID, str], ...]
+    transition_selected: str | None
+    faults_applied: tuple[str, ...] | None = None
+
+
+class ScenarioHistory:
+    def __init__(self) -> None:
+        self._records: list[HistoryRecord] = []
+
+    @property
+    def records(self) -> tuple[HistoryRecord, ...]:
+        return tuple(self._records)
+
+    def append_committed(self, record: HistoryRecord) -> None:
+        frozen = MappingProxyType(dict(record.state_patch))
+        self._records.append(HistoryRecord(
+            record.address, record.logical_timestamp, record.pre_state_fingerprint,
+            frozen, record.post_state_fingerprint, record.emitted_artifacts,
+            record.transition_selected, record.faults_applied,
+        ))

scenario_engine/ids.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import uuid
+
+from .address import ExecutionAddress
+
+
+ID_VERSION = "scenario-engine-id-v1"
+
+
+@dataclass(frozen=True, slots=True)
+class LogicalID:
+    value: str
+
+    def __post_init__(self) -> None:
+        canonical = str(uuid.UUID(self.value))
+        object.__setattr__(self, "value", canonical)
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class DeterministicIDProvider:
+    def __init__(self, root_seed: str | int):
+        self._root_seed = str(root_seed)
+
+    def derivation_material(self, address: ExecutionAddress, slot: str) -> bytes:
+        return "\x1f".join((ID_VERSION, self._root_seed, address.canonical(), slot)).encode()
+
+    def derive(self, address: ExecutionAddress, slot: str) -> LogicalID:
+        raw = bytearray(hashlib.sha256(self.derivation_material(address, slot)).digest()[:16])
+        raw[6] = (raw[6] & 0x0F) | 0x50
+        raw[8] = (raw[8] & 0x3F) | 0x80
+        return LogicalID(str(uuid.UUID(bytes=bytes(raw))))

scenario_engine/integrations/__init__.py

@@ -0,0 +1,7 @@
+"""Explicit optional test-framework integrations.
+
+Concrete adapters are deliberately not imported here, so importing this
+package never requires an optional dependency.
+"""
+
+__all__: tuple[str, ...] = ()