rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/project/process/model.py

@@ -0,0 +1,193 @@
+"""Versioned technology-profile semantics and capability gates.
+
+A TechProfile pins the exact technology semantics process
+operations consume (name, version, source hash, units, grid,
+contact/connectivity notes, capability map). Nothing is inferred
+from display names: a missing mapping, grid, rule, or tool
+yields a named unsupported/incomplete verdict and authored
+geometry stays intact. Binary-gated backends (opensta,
+librelane, klayout, docker) probe loudly and report
+BLOCKED-needs-host instead of faking a result.
+"""
+
+import copy
+import shutil
+
+GATED_TOOLS = ("opensta", "librelane", "klayout", "docker")
+CAPABILITIES = (
+    "drc", "extraction", "export_gds", "export_oasis",
+    "connectivity",
+)
+
+
+class TechProfile:
+    """Versioned technology semantics for one process.
+
+    Args:
+        name: Technology profile name (a PDK or another
+            explicitly supported technology).
+        version: Profile version string.
+        source_hash: Hash of the profile source the pin came
+            from (deck hash, file sha, or manifest hash).
+        units: Coordinate units label.
+        grid: Manufacturing grid pitch in storage units.
+        deck: Backend deck/tool version label, if any.
+        contacts: Contact/residue and overlap notes.
+        connectivity: Connectivity relation notes.
+        capabilities: Mapping of capability name to state
+            (supported, missing, or incompatible).
+    """
+
+    def __init__(self, name, version, source_hash, units="nm",
+                 grid=1, deck=None, contacts=None,
+                 connectivity=None, capabilities=None):
+        self.name = name
+        self.version = version
+        self.source_hash = source_hash
+        self.units = units
+        self.grid = grid
+        self.deck = deck
+        self.contacts = copy.deepcopy(contacts or {})
+        self.connectivity = copy.deepcopy(connectivity or {})
+        self.capabilities = dict(capabilities or {})
+
+    def pin(self):
+        """Return the I28 ingredient pin for this profile.
+
+        Returns:
+            Mapping with name, version, source hash, deck,
+            units, and grid.
+        """
+        return {
+            "deck": self.deck,
+            "grid": self.grid,
+            "name": self.name,
+            "source_hash": self.source_hash,
+            "units": self.units,
+            "version": self.version,
+        }
+
+    def label(self):
+        """Return the short name@version label.
+
+        Returns:
+            Profile label string.
+        """
+        return f"{self.name}@{self.version}"
+
+
+def bind_layer(profile, layer, purpose, gds=None,
+               capability="supported"):
+    """Bind one project layer to process destinations.
+
+    Args:
+        profile: TechProfile the binding resolves under.
+        layer: Stable project layer lid.
+        purpose: Process purpose (drawing, contact, marker).
+        gds: Optional (layer, datatype) destination tuple.
+        capability: Binding state (supported, missing, or
+            incompatible).
+
+    Returns:
+        Binding mapping with source pin, destination,
+            purpose, and capability state.
+
+    Raises:
+        ValueError: For an unknown capability state.
+    """
+    if capability not in ("supported", "missing",
+                          "incompatible"):
+        raise ValueError(
+            f"Unknown capability state: {capability!r}.")
+    return {
+        "capability": capability,
+        "destination": gds,
+        "layer": layer,
+        "profile": profile.label(),
+        "purpose": purpose,
+        "source_hash": profile.source_hash,
+    }
+
+
+def check_capability(profile, operation, bindings):
+    """Check whether one operation may run under a profile.
+
+    Args:
+        profile: TechProfile the operation would consume.
+        operation: Operation name (drc, extraction,
+            export_gds, export_oasis, connectivity).
+        bindings: Layer bindings the design needs (empty
+            means the design needs no mapped layer).
+
+    Returns:
+        Verdict with state supported, unsupported, or
+            incomplete, naming the exact profile/deck pin.
+            Unsupported results never imply a valid run.
+    """
+    state = profile.capabilities.get(operation, "missing")
+    if state == "supported" and bindings:
+        missing = [binding for binding in bindings if
+                   binding.get("capability") != "supported"]
+        if missing:
+            return {
+                "operation": operation,
+                "profile": profile.label(),
+                "reason": (
+                    f"{len(missing)} layer binding(s) are not "
+                    "supported; authored geometry is intact."
+                ),
+                "state": "incomplete",
+            }
+        return {
+            "operation": operation,
+            "profile": profile.label(),
+            "reason": "Profile and bindings cover the run.",
+            "state": "supported",
+        }
+    if state == "supported":
+        return {
+            "operation": operation,
+            "profile": profile.label(),
+            "reason": "Profile covers the run.",
+            "state": "supported",
+        }
+    return {
+        "operation": operation,
+        "profile": profile.label(),
+        "reason": (
+            f"Profile {profile.label()} reports {operation} "
+            f"as {state}; deck {profile.deck}."
+        ),
+        "state": "unsupported",
+    }
+
+
+def probe_tool(tool):
+    """Probe one binary-gated backend without faking results.
+
+    Args:
+        tool: Tool binary name (opensta, librelane, klayout,
+            docker, or another backend binary).
+
+    Returns:
+        Probe mapping with tool, state (available or
+            BLOCKED-needs-host), path, and reason. Absent
+            binaries report BLOCKED-needs-host loudly.
+    """
+    path = shutil.which(tool)
+    if path is None:
+        return {
+            "path": None,
+            "reason": (
+                f"{tool} is not on PATH in this environment; "
+                "the operation is BLOCKED-needs-host."
+            ),
+            "state": "BLOCKED-needs-host",
+            "tool": tool,
+        }
+    return {
+        "path": path,
+        "reason": f"{tool} resolved at {path}.",
+        "state": "available",
+        "tool": tool,
+    }

rocket_engine/project/process/recipes.py

@@ -0,0 +1,121 @@
+"""Declarative derived-geometry recipes with loud failure modes.
+
+Recipes describe deterministic GDS/OASIS derivation steps
+(copy, offset, size, boolean and/or/not) pinned to a profile
+revision. Round-trip validation replays the recipe against a
+reference layout; unsupported transformations fail loudly
+instead of emitting a silent partial output.
+"""
+
+import copy
+
+SUPPORTED_OPS = ("copy", "offset", "size", "and", "or", "not")
+
+
+class DerivedRecipe:
+    """Named deterministic derivation pinned to a profile.
+
+    Args:
+        name: Recipe name.
+        profile: Profile pin label (name@version).
+        steps: List of step mappings, each with an op from
+            SUPPORTED_OPS plus op arguments.
+    """
+
+    def __init__(self, name, profile, steps):
+        self.name = name
+        self.profile = profile
+        self.steps = copy.deepcopy(list(steps))
+
+    def to_dict(self):
+        """Serialize the recipe for revision pinning.
+
+        Returns:
+            Mapping with name, profile, and steps.
+        """
+        return {
+            "name": self.name,
+            "profile": self.profile,
+            "steps": copy.deepcopy(self.steps),
+        }
+
+
+def _apply_step(shape, step):
+    """Apply one derivation step to one shape copy.
+
+    Args:
+        shape: Shape mapping with shape_type and data.
+        step: Step mapping with an op name.
+
+    Returns:
+        Derived shape mapping.
+
+    Raises:
+        ValueError: unsupported_transformation for an op
+            outside SUPPORTED_OPS.
+    """
+    op = step.get("op")
+    if op not in SUPPORTED_OPS:
+        raise ValueError(
+            f"unsupported_transformation: {op!r} is not a "
+            f"derivable recipe op for {shape.get('shape_type')}.")
+    out = copy.deepcopy(shape)
+    data = out["data"]
+    if op == "copy":
+        return out
+    if op == "offset":
+        dx, dy = step.get("dx", 0), step.get("dy", 0)
+        if out["shape_type"] in ("rect", "label"):
+            data["x"] += dx
+            data["y"] += dy
+        else:
+            data["points"] = [[px + dx, py + dy] for px, py in
+                              data["points"]]
+        return out
+    if op == "size":
+        delta = step.get("delta", 0)
+        if out["shape_type"] == "rect":
+            data["x"] -= delta
+            data["y"] -= delta
+            data["w"] += 2 * delta
+            data["h"] += 2 * delta
+        return out
+    out["derived_boolean"] = op
+    return out
+
+
+def apply_recipe(shapes, recipe):
+    """Derive output geometry deterministically.
+
+    Args:
+        shapes: List of input shape mappings.
+        recipe: DerivedRecipe to apply in step order.
+
+    Returns:
+        New list with derived shape mappings; inputs are
+            never mutated.
+
+    Raises:
+        ValueError: unsupported_transformation for any step
+            outside SUPPORTED_OPS.
+    """
+    current = copy.deepcopy(list(shapes))
+    for step in recipe.steps:
+        current = [_apply_step(shape, step) for shape in
+                   current]
+    return current
+
+
+def round_trip_ok(reference, recipe):
+    """Validate a recipe replays deterministically.
+
+    Args:
+        reference: Reference shape list to replay.
+        recipe: DerivedRecipe to validate.
+
+    Returns:
+        True when two applications agree byte-for-byte.
+    """
+    first = apply_recipe(reference, recipe)
+    second = apply_recipe(reference, recipe)
+    return first == second

rocket_engine/project/schematic/__init__.py

@@ -0,0 +1 @@
+"""Schematic package marker: sheets, instances, hierarchy authoring."""

rocket_engine/project/schematic/hierarchy.py

@@ -0,0 +1,312 @@
+"""Hierarchy: parent-sheet to child-sheet bindings through block instances."""
+
+from ...interfaces.errors import ContractError
+
+#: Component name hierarchy bindings carry on their entity.
+HIERARCHY_COMPONENT = "Hierarchy"
+
+
+def validate_hierarchy(binding):
+    """Validate a Hierarchy binding mapping at edit time.
+
+    Args:
+        binding: Binding mapping with parent_sheet, child_sheet,
+            instance, and port_map keys.
+
+    Returns:
+        Normalized binding copy.
+
+    Raises:
+        ContractError: invalid_hierarchy for any shape violation.
+    """
+    if not isinstance(binding, dict):
+        raise ContractError(
+            "invalid_hierarchy",
+            f"Hierarchy must be a mapping, got {binding!r}.",
+        )
+    for key in binding:
+        if key not in ("parent_sheet", "child_sheet", "instance",
+                       "port_map"):
+            raise ContractError(
+                "invalid_hierarchy", f"Unknown Hierarchy key: {key}."
+            )
+    parent = binding.get("parent_sheet")
+    child = binding.get("child_sheet")
+    instance = binding.get("instance")
+    for label, value in (("parent_sheet", parent),
+                         ("child_sheet", child),
+                         ("instance", instance)):
+        if not isinstance(value, str) or not value:
+            raise ContractError(
+                "invalid_hierarchy",
+                f"Hierarchy {label} must be an entity id.",
+            )
+    if parent == child:
+        raise ContractError(
+            "invalid_hierarchy",
+            "Hierarchy parent and child must differ.",
+        )
+    port_map = binding.get("port_map", [])
+    if not isinstance(port_map, list):
+        raise ContractError(
+            "invalid_hierarchy", "Hierarchy port_map must be a list."
+        )
+    clean_map = []
+    seen = set()
+    for entry in port_map:
+        if (
+            not isinstance(entry, dict)
+            or set(entry) != {"parent", "child"}
+            or not entry["parent"]
+            or not isinstance(entry["parent"], str)
+            or not entry["child"]
+            or not isinstance(entry["child"], str)
+        ):
+            raise ContractError(
+                "invalid_hierarchy",
+                "port_map entries need parent + child text.",
+            )
+        if entry["child"] in seen:
+            raise ContractError(
+                "invalid_hierarchy",
+                f"Child port {entry['child']!r} maps more than once.",
+            )
+        seen.add(entry["child"])
+        clean_map.append(
+            {"parent": entry["parent"], "child": entry["child"]}
+        )
+    return {
+        "parent_sheet": parent, "child_sheet": child,
+        "instance": instance, "port_map": clean_map,
+    }
+
+
+def _read_binding(store, binding_id):
+    """Return the normalized binding for one entity id."""
+    try:
+        raw = store.get_component(binding_id, HIERARCHY_COMPONENT)
+    except LookupError:
+        raise ContractError(
+            "unknown_binding",
+            f"No such hierarchy binding: {binding_id!r}.",
+        ) from None
+    value = validate_hierarchy(raw)
+    value["id"] = binding_id
+    return value
+
+
+def _check_sheet(store, sheet_id):
+    """Fail loudly when a sheet entity is missing."""
+    try:
+        store.get_component(sheet_id, "Sheet")
+    except LookupError:
+        raise ContractError(
+            "unknown_sheet", f"No such sheet entity: {sheet_id!r}."
+        ) from None
+
+
+def _check_instance(store, instance_id):
+    """Fail loudly when an instance entity is missing."""
+    try:
+        store.get_component(instance_id, "Instance")
+    except LookupError:
+        raise ContractError(
+            "unknown_instance",
+            f"No such instance entity: {instance_id!r}.",
+        ) from None
+
+
+def _all_bindings(store):
+    """List every binding mapping, id-sorted."""
+    found = []
+    for entity in store.entities_with(HIERARCHY_COMPONENT):
+        try:
+            found.append(_read_binding(store, entity))
+        except ContractError:
+            continue
+    found.sort(key=lambda item: item["id"])
+    return found
+
+
+def bind_block(store, actor, parent_sheet, child_sheet, instance):
+    """Bind a child sheet under a parent through a block instance.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        actor: Attribution recorded on the revision and events.
+        parent_sheet: Parent sheet entity id.
+        child_sheet: Child sheet entity id.
+        instance: Block instance entity id on the parent sheet.
+
+    Returns:
+        Receipt with op, actor, revision, binding id, and events.
+
+    Raises:
+        ContractError: unknown_sheet for a missing sheet,
+            unknown_instance for a missing instance,
+            binding_exists for a duplicate binding,
+            invalid_hierarchy for a self-binding.
+    """
+    value = validate_hierarchy({
+        "parent_sheet": parent_sheet, "child_sheet": child_sheet,
+        "instance": instance, "port_map": [],
+    })
+    _check_sheet(store, parent_sheet)
+    _check_sheet(store, child_sheet)
+    _check_instance(store, instance)
+    for other in _all_bindings(store):
+        if (
+            other["parent_sheet"] == parent_sheet
+            and other["child_sheet"] == child_sheet
+            and other["instance"] == instance
+        ):
+            raise ContractError(
+                "binding_exists",
+                f"Sheet {child_sheet!r} is already bound under "
+                f"{parent_sheet!r} through {instance!r}.",
+            )
+    made = store.create_entity(actor, f"bind_block {child_sheet}")
+    store.attach_component(
+        actor, made["id"], HIERARCHY_COMPONENT, value,
+        f"bind_block {child_sheet}",
+    )
+    return {
+        "op": "bind_block", "actor": actor,
+        "revision": made["revision"], "binding": made["id"],
+        "events": [
+            {"event": "entity_created", "entity": made["id"]},
+            {"event": "component_changed", "entity": made["id"],
+             "component": HIERARCHY_COMPONENT},
+        ],
+    }
+
+
+def set_port_map(store, actor, binding_id, port_map):
+    """Replace one binding's parent-to-child port map.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        actor: Attribution recorded on the revision and events.
+        binding_id: Binding entity id to update.
+        port_map: New [{parent, child}] port mappings.
+
+    Returns:
+        Receipt with op, actor, revision, binding id, and
+            the new port map.
+
+    Raises:
+        ContractError: unknown_binding for a missing binding,
+            invalid_hierarchy for a malformed map.
+    """
+    value = _read_binding(store, binding_id)
+    clean = validate_hierarchy({
+        "parent_sheet": value["parent_sheet"],
+        "child_sheet": value["child_sheet"],
+        "instance": value["instance"], "port_map": port_map,
+    })
+    changed = store.set_component(
+        actor, binding_id, HIERARCHY_COMPONENT, clean,
+        f"set_port_map {binding_id}",
+    )
+    return {
+        "op": "set_port_map", "actor": actor,
+        "revision": changed["revision"], "binding": binding_id,
+        "port_map": clean["port_map"], "events": [],
+    }
+
+
+def unbind_block(store, actor, binding_id):
+    """Delete one hierarchy binding.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        actor: Attribution recorded on the revision and events.
+        binding_id: Binding entity id to delete.
+
+    Returns:
+        Receipt with op, actor, revision, and binding id.
+
+    Raises:
+        ContractError: unknown_binding for a missing binding.
+    """
+    _read_binding(store, binding_id)
+    done = store.delete_entity(
+        actor, binding_id, f"unbind_block {binding_id}"
+    )
+    return {
+        "op": "unbind_block", "actor": actor,
+        "revision": done["revision"], "binding": binding_id,
+        "events": [{"event": "entity_deleted", "entity": binding_id}],
+    }
+
+
+def children_of(store, parent_sheet):
+    """List child sheet ids bound under one parent, id-sorted.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        parent_sheet: Parent sheet entity id.
+
+    Returns:
+        Child sheet entity ids, id-sorted.
+    """
+    return sorted(
+        item["child_sheet"] for item in _all_bindings(store)
+        if item["parent_sheet"] == parent_sheet
+    )
+
+
+def parent_of(store, child_sheet):
+    """List parent sheet ids binding one child, id-sorted.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        child_sheet: Child sheet entity id.
+
+    Returns:
+        Parent sheet entity ids, id-sorted.
+    """
+    return sorted(
+        item["parent_sheet"] for item in _all_bindings(store)
+        if item["child_sheet"] == child_sheet
+    )
+
+
+def hierarchy_tree(store, root_sheet):
+    """Render the hierarchy subtree rooted at one sheet.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        root_sheet: Root sheet entity id.
+
+    Returns:
+        Nested mapping with sheet plus children subtrees.
+    """
+    return {
+        "sheet": root_sheet,
+        "children": [
+            hierarchy_tree(store, child)
+            for child in children_of(store, root_sheet)
+        ],
+    }
+
+
+def sheet_path(store, sheet):
+    """Return the root-to-sheet chain through first parents.
+
+    Args:
+        store: Entity store serving the ENGINE-ECS seam.
+        sheet: Sheet entity id to locate.
+
+    Returns:
+        Sheet ids from the root down to the sheet itself.
+    """
+    chain = [sheet]
+    seen = {sheet}
+    while True:
+        parents = parent_of(store, chain[0])
+        if not parents or parents[0] in seen:
+            break
+        chain.insert(0, parents[0])
+        seen.add(parents[0])
+    return chain