rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/project/ip/verbs.py

@@ -0,0 +1,123 @@
+"""IP editor verbs: per-PDK registry mutations behind ProjectService.
+
+First REFACTOR-SERVICE slice: the ip_register/ip_instantiate/
+ip_promote verbs live here as _IpMixin so src/project/service.py
+stays under the architecture line limit. ProjectService binds
+this mixin, so the verbs keep their bound path
+(rocket_engine.project.service.ProjectService.<verb>); the API
+contract generator reads the contract docstrings from this
+module (see scripts/api_spec.py _SERVICE_DOC_HOME).
+"""
+
+from ...ops import editors as _editors
+
+from . import lifecycle as _ip
+
+
+class _IpMixin:
+    """IP registry verbs (per-PDK invariant, RULING-01)."""
+
+    def ip_register(self, pdk, name, version, symbol, cell,
+                    request_id, command_text, pin_map=None,
+                    scope="pdk", reason="",
+                    expected_revision=None):
+        """Register one prebuilt IP block revision under its PDK.
+
+        Args:
+            pdk: Owning PDK id (the per-PDK invariant key).
+            name: Block name within the PDK registry.
+            version: Revision label ("" forbidden).
+            symbol: Linked schematic symbol reference.
+            cell: Linked footprint cell reference.
+            request_id: Client envelope id for idempotent replay.
+            command_text: YAML command text for identity comparison.
+            pin_map: Explicit [{symPin, cellPin}] entries.
+            scope: "pdk" (default) or "shared" with a reason.
+            reason: Recorded justification for shared scope.
+            expected_revision: Revision the writer read.
+
+        Returns:
+            Mutation mapping with receipt, events, and cursor.
+
+        Raises:
+            ProjectError: request_conflict, revision_conflict,
+                invalid_pdk, ip_exists, invalid_ip, invalid_scope.
+        """
+        return _editors.editor_mutation(self,
+            "ip_register", request_id, command_text,
+            expected_revision,
+            lambda store, _rid, _rt, _live: _ip.ip_register(
+                store, self._actor, pdk, name, version, symbol,
+                cell, pin_map=pin_map or [], scope=scope,
+                reason=reason),
+            lambda receipt: f"registered IP {pdk}/{name}@{version}",
+        )
+
+    def ip_instantiate(self, pdk, name, sheet, x, y,
+                       request_id, command_text, version=None,
+                       rotation=0, mirror=False, properties=None,
+                       expected_revision=None):
+        """Place one registered IP block with linkage intact.
+
+        Args:
+            pdk: Consuming PDK id (must own the block unless the
+                block opted into shared scope).
+            name: Block name within the PDK registry.
+            sheet: Sheet entity id hosting the instance.
+            x: X position in schematic units.
+            y: Y position in schematic units.
+            request_id: Client envelope id for idempotent replay.
+            command_text: YAML command text for identity comparison.
+            version: Revision label, or None for the latest.
+            rotation: Rotation in degrees (0/90/180/270).
+            mirror: Mirror flag.
+            properties: Text-to-text instance properties.
+            expected_revision: Revision the writer read.
+
+        Returns:
+            Mutation mapping with receipt, events, and cursor.
+
+        Raises:
+            ProjectError: request_conflict, revision_conflict,
+                unknown_ip, pdk_mismatch, unknown_sheet,
+                invalid_instance.
+        """
+        return _editors.editor_mutation(self,
+            "ip_instantiate", request_id, command_text,
+            expected_revision,
+            lambda store, _rid, _rt, _live: _ip.ip_instantiate(
+                store, self._actor, pdk, name, sheet, x, y,
+                version=version, rotation=rotation, mirror=mirror,
+                properties=properties),
+            lambda receipt: (
+                f"instantiated IP {pdk}/{name}"
+                f"@{receipt.get('version')}"),
+        )
+
+    def ip_promote(self, pdk, name, version,
+                   request_id, command_text,
+                   expected_revision=None):
+        """Promote one block version as the registry's recommended one.
+
+        Args:
+            pdk: Owning PDK id scoping the registry.
+            name: Block name within the PDK registry.
+            version: Revision label to promote.
+            request_id: Client envelope id for idempotent replay.
+            command_text: YAML command text for identity comparison.
+            expected_revision: Revision the writer read.
+
+        Returns:
+            Mutation mapping with receipt, events, and cursor.
+
+        Raises:
+            ProjectError: request_conflict, revision_conflict,
+                unknown_ip, invalid_pdk.
+        """
+        return _editors.editor_mutation(self,
+            "ip_promote", request_id, command_text,
+            expected_revision,
+            lambda store, _rid, _rt, _live: _ip.ip_promote(
+                store, self._actor, pdk, name, version),
+            lambda receipt: f"promoted IP {pdk}/{name}@{version}",
+        )

rocket_engine/project/layers/__init__.py

@@ -0,0 +1,6 @@
+"""Editable project layer catalog bound to a technology profile."""
+
+from .bindings import bind_layers
+from .presets import apply_preset, builtin_presets
+
+__all__ = ["bind_layers", "apply_preset", "builtin_presets"]

rocket_engine/project/layers/bindings.py

@@ -0,0 +1,115 @@
+"""Technology-profile bindings with explicit capability states.
+
+Bindings map project layer identities to process purposes and
+report each mapping as supported, missing, or incompatible. A
+missing binding never reinterprets geometry: drawing and saving
+keep working and only process operations report the gap.
+"""
+
+import copy
+
+STATES = ("supported", "missing", "incompatible")
+
+
+def bind_layers(catalog, profile_layers, source="profile",
+                version="unknown"):
+    """Bind catalog layers against a profile vocabulary.
+
+    Args:
+        catalog: LayerCatalog to bind.
+        profile_layers: Mapping of profile name to layer-name
+            lists, or a plain list of known layer names.
+        source: Provenance label for the profile source.
+        version: Profile version pinned into the report.
+
+    Returns:
+        Binding report with profile pin, catalog revision,
+            and one entry per layer (state, purpose, source).
+    """
+    if isinstance(profile_layers, dict):
+        profile = catalog.profile or {}
+        known = profile_layers.get(profile.get("name", ""), [])
+    else:
+        known = list(profile_layers)
+    entries = []
+    for layer in catalog.list_layers():
+        if layer["name"] in known:
+            state = "supported"
+        elif layer["name"].startswith("custom"):
+            state = "missing"
+        else:
+            state = "missing"
+        entries.append({
+            "capability": state,
+            "layer": layer["lid"],
+            "name": layer["name"],
+            "purpose": layer["purpose"],
+            "source": source,
+            "state": state,
+            "version": version,
+        })
+    profile = catalog.profile or {}
+    return {
+        "catalog_revision": catalog.revision,
+        "entries": entries,
+        "profile": profile.get("name", "unresolved"),
+        "profile_version": profile.get("version", version),
+    }
+
+
+def check_operation(report, layer_lid, operation):
+    """Check whether one process operation may consume a layer.
+
+    Args:
+        report: Binding report from bind_layers.
+        layer_lid: Stable layer id the operation needs.
+        operation: Process operation name (export_gds, drc,
+            extraction, or a recipe step).
+
+    Returns:
+        Verdict mapping with state (supported, unsupported,
+            or incomplete), layer, operation, and reason. Draw
+        and save paths ignore this verdict; only the named
+        process operation is gated by it.
+
+    Raises:
+        ValueError: For a layer with no binding entry.
+    """
+    for entry in report["entries"]:
+        if entry["layer"] == layer_lid:
+            if entry["state"] == "supported":
+                return {
+                    "layer": layer_lid,
+                    "operation": operation,
+                    "reason": "Binding covers the operation.",
+                    "state": "supported",
+                }
+            return {
+                "layer": layer_lid,
+                "operation": operation,
+                "reason": (
+                    f"No {operation} mapping for layer "
+                    f"{entry['name']!r}; geometry is intact."
+                ),
+                "state": "unsupported",
+            }
+    raise ValueError(f"No binding entry for layer: {layer_lid!r}.")
+
+
+def binding_for(report, layer_lid):
+    """Return one layer entry from a binding report.
+
+    Args:
+        report: Binding report from bind_layers.
+        layer_lid: Stable layer id to look up.
+
+    Returns:
+        Deep copy of the binding entry.
+
+    Raises:
+        ValueError: For a layer with no binding entry.
+    """
+    for entry in report["entries"]:
+        if entry["layer"] == layer_lid:
+            return copy.deepcopy(entry)
+    raise ValueError(f"No binding entry for layer: {layer_lid!r}.")

rocket_engine/project/layers/catalog.py

@@ -0,0 +1,228 @@
+"""Editable project layer catalog with stable identities.
+
+Layers carry identity (lid) separate from display (name, color,
+visibility): renames, saves, and reloads keep the lid, so saved
+geometry addressed by lid is never reinterpreted when a profile
+is missing or changed.
+"""
+
+import copy
+import itertools
+
+_COUNTER = itertools.count(1)
+
+
+def _mint_lid(existing):
+    """Mint one stable layer id.
+
+    Args:
+        existing: Lids already in use.
+
+    Returns:
+        Fresh lid string not present in existing.
+    """
+    while True:
+        candidate = f"lyr-{next(_COUNTER):04d}"
+        if candidate not in existing:
+            return candidate
+
+
+class LayerCatalog:
+    """Editable layer vocabulary for one project.
+
+    Args:
+        profile: Resolved technology profile mapping (name,
+            version) or None when no profile is selected.
+        revision: Starting catalog revision for a fresh
+            catalog.
+    """
+
+    def __init__(self, profile=None, revision=1):
+        self._profile = copy.deepcopy(profile)
+        self._revision = revision
+        self._layers = {}
+
+    @property
+    def setup_visible(self):
+        """Whether missing-profile setup must be shown.
+
+        Returns:
+            True when no technology profile is resolved.
+        """
+        return self._profile is None
+
+    @property
+    def revision(self):
+        """Current catalog revision.
+
+        Returns:
+            Integer revision bumped by every mutation.
+        """
+        return self._revision
+
+    @property
+    def profile(self):
+        """Resolved technology profile, if any.
+
+        Returns:
+            Deep copy of the profile mapping or None.
+        """
+        return copy.deepcopy(self._profile)
+
+    def add_layer(self, name, purpose="drawing", color="#ffffff",
+                  order=0, visible=True, aliases=()):
+        """Add one project layer with a stable identity.
+
+        Args:
+            name: Display name for the layer.
+            purpose: Process purpose label (display only;
+                semantics come from bindings).
+            color: Display color for editors.
+            order: Stack order for editors.
+            visible: Display visibility flag.
+            aliases: Extra names resolving to this layer.
+
+        Returns:
+            Deep copy of the created layer record.
+
+        Raises:
+            ValueError: If the name is empty or already used.
+        """
+        if not name:
+            raise ValueError("Layer name must not be empty.")
+        if any(layer["name"] == name for layer in
+               self._layers.values()):
+            raise ValueError(f"Duplicate layer name: {name!r}.")
+        lid = _mint_lid(set(self._layers))
+        self._layers[lid] = {
+            "aliases": list(aliases),
+            "color": color,
+            "lid": lid,
+            "name": name,
+            "order": order,
+            "purpose": purpose,
+            "visible": bool(visible),
+        }
+        self._revision += 1
+        return copy.deepcopy(self._layers[lid])
+
+    def rename_layer(self, lid, name):
+        """Rename one layer without changing its identity.
+
+        Args:
+            lid: Stable layer id to rename.
+            name: New display name.
+
+        Returns:
+            Deep copy of the renamed layer record.
+
+        Raises:
+            ValueError: For an unknown lid, an empty name, or
+                a name already in use.
+        """
+        if lid not in self._layers:
+            raise ValueError(f"Unknown layer: {lid!r}.")
+        if not name:
+            raise ValueError("Layer name must not be empty.")
+        self._layers[lid]["name"] = name
+        self._revision += 1
+        return copy.deepcopy(self._layers[lid])
+
+    def set_display(self, lid, color=None, visible=None, order=None):
+        """Change display-only flags of one layer.
+
+        Args:
+            lid: Stable layer id to update.
+            color: New display color, if given.
+            visible: New visibility flag, if given.
+            order: New stack order, if given.
+
+        Returns:
+            Deep copy of the updated layer record.
+
+        Raises:
+            ValueError: For an unknown lid.
+        """
+        if lid not in self._layers:
+            raise ValueError(f"Unknown layer: {lid!r}.")
+        layer = self._layers[lid]
+        if color is not None:
+            layer["color"] = color
+        if visible is not None:
+            layer["visible"] = bool(visible)
+        if order is not None:
+            layer["order"] = order
+        self._revision += 1
+        return copy.deepcopy(layer)
+
+    def get_layer(self, lid):
+        """Return one layer record by stable id.
+
+        Args:
+            lid: Stable layer id to read.
+
+        Returns:
+            Deep copy of the layer record.
+
+        Raises:
+            ValueError: For an unknown lid.
+        """
+        if lid not in self._layers:
+            raise ValueError(f"Unknown layer: {lid!r}.")
+        return copy.deepcopy(self._layers[lid])
+
+    def list_layers(self):
+        """List every layer ordered by stack order.
+
+        Returns:
+            List of deep-copied layer records.
+        """
+        return sorted(
+            (copy.deepcopy(layer) for layer in
+             self._layers.values()),
+            key=lambda layer: (layer["order"], layer["lid"]),
+        )
+
+    def attach_profile(self, profile):
+        """Resolve a technology profile without moving geometry.
+
+        Args:
+            profile: Technology profile mapping with at least
+                name and version.
+
+        Returns:
+            Deep copy of the attached profile.
+        """
+        self._profile = copy.deepcopy(profile)
+        self._revision += 1
+        return copy.deepcopy(self._profile)
+
+    def to_dict(self):
+        """Serialize the catalog including its revision pin.
+
+        Returns:
+            Plain mapping with profile, revision, and layers.
+        """
+        return {
+            "layers": self.list_layers(),
+            "profile": copy.deepcopy(self._profile),
+            "revision": self._revision,
+        }
+
+    @classmethod
+    def from_dict(cls, data):
+        """Rebuild a catalog from serialized state.
+
+        Args:
+            data: Mapping produced by to_dict.
+
+        Returns:
+            LayerCatalog with stable lids preserved.
+        """
+        catalog = cls(
+            profile=data.get("profile"),
+            revision=data.get("revision", 1),
+        )
+        for layer in data.get("layers", ()):
+            catalog._layers[layer["lid"]] = copy.deepcopy(layer)
+        return catalog

rocket_engine/project/layers/presets.py

@@ -0,0 +1,43 @@
+"""Built-in layer visibility presets (viewer aids, not semantics)."""
+
+BUILTIN_PRESETS = ("All", "None", "All-metal", "Top", "Bottom")
+
+
+def builtin_presets():
+    """List every built-in preset name.
+
+    Returns:
+        Tuple of preset names.
+    """
+    return BUILTIN_PRESETS
+
+
+def apply_preset(name, layer_names):
+    """Apply one built-in preset to a layer name list.
+
+    Args:
+        name: Preset name from builtin_presets.
+        layer_names: Available layer names to filter.
+
+    Returns:
+        Mapping with preset name and enabled layer names.
+
+    Raises:
+        ValueError: For an unknown preset name.
+    """
+    if name not in BUILTIN_PRESETS:
+        raise ValueError(f"Unknown preset: {name!r}.")
+    names = list(layer_names)
+    if name == "All":
+        enabled = names
+    elif name == "None":
+        enabled = []
+    elif name == "All-metal":
+        enabled = [layer for layer in names
+                   if "met" in layer.lower() or "metal" in
+                   layer.lower()]
+    elif name == "Top":
+        enabled = names[-1:] if names else []
+    else:
+        enabled = names[:1] if names else []
+    return {"enabled": enabled, "preset": name}

rocket_engine/project/ledger/__init__.py

@@ -0,0 +1 @@
+"""Project ledger internals behind ProjectService."""

rocket_engine/project/ledger/docs.py

@@ -0,0 +1,167 @@
+"""Document path resolution and byte access."""
+
+from ...interfaces.paths import join_contained
+from ..errors import ProjectError
+
+from .shared import _RESERVED_DOCS, _SNAPSHOTS_DIRNAME, _atomic_write_text
+
+class _DocMixin:
+    """Document byte access for ProjectService."""
+
+    def _doc_path(self, canonical):
+        """Resolve one canonical path under the project dir.
+
+        Args:
+            canonical: Canonical document path.
+
+        Returns:
+            Resolved absolute path inside the project dir.
+
+        Raises:
+            ProjectError: path_escape when containment fails.
+        """
+        try:
+            return join_contained(self._dir, canonical)
+        except Exception as exc:
+            code = getattr(exc, "code", None) or "path_escape"
+            raise ProjectError(code, str(exc)) from exc
+
+    def _read_doc_text(self, canonical, original):
+        """Read one document as text, or None when missing.
+
+        Args:
+            canonical: Canonical document path.
+            original: Caller-supplied path for error messages.
+
+        Returns:
+            Document text, or None when the document is absent.
+
+        Raises:
+            ProjectError: invalid_command when the path names a
+                directory; invalid_document when durable bytes are
+                not UTF-8 text.
+        """
+        if self._dir is None:
+            return self._docs.get(canonical)
+        target = self._doc_path(canonical)
+        if not target.exists():
+            return None
+        if target.is_dir():
+            raise ProjectError(
+                "invalid_command",
+                f"Document path is a directory: {original!r}.",
+            )
+        try:
+            return target.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            raise ProjectError(
+                "invalid_document",
+                f"Document is not UTF-8 text: {original!r} ({exc}).",
+            ) from exc
+        except OSError as exc:
+            raise ProjectError(
+                "invalid_ledger",
+                f"Cannot read document {original!r}: {exc}.",
+            ) from exc
+
+    def _write_doc_text(self, canonical, content, original):
+        """Write one document (parents created, atomic rename).
+
+        Args:
+            canonical: Canonical document path.
+            content: UTF-8 text to store.
+            original: Caller-supplied path for error messages.
+
+        Raises:
+            ProjectError: invalid_command when the path names a
+                directory; invalid_ledger when the durable write
+                fails.
+        """
+        if self._dir is None:
+            self._docs[canonical] = content
+            return
+        target = self._doc_path(canonical)
+        if target.is_dir():
+            raise ProjectError(
+                "invalid_command",
+                f"Document path is a directory: {original!r}.",
+            )
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise ProjectError(
+                "invalid_ledger",
+                f"Cannot create document dir for {original!r}: {exc}.",
+            ) from exc
+        try:
+            _atomic_write_text(target, content)
+        except OSError as exc:
+            raise ProjectError(
+                "invalid_ledger",
+                f"Cannot write document {original!r}: {exc}.",
+            ) from exc
+
+    def _delete_doc_path(self, canonical, original):
+        """Delete one existing document file.
+
+        Args:
+            canonical: Canonical document path.
+            original: Caller-supplied path for error messages.
+
+        Raises:
+            ProjectError: invalid_command when the path names a
+                directory; invalid_ledger when the delete fails.
+        """
+        if self._dir is None:
+            self._docs.pop(canonical, None)
+            return
+        target = self._doc_path(canonical)
+        if target.is_dir():
+            raise ProjectError(
+                "invalid_command",
+                f"Document path is a directory: {original!r}.",
+            )
+        try:
+            target.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError as exc:
+            raise ProjectError(
+                "invalid_ledger",
+                f"Cannot delete document {original!r}: {exc}.",
+            ) from exc
+
+    def _iter_doc_files(self):
+        """Yield (canonical path, byte size) for every document.
+
+        Returns:
+            Sorted (path, bytes) pairs, engine-owned entries
+            excluded.
+        """
+        if self._dir is None:
+            return sorted(
+                (path, len(text.encode("utf-8")))
+                for path, text in self._docs.items()
+            )
+        if not self._dir.is_dir():
+            return []
+        found = []
+        for target in sorted(self._dir.rglob("*")):
+            if not target.is_file():
+                continue
+            try:
+                rel = target.relative_to(self._dir).as_posix()
+            except ValueError:
+                continue
+            if (
+                rel in _RESERVED_DOCS
+                or rel.startswith("runs/")
+                or rel.startswith(_SNAPSHOTS_DIRNAME + "/")
+            ):
+                continue
+            try:
+                size = target.stat().st_size
+            except OSError:
+                continue
+            found.append((rel, size))
+        return sorted(found)