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

scenario_engine/dsl/compiler.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from scenario_engine.artifacts import GeneratedArtifact
+from scenario_engine.context import GenerationContext
+from scenario_engine.expressions import (
+    Add, Append, BooleanMany, BooleanNot, DerivedRef, Divide, Equal, Expression,
+    GreaterThan, GreaterThanOrEqual, Length, LessThan, LessThanOrEqual, Literal,
+    LocalRef, Multiply, NotEqual, Record, ScopeRef, StateRef, Subtract, SumField,
+)
+from scenario_engine.runner import StepSpec
+from scenario_engine.expressions import resolve_semantic_path
+from scenario_engine.plugins import PluginRegistry, invoke_plugin
+
+from .errors import DSLCompilationError
+from .models import CompiledScenario, CompiledStep, ScenarioDocument
+from .parser import decode_semantic_value
+
+
+@dataclass(frozen=True, slots=True)
+class LogicalIDGenerator:
+    slot: str
+
+    def generate(self, context: GenerationContext) -> Any:
+        return context.logical_id(self.slot)
+
+
+@dataclass(frozen=True, slots=True)
+class LiteralGenerator:
+    value: Any
+
+    def generate(self, context: GenerationContext) -> Any:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class IntegerGenerator:
+    minimum: int
+    maximum: int
+
+    def generate(self, context: GenerationContext) -> int:
+        return context.rng().inclusive_int(self.minimum, self.maximum)
+
+
+@dataclass(frozen=True, slots=True)
+class PluginGenerator:
+    name: str
+    version: str
+    arguments: Mapping[str, Expression]
+    registry: PluginRegistry
+    state: Mapping[str, Any]
+
+    def generate(self, context: GenerationContext) -> Any:
+        from scenario_engine.expressions import EvaluationEnvironment
+
+        state = self.state.snapshot() if hasattr(self.state, "snapshot") else self.state
+        environment = EvaluationEnvironment(state, MappingProxyType({}), MappingProxyType({}))
+        arguments = {name: expression.evaluate(environment) for name, expression in self.arguments.items()}
+        return invoke_plugin(self.registry.require(self.name, self.version), context, arguments)
+
+
+def _expression(node: Mapping[str, Any], resources=None, scope=None) -> Expression:
+    operator, payload = next(iter(node.items()))
+    if operator == "$state":
+        return StateRef(payload)
+    if operator == "$local":
+        return LocalRef(payload)
+    if operator == "$derived":
+        return DerivedRef(payload)
+    if operator == "$literal":
+        return Literal(decode_semantic_value(payload))
+    if operator == "$resource":
+        if resources is None:
+            return Literal(payload)  # replaced before execution during preparation
+        return Literal(resources.lookup(payload))
+    if operator == "$scope":
+        return ScopeRef(payload) if scope is None else Literal(resolve_semantic_path(scope, payload))
+    if operator == "$add":
+        return Add(_expression(payload[0], resources, scope), _expression(payload[1], resources, scope))
+    if operator == "$mul":
+        return Multiply(_expression(payload[0], resources, scope), _expression(payload[1], resources, scope))
+    binary = {"$sub": Subtract, "$div": Divide, "$eq": Equal, "$ne": NotEqual,
+              "$lt": LessThan, "$lte": LessThanOrEqual, "$gt": GreaterThan,
+              "$gte": GreaterThanOrEqual}
+    if operator in binary:
+        return binary[operator](_expression(payload[0], resources, scope), _expression(payload[1], resources, scope))
+    if operator in {"$and", "$or"}:
+        return BooleanMany(tuple(_expression(child, resources, scope) for child in payload), operator == "$and")
+    if operator == "$not": return BooleanNot(_expression(payload, resources, scope))
+    if operator == "$len": return Length(_expression(payload, resources, scope))
+    if operator == "$append":
+        return Append(_expression(payload["list"], resources, scope), _expression(payload["value"], resources, scope))
+    if operator == "$object":
+        return Record(MappingProxyType({name: _expression(child, resources, scope) for name, child in payload.items()}))
+    if operator == "$sum_field":
+        return SumField(_expression(payload["source"], resources, scope), payload["field"])
+    raise AssertionError("validated expression operator was not compiled")
+
+
+def _generator(node: Mapping[str, Any], resources=None, scope=None, plugins=None, state=None) -> Any:
+    operator, payload = next(iter(node.items()))
+    if operator == "$int":
+        return IntegerGenerator(payload[0], payload[1])
+    if operator == "$id":
+        return LogicalIDGenerator(payload)
+    if operator == "$literal":
+        return LiteralGenerator(decode_semantic_value(payload))
+    if operator == "$plugin":
+        arguments = MappingProxyType({
+            name: _expression(expression, resources, scope)
+            for name, expression in payload.get("args", {}).items()
+        })
+        return PluginGenerator(payload["name"], payload["version"], arguments,
+                               plugins or PluginRegistry(), state or MappingProxyType({}))
+    raise AssertionError("validated generator operator was not compiled")
+
+
+def _emitter(declarations: tuple[Mapping[str, Any], ...], resources=None, scope=None):
+    compiled = tuple((declaration["type"], {
+        name: _expression(node, resources, scope) for name, node in declaration["fields"].items()
+    }) for declaration in declarations)
+
+    def emit(context, post_state, locals_, derived):
+        from scenario_engine.expressions import EvaluationEnvironment
+
+        env = EvaluationEnvironment(post_state, MappingProxyType({}), MappingProxyType({}))
+        artifacts = []
+        for index, (artifact_type, fields) in enumerate(compiled):
+            address = context.address.child("emit", str(index), artifact_type)
+            value = {name: fields[name].evaluate(env) for name in sorted(fields)}
+            artifacts.append(GeneratedArtifact(
+                artifact_type, artifact_type, value,
+                context.ids.derive(address, "artifact"), address,
+            ))
+        return tuple(artifacts)
+
+    return emit
+
+
+def _validate_sequence(steps, path):
+    ids = [step.step_id for step in steps]
+    known = set(ids)
+    for index, step in enumerate(steps):
+        expected = ids[index + 1] if index + 1 < len(ids) else None
+        if step.transition is not None and step.transition not in known:
+            raise DSLCompilationError(
+                f"{path}[{index}].transition: unknown node ID {step.transition}"
+            )
+        if step.transition != expected:
+            if expected is None:
+                message = "final step transition must be null"
+            elif step.transition is None:
+                message = f"non-final step transition must be {expected}"
+            else:
+                message = f"linear transition must target immediately following step {expected}"
+            raise DSLCompilationError(f"{path}[{index}].transition: {message}")
+
+
+def _targets(step):
+    if step.call is not None: return (step.call["subflow"],)
+    if step.repeat is not None: return (step.repeat["subflow"],)
+    if step.branch is not None:
+        result = [case["subflow"] for case in step.branch["cases"]]
+        if "else" in step.branch: result.append(step.branch["else"]["subflow"])
+        return tuple(result)
+    return ()
+
+
+def _validate_control(document):
+    from scenario_engine.control_flow import SubflowCycleError, UnknownSubflowError
+    known = set(document.subflows)
+    for sequence_name, steps in (("$", document.steps), *sorted(document.subflows.items())):
+        for step in steps:
+            for target in _targets(step):
+                if target not in known: raise UnknownSubflowError(f"{step.step_id}: unknown subflow {target}")
+    graph = {name: sorted({target for step in steps for target in _targets(step)}) for name, steps in document.subflows.items()}
+    visiting, complete = [], set()
+    def visit(name):
+        if name in visiting:
+            cycle = visiting[visiting.index(name):] + [name]
+            raise SubflowCycleError("subflow call cycle: " + " -> ".join(cycle))
+        if name in complete: return
+        visiting.append(name)
+        for child in graph[name]: visit(child)
+        visiting.pop(); complete.add(name)
+    for name in sorted(graph): visit(name)
+
+
+def _compile_step(step, resources, scope=None, plugins=None, state=None):
+    if step.control_kind is not None:
+        return step
+    transition = step.transition
+    spec = StepSpec(
+        step.step_id,
+        MappingProxyType({name: _generator(node, resources, scope, plugins, state)
+                          for name, node in step.generate.items()}),
+        MappingProxyType({name: _expression(node, resources, scope) for name, node in step.derive.items()}),
+        MappingProxyType({name: _expression(node, resources, scope) for name, node in step.write.items()}),
+        step.advance, emit=_emitter(step.emit, resources, scope), transition=lambda state, target=transition: target,
+    )
+    return CompiledStep(spec, transition)
+
+
+def compile_document(document: ScenarioDocument, resources=None, plugins=None,
+                     state=None) -> CompiledScenario:
+    _validate_sequence(document.steps, "$.steps")
+    for name, steps in document.subflows.items(): _validate_sequence(steps, f"$.subflows.{name}.steps")
+    _validate_control(document)
+    compiled: list[Any] = []
+    for step in document.steps:
+        compiled.append(_compile_step(step, resources, plugins=plugins, state=state))
+    subflows = MappingProxyType({name: tuple(_compile_step(step, resources, plugins=plugins, state=state)
+        for step in steps) for name, steps in document.subflows.items()})
+    return CompiledScenario(
+        document.scenario_id, document.reference_clock_start, document.initial_state,
+        tuple(compiled), compiled[0].step_id, document, resources, subflows,
+    )
+
+
+def compile_constraint(node: Mapping[str, Any], resources) -> Expression:
+    return _expression(node, resources)
+
+
+def compile_expression(node: Mapping[str, Any], resources, scope=None) -> Expression:
+    return _expression(node, resources, scope)
+
+
+def compile_scoped_sequence(steps, resources, scope, plugins=None, state=None):
+    return tuple(_compile_step(step, resources, scope, plugins, state) for step in steps)

scenario_engine/dsl/errors.py

@@ -0,0 +1,23 @@
+"""Deterministic public errors for the Phase 0.1B declarative layer."""
+
+from scenario_engine.errors import ScenarioEngineError
+
+
+class DSLError(ScenarioEngineError, ValueError):
+    """Base class for declarative scenario errors."""
+
+
+class DSLParseError(DSLError):
+    """The YAML stream could not be safely loaded."""
+
+
+class DSLSchemaError(DSLError):
+    """The loaded document has an invalid shape or value."""
+
+
+class UnsupportedDSLVersionError(DSLSchemaError):
+    """The document requests an unsupported DSL version."""
+
+
+class DSLCompilationError(DSLError):
+    """The document is well-shaped but statically invalid."""

scenario_engine/dsl/models.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from scenario_engine.runner import StepSpec
+
+
+def frozen_mapping(value: Mapping[str, Any]) -> Mapping[str, Any]:
+    return MappingProxyType(dict(value))
+
+
+@dataclass(frozen=True, slots=True)
+class StepDocument:
+    step_id: str
+    generate: Mapping[str, Any]
+    derive: Mapping[str, Any]
+    write: Mapping[str, Any]
+    emit: tuple[Mapping[str, Any], ...]
+    advance: timedelta
+    transition: str | None
+    call: Mapping[str, Any] | None = None
+    branch: Mapping[str, Any] | None = None
+    repeat: Mapping[str, Any] | None = None
+
+    @property
+    def control_kind(self) -> str | None:
+        if self.call is not None:
+            return "call"
+        if self.branch is not None:
+            return "branch"
+        if self.repeat is not None:
+            return "repeat"
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class ScenarioDocument:
+    dsl_version: int
+    scenario_id: str
+    reference_clock_start: datetime
+    initial_state: Mapping[str, Any]
+    steps: tuple[StepDocument, ...]
+    resources: Mapping[str, Any] = MappingProxyType({})
+    validators: tuple[Mapping[str, Any], ...] = ()
+    constraints: tuple[Mapping[str, Any], ...] = ()
+    subflows: Mapping[str, tuple[StepDocument, ...]] = MappingProxyType({})
+    invariants: tuple[Mapping[str, Any], ...] = ()
+    faults: tuple[Mapping[str, Any], ...] = ()
+    oracle: Mapping[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledStep:
+    spec: StepSpec
+    transition: str | None
+
+    @property
+    def step_id(self) -> str:
+        return self.spec.step_id
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledScenario:
+    scenario_id: str
+    reference_clock_start: datetime
+    initial_state: Mapping[str, Any]
+    steps: tuple[CompiledStep, ...]
+    start_step: str
+    document: ScenarioDocument
+    resources: Any = None
+    subflows: Mapping[str, tuple[CompiledStep | StepDocument, ...]] = MappingProxyType({})