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

scenario_engine/adapters/sqlalchemy.py

@@ -0,0 +1,207 @@
+"""Narrow, insert-only SQLAlchemy Core materialization adapter."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from decimal import Decimal
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from scenario_engine.errors import ScenarioEngineError
+
+try:
+    from sqlalchemy import Table
+    from sqlalchemy.engine import Engine
+except ImportError as exc:  # pragma: no cover - exercised in an isolated process
+    raise ImportError(
+        "scenario_engine.adapters.sqlalchemy requires the optional "
+        "'SQLAlchemy>=2.0,<3' dependency"
+    ) from exc
+
+from scenario_engine.ids import LogicalID
+from scenario_engine.result import ScenarioResult
+from scenario_engine.values import MISSING, fingerprint
+
+
+class SqlAlchemyMaterializerError(ScenarioEngineError, ValueError):
+    """Base class for deterministic adapter errors."""
+
+
+class InvalidRowArtifactError(SqlAlchemyMaterializerError):
+    pass
+
+
+class UnknownTableBindingError(SqlAlchemyMaterializerError):
+    pass
+
+
+class InvalidTableBindingError(SqlAlchemyMaterializerError):
+    pass
+
+
+class InvalidColumnBindingError(SqlAlchemyMaterializerError):
+    pass
+
+
+class MissingPrimaryKeyError(SqlAlchemyMaterializerError):
+    pass
+
+
+class UnsupportedMaterializedValueError(SqlAlchemyMaterializerError):
+    pass
+
+
+class MaterializationExecutionError(SqlAlchemyMaterializerError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class SqlAlchemyRowCommand:
+    artifact_index: int
+    table_name: str
+    values: Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class MaterializationReport:
+    commands_attempted: int
+    rows_inserted: int
+    per_table_counts: Mapping[str, int]
+    command_fingerprint: str
+
+
+def _freeze_values(values: Mapping[str, Any]) -> Mapping[str, Any]:
+    return MappingProxyType(dict(values))
+
+
+def extract_row_commands(result: ScenarioResult) -> tuple[SqlAlchemyRowCommand, ...]:
+    """Extract validated-shape row commands in committed artifact order."""
+    if not isinstance(result, ScenarioResult):
+        raise TypeError("result must be a ScenarioResult")
+    commands = []
+    for artifact_index, artifact in enumerate(result.artifacts):
+        if artifact.artifact_type != "sqlalchemy_row":
+            continue
+        payload = artifact.value
+        if not isinstance(payload, Mapping) or set(payload) != {"table", "values"}:
+            raise InvalidRowArtifactError(
+                f"sqlalchemy_row artifact {artifact_index} payload must contain exactly table and values"
+            )
+        table_name, values = payload["table"], payload["values"]
+        if not isinstance(table_name, str) or not table_name:
+            raise InvalidRowArtifactError(
+                f"sqlalchemy_row artifact {artifact_index} table must be a non-empty string"
+            )
+        if not isinstance(values, Mapping) or not values or not all(
+            isinstance(name, str) and name for name in values
+        ):
+            raise InvalidRowArtifactError(
+                f"sqlalchemy_row artifact {artifact_index} values must be a non-empty string-keyed mapping"
+            )
+        commands.append(SqlAlchemyRowCommand(artifact_index, table_name, _freeze_values(values)))
+    return tuple(commands)
+
+
+def _prepare_value(value: Any, command_index: int, column_name: str) -> Any:
+    if value is MISSING:
+        raise UnsupportedMaterializedValueError(
+            f"command {command_index} column {column_name}: MISSING is not SQL NULL"
+        )
+    if isinstance(value, LogicalID):
+        return value.value
+    if value is None or isinstance(value, (bool, int, Decimal, str, timedelta)):
+        return value
+    if isinstance(value, datetime):
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise UnsupportedMaterializedValueError(
+                f"command {command_index} column {column_name}: datetime must be timezone-aware"
+            )
+        return value
+    raise UnsupportedMaterializedValueError(
+        f"command {command_index} column {column_name}: unsupported {type(value).__name__} value"
+    )
+
+
+def prepare_row_commands(
+    commands: tuple[SqlAlchemyRowCommand, ...], tables: Mapping[str, Table]
+) -> tuple[tuple[SqlAlchemyRowCommand, Table, Mapping[str, Any]], ...]:
+    """Purely prevalidate and prepare every command before transaction entry."""
+    prepared = []
+    for command_index, command in enumerate(commands):
+        if command.table_name not in tables:
+            raise UnknownTableBindingError(
+                f"command {command_index}: unknown table binding {command.table_name}"
+            )
+        table = tables[command.table_name]
+        if not isinstance(table, Table):
+            raise InvalidTableBindingError(
+                f"command {command_index}: binding {command.table_name} is not a SQLAlchemy Table"
+            )
+        unknown = sorted(set(command.values) - set(table.c.keys()))
+        if unknown:
+            raise InvalidColumnBindingError(
+                f"command {command_index} table {command.table_name}: unknown columns {','.join(unknown)}"
+            )
+        primary_keys = tuple(column.name for column in table.primary_key.columns)
+        if not primary_keys:
+            raise MissingPrimaryKeyError(
+                f"command {command_index} table {command.table_name}: target table has no primary key"
+            )
+        missing = tuple(name for name in primary_keys if name not in command.values)
+        if missing:
+            raise MissingPrimaryKeyError(
+                f"command {command_index} table {command.table_name}: missing primary key columns {','.join(missing)}"
+            )
+        values = {name: _prepare_value(command.values[name], command_index, name)
+                  for name in sorted(command.values)}
+        prepared.append((command, table, MappingProxyType(values)))
+    return tuple(prepared)
+
+
+def command_fingerprint(commands: tuple[SqlAlchemyRowCommand, ...]) -> str:
+    intent = [{
+        "artifact_index": command.artifact_index,
+        "table": command.table_name,
+        "values": dict(command.values),
+    } for command in commands]
+    return fingerprint(intent)
+
+
+def materialize_result(
+    engine: Engine, result: ScenarioResult, tables: Mapping[str, Table]
+) -> MaterializationReport:
+    """Prevalidate all commands, then insert all rows in one transaction."""
+    if not isinstance(engine, Engine):
+        raise TypeError("engine must be a SQLAlchemy Engine")
+    commands = extract_row_commands(result)
+    digest = command_fingerprint(commands)
+    if not commands:
+        return MaterializationReport(0, 0, MappingProxyType({}), digest)
+    prepared = prepare_row_commands(commands, tables)
+    try:
+        with engine.begin() as connection:
+            for command_index, (command, table, values) in enumerate(prepared):
+                try:
+                    connection.execute(table.insert().values(**dict(values)))
+                except Exception as exc:
+                    raise MaterializationExecutionError(
+                        f"command {command_index} table {command.table_name}: {type(exc).__name__}"
+                    ) from exc
+    except MaterializationExecutionError:
+        raise
+    counts = Counter(command.table_name for command in commands)
+    return MaterializationReport(
+        len(commands), len(commands),
+        MappingProxyType({name: counts[name] for name in sorted(counts)}), digest,
+    )
+
+
+__all__ = [
+    "InvalidColumnBindingError", "InvalidRowArtifactError", "InvalidTableBindingError",
+    "MaterializationExecutionError", "MaterializationReport", "MissingPrimaryKeyError",
+    "SqlAlchemyMaterializerError", "SqlAlchemyRowCommand", "UnknownTableBindingError",
+    "UnsupportedMaterializedValueError", "command_fingerprint", "extract_row_commands",
+    "materialize_result", "prepare_row_commands",
+]

scenario_engine/address.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+import json
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionAddress:
+    scenario_id: str
+    run_index: int = 0
+    subflow_invocations: tuple[int, ...] = ()
+    repetition_indexes: tuple[int, ...] = ()
+    step_id: str | None = None
+    semantic_path: tuple[str, ...] = ()
+
+    def for_step(self, step_id: str) -> ExecutionAddress:
+        return replace(self, step_id=step_id, semantic_path=())
+
+    def child(self, *path: str) -> ExecutionAddress:
+        return replace(self, semantic_path=self.semantic_path + tuple(path))
+
+    def with_subflow_invocation(self, index: int) -> ExecutionAddress:
+        return replace(self, subflow_invocations=self.subflow_invocations + (index,))
+
+    def with_repetition(self, index: int) -> ExecutionAddress:
+        return replace(self, repetition_indexes=self.repetition_indexes + (index,))
+
+    def canonical(self) -> str:
+        value = {
+            "path": list(self.semantic_path),
+            "repetitions": list(self.repetition_indexes),
+            "run": self.run_index,
+            "scenario": self.scenario_id,
+            "step": self.step_id,
+            "subflows": list(self.subflow_invocations),
+        }
+        return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)

scenario_engine/artifacts.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .address import ExecutionAddress
+from .ids import LogicalID
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedArtifact:
+    artifact_type: str
+    name: str
+    value: Any
+    logical_id: LogicalID
+    address: ExecutionAddress

scenario_engine/canonical.py

@@ -0,0 +1,109 @@
+"""Canonical semantic representation for validated Phase 0.1 DSL documents."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import TYPE_CHECKING, Any, Mapping
+
+from .values import normalize
+
+if TYPE_CHECKING:
+    from .dsl.models import CompiledScenario, ScenarioDocument, StepDocument
+
+
+_SEMANTIC_WRAPPERS = {"$decimal", "$datetime", "$duration", "$missing"}
+
+
+def _canonical_node(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        if len(value) == 1 and next(iter(value)) in _SEMANTIC_WRAPPERS:
+            from .dsl.parser import decode_semantic_value
+
+            return decode_semantic_value(value)
+        if len(value) == 1 and "$literal" in value:
+            from .dsl.parser import decode_semantic_value
+
+            return {"$literal": decode_semantic_value(value["$literal"])}
+        return {key: _canonical_node(value[key]) for key in sorted(value)}
+    if isinstance(value, (list, tuple)):
+        return [_canonical_node(item) for item in value]
+    return value
+
+
+def _step_payload(step: StepDocument) -> Mapping[str, Any]:
+    payload = {
+        "advance": step.advance,
+        "derive": _canonical_node(step.derive),
+        "emit": _canonical_node(step.emit),
+        "generate": _canonical_node(step.generate),
+        "id": step.step_id,
+        "transition": step.transition,
+        "write": _canonical_node(step.write),
+    }
+    if step.call is not None: payload["call"] = _canonical_node(step.call)
+    if step.branch is not None: payload["branch"] = _canonical_node(step.branch)
+    if step.repeat is not None: payload["repeat"] = _canonical_node(step.repeat)
+    return payload
+
+
+def _document(value: str | ScenarioDocument | CompiledScenario) -> ScenarioDocument:
+    from .dsl.models import CompiledScenario, ScenarioDocument
+    from .dsl.parser import parse_yaml
+
+    if isinstance(value, str):
+        return parse_yaml(value)
+    if isinstance(value, CompiledScenario):
+        return value.document
+    if isinstance(value, ScenarioDocument):
+        return value
+    raise TypeError("scenario must be YAML text, ScenarioDocument, or CompiledScenario")
+
+
+def canonical_scenario_payload(
+    scenario: str | ScenarioDocument | CompiledScenario,
+) -> Mapping[str, Any]:
+    """Return the JSON-compatible semantic payload of a validated scenario."""
+    document = _document(scenario)
+    payload = {
+        "clock": {"start": document.reference_clock_start},
+        "dsl_version": document.dsl_version,
+        "initial_state": document.initial_state,
+        "scenario": document.scenario_id,
+        "steps": [_step_payload(step) for step in document.steps],
+    }
+    if document.resources:
+        payload["resources"] = _canonical_node(document.resources)
+    if document.validators:
+        payload["validators"] = _canonical_node(document.validators)
+    if document.constraints:
+        payload["constraints"] = _canonical_node(document.constraints)
+    if document.subflows:
+        payload["subflows"] = {
+            name: {"steps": [_step_payload(step) for step in document.subflows[name]]}
+            for name in sorted(document.subflows)
+        }
+    if document.invariants:
+        payload["invariants"] = _canonical_node(document.invariants)
+    if document.faults:
+        payload["faults"] = _canonical_node(document.faults)
+    if document.oracle is not None:
+        payload["oracle"] = _canonical_node(document.oracle)
+    return normalize(payload)
+
+
+def canonical_scenario_bytes(
+    scenario: str | ScenarioDocument | CompiledScenario,
+) -> bytes:
+    return json.dumps(
+        canonical_scenario_payload(scenario),
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+
+
+def canonical_scenario_hash(
+    scenario: str | ScenarioDocument | CompiledScenario,
+) -> str:
+    return hashlib.sha256(canonical_scenario_bytes(scenario)).hexdigest()

scenario_engine/clock.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+
+class LogicalClock:
+    def __init__(self, reference: datetime):
+        if reference.tzinfo is None or reference.utcoffset() is None:
+            raise ValueError("logical clock reference must be timezone-aware")
+        self._current = reference.astimezone(timezone.utc)
+
+    @property
+    def current(self) -> datetime:
+        return self._current
+
+    def prospective(self, advance: timedelta) -> datetime:
+        return self._current + advance
+
+    def commit(self, timestamp: datetime) -> None:
+        if timestamp.tzinfo is None or timestamp.utcoffset() is None:
+            raise ValueError("committed timestamp must be timezone-aware")
+        self._current = timestamp.astimezone(timezone.utc)

scenario_engine/context.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .address import ExecutionAddress
+from .clock import LogicalClock
+from .ids import DeterministicIDProvider, LogicalID
+from .rng import DeterministicRNG
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationContext:
+    root_seed: str | int
+    address: ExecutionAddress
+    clock: LogicalClock
+    ids: DeterministicIDProvider
+
+    def rng(self) -> DeterministicRNG:
+        return DeterministicRNG(self.root_seed, self.address)
+
+    def logical_id(self, slot: str) -> LogicalID:
+        return self.ids.derive(self.address, slot)
+
+    def at(self, address: ExecutionAddress) -> GenerationContext:
+        return GenerationContext(self.root_seed, address, self.clock, self.ids)

scenario_engine/control_flow.py

@@ -0,0 +1,63 @@
+"""Deterministic, bounded structured-control primitives for Phase 0.4."""
+
+from __future__ import annotations
+
+import hashlib
+from copy import deepcopy
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from .errors import ScenarioEngineError
+from .expressions import EvaluationEnvironment
+
+MAX_REPEAT_COUNT = 100
+
+
+class ControlFlowError(ScenarioEngineError, ValueError):
+    pass
+
+
+class UnknownSubflowError(ControlFlowError):
+    pass
+
+
+class SubflowCycleError(ControlFlowError):
+    pass
+
+
+class BranchConditionError(ControlFlowError):
+    pass
+
+
+class RepeatCountError(ControlFlowError):
+    pass
+
+
+class RepeatLimitError(ControlFlowError):
+    pass
+
+
+def invocation_component(control_id: str, subflow: str) -> int:
+    """Return stable call-site identity in the reserved integer address dimension."""
+    payload = f"phase0.4\0{control_id}\0{subflow}".encode("utf-8")
+    return int.from_bytes(hashlib.sha256(payload).digest()[:8], "big")
+
+
+def immutable_scope(values: Mapping[str, Any]) -> Mapping[str, Any]:
+    return MappingProxyType(deepcopy(dict(values)))
+
+
+def evaluate_bindings(bindings, compile_expression, state, resources, scope):
+    env = EvaluationEnvironment(state, MappingProxyType({}), MappingProxyType({}), scope)
+    return immutable_scope({
+        name: compile_expression(bindings[name], resources).evaluate(env)
+        for name in sorted(bindings)
+    })
+
+
+def validate_repeat_count(value: Any, maximum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise RepeatCountError("repeat count must be a nonnegative integer, not boolean")
+    if value > maximum:
+        raise RepeatLimitError(f"repeat count {value} exceeds declared max {maximum}")
+    return value

scenario_engine/dsl/__init__.py

@@ -0,0 +1,31 @@
+"""Phase 0.1B minimal, strictly validated linear declarative DSL."""
+
+from .compiler import compile_document
+from .errors import (
+    DSLCompilationError, DSLError, DSLParseError, DSLSchemaError,
+    UnsupportedDSLVersionError,
+)
+from .models import CompiledScenario, ScenarioDocument
+from .parser import decode_semantic_value, parse_yaml, parse_yaml_file
+from .runtime import ScenarioResult, evaluate_scenario, replay_scenario, run_scenario
+from scenario_engine.invariants import InvariantDefinitionError, InvariantViolation
+from scenario_engine.oracle import OracleEvaluation, OracleMismatchError, OracleReport
+from scenario_engine.resources import ResourceCycleError, ResourceResolutionError, ResolvedResources, resolve_resources
+from scenario_engine.validation import ConstraintDefinitionError, ConstraintViolation, ResourceValidationError
+from scenario_engine.control_flow import (BranchConditionError, ControlFlowError,
+    RepeatCountError, RepeatLimitError, SubflowCycleError, UnknownSubflowError)
+from scenario_engine.expressions import ScopeResolutionError
+from scenario_engine.plugins import PluginCompatibilityError
+
+__all__ = [
+    "CompiledScenario", "DSLCompilationError", "DSLError", "DSLParseError",
+    "DSLSchemaError", "ScenarioDocument", "ScenarioResult",
+    "UnsupportedDSLVersionError", "compile_document", "decode_semantic_value",
+    "parse_yaml", "parse_yaml_file", "replay_scenario", "run_scenario", "evaluate_scenario",
+    "ResourceCycleError", "ResourceResolutionError", "ResolvedResources", "resolve_resources",
+    "ConstraintDefinitionError", "ConstraintViolation", "ResourceValidationError",
+    "BranchConditionError", "ControlFlowError", "RepeatCountError", "RepeatLimitError",
+    "ScopeResolutionError", "SubflowCycleError", "UnknownSubflowError",
+    "InvariantDefinitionError", "InvariantViolation", "OracleEvaluation", "OracleMismatchError", "OracleReport",
+    "PluginCompatibilityError",
+]