rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/interfaces/references.py

@@ -0,0 +1,115 @@
+"""Scoped reference resolution and connection checks (I02).
+
+Resolution assumes a validated store: files here were accepted by
+validate_document at ingestion. The scan therefore uses a plain safe
+load and skips anything outside the root or unparseable.
+"""
+
+from pathlib import Path
+
+from ruamel.yaml import YAML
+
+from .documents import validate_document
+from .errors import ContractError
+
+
+def _matches(doc, ref):
+    return (
+        isinstance(doc, dict)
+        and doc.get("scope") == ref.get("scope")
+        and doc.get("id") == ref.get("id")
+        and doc.get("revision") == ref.get("revision")
+    )
+
+
+def _scan(root):
+    yaml = YAML(typ="safe")
+    for path in sorted(root.rglob("*.yaml")):
+        try:
+            path.resolve().relative_to(root)
+        except ValueError:
+            continue
+        try:
+            doc = yaml.load(path.read_text())
+        except Exception:
+            continue
+        if isinstance(doc, dict):
+            yield doc
+
+
+def resolve_reference(ref, root, path=None):
+    """Resolve an exact {scope, id, revision} reference inside root.
+
+    Args:
+        ref: Reference mapping with scope, id, and revision.
+        root: Store root the resolution stays inside.
+        path: Optional direct path under root; scans the store
+            when omitted.
+
+    Returns:
+        Matching validated record mapping.
+
+    Raises:
+        ContractError: invalid_reference for an escape, a mismatch
+            at path, or an unknown reference; invalid_yaml when a
+            direct path cannot load.
+    """
+    root = Path(root).resolve()
+    if path is not None:
+        target = (root / path).resolve()
+        try:
+            target.relative_to(root)
+        except ValueError:
+            raise ContractError(
+                "invalid_reference", f"Reference escapes store root: {path}."
+            ) from None
+        try:
+            doc = YAML(typ="safe").load(target.read_text())
+        except Exception as exc:
+            raise ContractError("invalid_yaml", f"Cannot load {path}: {exc}") from exc
+        if _matches(doc, ref):
+            return doc
+        raise ContractError("invalid_reference", f"No match at path: {path}.")
+    for doc in _scan(root):
+        if _matches(doc, ref):
+            return doc
+    raise ContractError(
+        "invalid_reference",
+        f"Unknown reference: {ref.get('scope')}/{ref.get('id')}@{ref.get('revision')}.",
+    )
+
+
+def check_connection(text, endpoint_a, endpoint_b):
+    """Check two endpoints for unit/port compatibility.
+
+    Args:
+        text: Validated-record YAML text holding the port table.
+        endpoint_a: First (instance, port) endpoint.
+        endpoint_b: Second (instance, port) endpoint.
+
+    Returns:
+        Compatibility mapping (compatible True).
+
+    Raises:
+        ContractError: invalid_yaml for a bad record,
+            invalid_reference for an unknown port,
+            incompatible_port for mismatched wavelength units.
+    """
+    data = validate_document(text)
+    ports = data.get("ports", {})
+
+    def _wavelength_unit(endpoint):
+        _, port = endpoint
+        if port not in ports:
+            raise ContractError("invalid_reference", f"Unknown port: {port}.")
+        props = ports[port].get("properties", {})
+        return props.get("wavelength", {}).get("unit")
+
+    unit_a = _wavelength_unit(endpoint_a)
+    unit_b = _wavelength_unit(endpoint_b)
+    if unit_a and unit_b and unit_a != unit_b:
+        raise ContractError(
+            "incompatible_port",
+            f"Incompatible wavelength units: {unit_a} vs {unit_b}.",
+        )
+    return {"compatible": True}

rocket_engine/interfaces/refs.py

@@ -0,0 +1,85 @@
+"""I28 ingredient-closure pins for Wave-3 editor and testbench verbs.
+
+Pure helpers (no I/O, no logic beyond digests): every Wave-3
+mutation receipt carries an ``i28`` closure pinning the consumed
+revisions (entities, templates, profiles) so a replay can prove
+drift instead of assuming it. Stored digests are canonical-JSON
+sha1, matching the ledger content-key discipline.
+"""
+
+import copy
+import hashlib
+import json
+
+
+def digest_mapping(mapping):
+    """Digest one JSON-shaped mapping for an I28 pin.
+
+    Args:
+        mapping: JSON-shaped mapping to digest.
+
+    Returns:
+        Twelve hex characters of canonical-JSON sha1.
+    """
+    text = json.dumps(mapping, sort_keys=True, default=str)
+    return hashlib.sha1(text.encode("utf-8")).hexdigest()[:12]
+
+
+def pin_entities(head, revisions):
+    """Pin consumed entity revisions at one head revision.
+
+    Args:
+        head: Ledger head revision the pin rides on.
+        revisions: Entity id to live entity revision mapping.
+
+    Returns:
+        Pin with head revision plus the sorted entity map.
+    """
+    return {
+        "revision": head,
+        "entities": {key: revisions[key] for key in sorted(revisions)},
+    }
+
+
+def pin_template(provenance):
+    """Pin one template provenance into the closure.
+
+    Args:
+        provenance: Template provenance mapping (kind,
+            template_version, digest).
+
+    Returns:
+        Deep copy of the provenance plus its digest pin.
+    """
+    kept = copy.deepcopy(dict(provenance or {}))
+    kept["digest"] = kept.get("digest") or digest_mapping(kept)
+    return kept
+
+
+def pin_closure(head, entities=None, template=None, profile=None):
+    """Assemble one I28 closure pin for a Wave-3 receipt.
+
+    Args:
+        head: Ledger head revision the pin rides on.
+        entities: Entity id to live revision mapping, if any.
+        template: Template provenance mapping, if consumed.
+        profile: Technology profile pin ({name, version}), if
+            consumed.
+
+    Returns:
+        Closure pin with revision, entity pins, template pin,
+            and profile pin (each present only when consumed).
+    """
+    pin = {"revision": head}
+    if entities:
+        pin["entities"] = {
+            key: entities[key] for key in sorted(entities)
+        }
+    if template is not None:
+        pin["template"] = pin_template(template)
+    if profile is not None:
+        pin["profile"] = copy.deepcopy(dict(profile))
+    pin["digest"] = digest_mapping(
+        {key: pin[key] for key in sorted(pin) if key != "digest"}
+    )
+    return pin

rocket_engine/interfaces/runparams.py

@@ -0,0 +1,304 @@
+"""Explicit run.request params schema (RUN-PARAMS).
+
+Runs are explicit, always — no live-update path — so every knob a
+run needs travels IN the run request, frozen into the run snapshot
+like everything else. xschem keeps netlist knobs as live TCL vars;
+the web split cannot do that without per-event round-trips, so they
+become explicit `request` parameters: netlist type, flat/split
+shape, the LVS-netlist flag, top-is-subckt, deck opts
+passthrough, and the solver budget (null keeps the adapter
+default). Without this schema run reproducibility has a hole:
+two identical-looking runs could differ by a knob nobody recorded.
+
+Validated at submit (`Engine.submit` and `Engine.run` normalize
+`arguments["request"]` through `validate_run_request` before the
+command text is frozen), replayed byte-identically through
+`freeze_run_request`, and read back through `parse_run_request`.
+Unknown fields are rejected loudly, never ignored — and every
+caller (IDE, MCP, console) sends the same shape because validation
+lives in the engine, not the transports.
+"""
+
+import io
+
+from ruamel.yaml import YAML
+
+# Mirrors xschem's netlist_type TCL var: the netlist dialect the run
+# netlists in. Canonical order is display order (error text, schema).
+NETLIST_TYPES = ("spice", "spectre", "verilog", "vhdl")
+
+# Solver-lane budget bounds, mirroring the python lane so one
+# hanging tool cannot pin a drain worker forever. None means
+# "adapter default" (a spice sim keeps 120s, a LibreLane flow
+# keeps its hour); the engine stamps the job only when set.
+MIN_TIMEOUT_S = 1
+MAX_TIMEOUT_S = 1800
+DEFAULT_TIMEOUT_S = None
+
+# Canonical knob order: validation output, frozen text, and the
+# schema all follow this order so replays compare byte-identically.
+RUN_REQUEST_FIELDS = (
+    "netlist_type",
+    "flat_netlist",
+    "lvs_netlist",
+    "top_is_subckt",
+    "deck_opts",
+    "timeout_s",
+)
+
+RUN_REQUEST_DEFAULTS = {
+    "netlist_type": "spice",
+    "flat_netlist": False,
+    "lvs_netlist": False,
+    "top_is_subckt": False,
+    "deck_opts": {},
+    "timeout_s": DEFAULT_TIMEOUT_S,
+}
+
+_BOOL_FLAGS = ("flat_netlist", "lvs_netlist", "top_is_subckt")
+
+# Deck opts pass through to the solver deck untouched: flat scalar
+# options only (a nested mapping would smuggle unvalidated shape
+# into the tool call). None means "present but valueless".
+_SCALAR_TYPES = (str, int, float, bool, type(None))
+
+# Machine seam for api_spec/contract regen: the integrator injects
+# this `request` property into solver-op schemas from here, the way
+# expected_revision is injected from ProjectService.submit's arg
+# text. additionalProperties False is the schema half of "unknown
+# fields rejected, never ignored".
+RUN_REQUEST_SCHEMA = {
+    "type": "object",
+    "description": (
+        "Explicit run knobs (xschem live-var equivalents), frozen "
+        "into the run snapshot. Unknown fields are rejected."
+    ),
+    "properties": {
+        "netlist_type": {
+            "type": "string",
+            # Literal (not list(NETLIST_TYPES)): api_spec reads this
+            # schema via AST without importing; tests pin equality.
+            "enum": ["spice", "spectre", "verilog", "vhdl"],
+            "default": "spice",
+            "description": "Netlist dialect the run netlists in.",
+        },
+        "flat_netlist": {
+            "type": "boolean",
+            "default": False,
+            "description": "Flatten the hierarchy (else split per cell).",
+        },
+        "lvs_netlist": {
+            "type": "boolean",
+            "default": False,
+            "description": "Netlist for LVS comparison.",
+        },
+        "top_is_subckt": {
+            "type": "boolean",
+            "default": False,
+            "description": "Emit the top cell as a subcircuit.",
+        },
+        "deck_opts": {
+            "type": "object",
+            "default": {},
+            "description": "Solver deck options, flat scalar passthrough.",
+        },
+        "timeout_s": {
+            "type": ["number", "null"],
+            "default": None,
+            "description": (
+                "Solver budget in seconds; null keeps the adapter "
+                "default."
+            ),
+        },
+    },
+    "additionalProperties": False,
+}
+
+
+class RunParamsError(Exception):
+    """Run.request violation with a stable machine code.
+
+    Args:
+        code: Stable machine-readable error code
+            (unknown_run_param, invalid_run_param,
+            invalid_run_request).
+        message: Human-readable detail naming the field.
+        fields: Itemized fields, when the error names any.
+    """
+
+    def __init__(self, code, message, fields=None):
+        super().__init__(message)
+        self.code = code
+        self.fields = fields or []
+
+
+def _check_deck_opts(opts):
+    """Validate deck opts: string keys, flat scalar values."""
+    if not isinstance(opts, dict):
+        raise RunParamsError(
+            "invalid_run_param",
+            f"deck_opts must be a mapping, got {opts!r}.",
+            fields=["deck_opts"],
+        )
+    for key, value in opts.items():
+        if not isinstance(key, str) or not key:
+            raise RunParamsError(
+                "invalid_run_param",
+                f"deck_opts keys must be non-empty strings, got {key!r}.",
+                fields=["deck_opts"],
+            )
+        if not isinstance(value, _SCALAR_TYPES):
+            raise RunParamsError(
+                "invalid_run_param",
+                f"deck_opts.{key} must be a scalar, got {value!r}.",
+                fields=["deck_opts"],
+            )
+    return dict(opts)
+
+
+def validate_run_request(params):
+    """Validate and normalize one run.request mapping.
+
+    Missing input (None) and `{}` both mean "all defaults": the
+    frozen snapshot always shows every knob explicitly, so old
+    callers that send no `request` still record what they ran with.
+
+    Args:
+        params: Caller-supplied `request` mapping, or None when
+            the caller sent no `request` key.
+
+    Returns:
+        Normalized mapping with every knob present in canonical
+        field order: caller values where given, schema defaults
+        elsewhere. A fresh mapping — the caller's dict is never
+        mutated.
+
+    Raises:
+        RunParamsError: unknown_run_param naming every unknown
+            field, invalid_run_param naming the mistyped field
+            (netlist_type outside the enum, a non-bool flag, a
+            malformed deck_opts), invalid_run_request for a
+            non-mapping `request`.
+    """
+    if params is None:
+        params = {}
+    if not isinstance(params, dict):
+        raise RunParamsError(
+            "invalid_run_request",
+            f"request must be a mapping, got {params!r}.",
+        )
+    unknown = sorted(key for key in params if key not in RUN_REQUEST_FIELDS)
+    if unknown:
+        raise RunParamsError(
+            "unknown_run_param",
+            f"Unknown run.request field(s): {', '.join(map(repr, unknown))}; "
+            f"known fields: {', '.join(RUN_REQUEST_FIELDS)}.",
+            fields=unknown,
+        )
+    kind = params.get("netlist_type", RUN_REQUEST_DEFAULTS["netlist_type"])
+    if kind not in NETLIST_TYPES:
+        raise RunParamsError(
+            "invalid_run_param",
+            f"netlist_type must be one of {', '.join(NETLIST_TYPES)}, "
+            f"got {kind!r}.",
+            fields=["netlist_type"],
+        )
+    normalized = {"netlist_type": kind}
+    for flag in _BOOL_FLAGS:
+        value = params.get(flag, False)
+        if not isinstance(value, bool):
+            raise RunParamsError(
+                "invalid_run_param",
+                f"{flag} must be a boolean, got {value!r}.",
+                fields=[flag],
+            )
+        normalized[flag] = value
+    normalized["deck_opts"] = _check_deck_opts(
+        params.get("deck_opts", RUN_REQUEST_DEFAULTS["deck_opts"])
+    )
+    normalized["timeout_s"] = _check_timeout(
+        params.get("timeout_s", RUN_REQUEST_DEFAULTS["timeout_s"])
+    )
+    return normalized
+
+
+def _check_timeout(value):
+    """Validate the solver budget: a positive number in bounds, or None.
+
+    Args:
+        value: Caller-supplied `timeout_s`, or None for the
+            adapter default.
+
+    Returns:
+        The validated budget, unchanged.
+
+    Raises:
+        RunParamsError: invalid_run_param for a boolean,
+            non-number, or out-of-bounds budget.
+    """
+    if value is None:
+        return None
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not MIN_TIMEOUT_S <= value <= MAX_TIMEOUT_S
+    ):
+        raise RunParamsError(
+            "invalid_run_param",
+            f"timeout_s must be {MIN_TIMEOUT_S}..{MAX_TIMEOUT_S} seconds "
+            f"or null, got {value!r}.",
+            fields=["timeout_s"],
+        )
+    return value
+
+
+def freeze_run_request(validated):
+    """Render validated knobs as canonical inputs.yaml text.
+
+    Key order is canonical (schema field order, deck opts sorted),
+    so the same logical request replays byte-identically whatever
+    key order the caller sent.
+
+    Args:
+        validated: Normalized mapping from `validate_run_request`.
+
+    Returns:
+        Deterministic YAML text (`request:` mapping) for the run
+        snapshot: same knobs in, same bytes out.
+    """
+    ordered = {field: validated[field] for field in RUN_REQUEST_FIELDS}
+    ordered["deck_opts"] = {
+        key: ordered["deck_opts"][key] for key in sorted(ordered["deck_opts"])
+    }
+    buf = io.StringIO()
+    YAML(typ="safe").dump({"request": ordered}, buf)
+    return buf.getvalue()
+
+
+def parse_run_request(text):
+    """Read frozen inputs.yaml text back into validated knobs.
+
+    Args:
+        text: YAML text holding a top-level `request:` mapping, as
+            rendered by `freeze_run_request`.
+
+    Returns:
+        Validated mapping (see `validate_run_request`).
+
+    Raises:
+        RunParamsError: invalid_run_request for unparsable text or
+            a missing/non-mapping `request`, else whatever
+            `validate_run_request` raises for the stored knobs.
+    """
+    try:
+        data = YAML(typ="safe").load(text)
+    except Exception as exc:
+        raise RunParamsError(
+            "invalid_run_request", f"Cannot parse inputs.yaml: {exc}."
+        ) from exc
+    if not isinstance(data, dict) or not isinstance(data.get("request"), dict):
+        raise RunParamsError(
+            "invalid_run_request",
+            "inputs.yaml must hold a top-level request mapping.",
+        )
+    return validate_run_request(data["request"])