rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/execution/routing/ports.py

@@ -0,0 +1,102 @@
+"""Port handler seam: position-checked apply plus ack, shared by ports.
+
+Every port handler honors position-check-then-apply: one
+ledger position applies once per port, and every delivery —
+first or duplicate — advances the ack. Handlers bind to the
+port's own bus guard, so the check cannot drift per port.
+"""
+
+from ..ports import PositionGuard
+
+
+class PortHandler:
+    """One port's apply path: guard, apply, ack.
+
+    Args:
+        bus: PortBus the port is attached to.
+        port: Attached port name this handler serves.
+        guard: PositionGuard to check positions against; the
+            port's bound bus guard when omitted.
+    """
+
+    def __init__(self, bus, port, guard=None):
+        """Bind one handler to one port's guard and ack flow.
+
+        Args:
+            bus: PortBus the port is attached to.
+            port: Attached port name this handler serves.
+            guard: PositionGuard to check positions against;
+                the port's bound bus guard when omitted.
+
+        Returns:
+            Bound handler.
+        """
+        self._bus = bus
+        self._port = port
+        self._guard = (guard if guard is not None
+                       else bus.guard_for(port))
+
+    @property
+    def port(self):
+        """Port name this handler serves.
+
+        Returns:
+            Attached port name.
+        """
+        return self._port
+
+    @property
+    def guard(self):
+        """Position guard this handler checks against.
+
+        Returns:
+            The bound PositionGuard.
+        """
+        return self._guard
+
+    def handle(self, event, apply):
+        """Apply one event once, then ack its position.
+
+        Args:
+            event: Ledger event mapping with an integer seq.
+            apply: Callable taking the event, run only when
+                its position is new for the port.
+
+        Returns:
+            (applied, result) pair: applied True plus the
+                apply result on first application, (False,
+                None) on a duplicate position. Either way the
+                position is acked.
+
+        Raises:
+            ExecutionError: invalid_command for an event
+                without an integer seq, unknown_port for a
+                detached port.
+            Exception: Whatever apply raises propagates, and
+                the position stays unapplied for redelivery.
+        """
+        seq = event.get("seq") if isinstance(event, dict) else None
+        applied, result = self._guard.apply_once(
+            self._port, seq, apply, event)
+        self._bus.ack(self._port, seq)
+        return applied, result
+
+    def drain(self, apply, limit=None):
+        """Drain the port backlog through one apply callable.
+
+        Args:
+            apply: Callable taking one event mapping, run
+                once per ledger position.
+            limit: Maximum events to deliver; the whole
+                backlog when omitted.
+
+        Returns:
+            Drain record with port, delivered and applied
+                counts, the acked position, and handler
+                error messages.
+
+        Raises:
+            ExecutionError: unknown_port for a detached port.
+        """
+        return self._bus.drain(self._port, apply,
+                               limit=limit, guarded=True)

rocket_engine/execution/routing/tools.py

@@ -0,0 +1,346 @@
+"""Worker-side console op recorder in prelude shape."""
+
+from .calls import tool_call
+
+
+class ConsoleTools:
+    """Worker-side console namespace: tier-2 verbs as op records.
+
+    The recording twin of ConsoleNamespace: one explicit wrapper
+    per tier-2 verb plus a generic fallback for every other op,
+    each appending a canonical op-call record in the prelude shape
+    (operation plus verbatim keyword arguments) and answering the
+    recorded receipt. Recording never validates semantics and
+    never executes — the host replays each record through shared
+    dispatch after the worker exits, where admission judges it.
+
+    Args:
+        sink: Optional callable receiving every recorded entry
+            besides the calls list (a JSONL writer serves).
+    """
+
+    def __init__(self, sink=None):
+        self.calls = []
+        self._sink = sink
+        self._index = 0
+
+    def _record(self, operation, args, kwargs):
+        """Append one op record; positional args fail prelude-loud."""
+        if args:
+            raise TypeError(
+                "op calls take keyword arguments only: %s." % operation
+            )
+        entry = tool_call(operation, kwargs)
+        self.calls.append(entry)
+        if self._sink is not None:
+            self._sink(entry)
+        self._index += 1
+        return {"state": "recorded", "operation": operation,
+                "index": self._index}
+
+    def __getattr__(self, operation):
+        """Record one call to any op by name (generic fallback)."""
+        def call(*args, **kwargs):
+            return self._record(operation, args, kwargs)
+
+        return call
+
+    def write_doc(self, *args, **kwargs):
+        """Record one write_doc op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("write_doc", args, kwargs)
+
+    def delete_doc(self, *args, **kwargs):
+        """Record one delete_doc op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("delete_doc", args, kwargs)
+
+    def apply_mutations(self, *args, **kwargs):
+        """Record one apply_mutations op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("apply_mutations", args, kwargs)
+
+    def place_cell(self, *args, **kwargs):
+        """Record one place_cell op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("place_cell", args, kwargs)
+
+    def create_entity(self, *args, **kwargs):
+        """Record one create_entity op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("create_entity", args, kwargs)
+
+    def set_component(self, *args, **kwargs):
+        """Record one set_component op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("set_component", args, kwargs)
+
+    def attach_component(self, *args, **kwargs):
+        """Record one attach_component op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("attach_component", args, kwargs)
+
+    def detach_component(self, *args, **kwargs):
+        """Record one detach_component op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("detach_component", args, kwargs)
+
+    def delete_entity(self, *args, **kwargs):
+        """Record one delete_entity op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("delete_entity", args, kwargs)
+
+    def place_wire(self, *args, **kwargs):
+        """Record one place_wire op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("place_wire", args, kwargs)
+
+    def place_junction(self, *args, **kwargs):
+        """Record one place_junction op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("place_junction", args, kwargs)
+
+    def connect_endpoint(self, *args, **kwargs):
+        """Record one connect_endpoint op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("connect_endpoint", args, kwargs)
+
+    def move_wire(self, *args, **kwargs):
+        """Record one move_wire op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("move_wire", args, kwargs)
+
+    def split_wire(self, *args, **kwargs):
+        """Record one split_wire op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("split_wire", args, kwargs)
+
+    def delete_wire(self, *args, **kwargs):
+        """Record one delete_wire op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("delete_wire", args, kwargs)
+
+    def delete_junction(self, *args, **kwargs):
+        """Record one delete_junction op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("delete_junction", args, kwargs)
+
+    def materialize_nets(self, *args, **kwargs):
+        """Record one materialize_nets op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("materialize_nets", args, kwargs)
+
+    def create_project(self, *args, **kwargs):
+        """Record one create_project op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("create_project", args, kwargs)
+
+    def rewind(self, *args, **kwargs):
+        """Record one rewind op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("rewind", args, kwargs)
+
+    def write_settings(self, *args, **kwargs):
+        """Record one write_settings op call.
+
+        Args:
+            args: Rejected positionally, prelude parity.
+            kwargs: Keyword op arguments recorded verbatim.
+
+        Returns:
+            Recorded receipt with state, operation, and index.
+
+        Raises:
+            TypeError: When positional args arrive (keyword-only).
+        """
+        return self._record("write_settings", args, kwargs)