interlacing 0.11.0__py3-none-any.whl

interlacing/__init__.py

@@ -0,0 +1,50 @@
+"""interlacing: nodes, edges and methods, and an engine that runs the graphs they make.
+
+A node is anything that takes information in and gives information out: a model, a function, an external
+program, a device, a person, another graph. An edge carries information from one node to another under a
+written protocol. A method is a reusable way of joining nodes: a chain, a loop, a fan, a tree.
+
+Layers, bottom up (each imports only from below):
+
+1. base        Node, Port, Schema, Edge, Protocol, Envelope, Graph, GraphBuilder, Method
+2. engine      Engine, Result, Journal, Transport
+3. parts       nodes, protocols, methods, models: the ones that come with the package
+   blocks      a designed graph kept as a unit and used as often as needed: Block, seq, par
+4. spec        graphs written as data: dump, load, and the Catalog that says what data may reach
+5. runs, cli, serve   a run kept in a directory, the ``interlacing`` command that works on one, and the
+               same operations offered to an MCP client
+
+Public names are importable from the package root. Standard library only.
+"""
+
+__version__ = "0.11.0"
+
+_PUBLIC = {
+    # base
+    "Node": "base", "Port": "base", "Firing": "base", "Context": "base", "Schema": "base", "Edge": "base",
+    "Invalid": "base", "Protocol": "base", "Protocols": "base", "Delivery": "base", "Envelope": "base", "Ref": "base",
+    "Graph": "base", "GraphBuilder": "base", "GraphError": "base", "NodeError": "base", "Method": "base",
+    # engine
+    "Engine": "engine", "Result": "engine", "RunError": "engine", "OverBudget": "engine", "Journal": "engine", "Transport": "engine",
+    # parts
+    "FunctionNode": "nodes", "AgentNode": "nodes", "Tool": "nodes", "ProcessNode": "nodes", "SourceNode": "nodes",
+    "SinkNode": "nodes", "HumanNode": "nodes", "GraphNode": "nodes", "Desk": "nodes",
+    "Chain": "methods", "Loop": "methods", "Fan": "methods", "Tree": "methods", "Star": "methods",
+    "Governed": "methods", "Pool": "methods",
+    "Block": "blocks", "seq": "blocks", "par": "blocks",
+    "DEFAULT": "protocols", "standard": "protocols", "File": "protocols", "FileOf": "protocols",
+    "with_files": "protocols",
+    "Provider": "models", "FakeProvider": "models", "ChatResult": "models",
+    # graphs as data
+    "Catalog": "spec", "SpecError": "spec", "SpawnNode": "spec", "dump": "spec", "load": "spec",
+}
+
+
+def __getattr__(name):
+    if name in _PUBLIC:
+        import importlib
+        return getattr(importlib.import_module(f"{__name__}.{_PUBLIC[name]}"), name)
+    raise AttributeError(name)
+
+
+__all__ = ["__version__", *_PUBLIC]

interlacing/base/__init__.py

@@ -0,0 +1,25 @@
+"""The abstractions everything else is built on. No behaviour of any particular node, edge or method lives here.
+
+    Node, Port, Schema      what takes information in and gives it out, and what its ports carry
+    Edge, Protocol          a flow between two ports, and the rules of that flow
+    Envelope, Ref           the form in which information travels
+    Graph, GraphBuilder     nodes joined by edges, checked once, then read-only
+    Method                  a reusable way of joining nodes
+
+This package imports nothing else from ``interlacing``.
+"""
+from .canonical import canonical, digest
+from .edge import Edge, EdgeError, Endpoint
+from .envelope import Envelope, Ref
+from .graph import Graph, GraphBuilder, GraphError
+from .method import Method
+from .node import Context, Firing, Invalid, Node, NodeError
+from .port import Port, PortError
+from .protocol import Delivery, Protocol, ProtocolError, Protocols
+from .schema import ANY, Is, ListOf, Record, Schema, SchemaError, schema
+
+__all__ = [
+    "ANY", "Context", "Delivery", "Edge", "EdgeError", "Endpoint", "Envelope", "Firing", "Graph", "GraphBuilder",
+    "GraphError", "Invalid", "Is", "ListOf", "Method", "Node", "NodeError", "Port", "PortError", "Protocol", "ProtocolError",
+    "Protocols", "Record", "Ref", "Schema", "SchemaError", "canonical", "digest", "schema",
+]

interlacing/base/canonical.py

@@ -0,0 +1,14 @@
+"""One canonical text form of a definition, and its digest. Two equal definitions always hash the same."""
+from __future__ import annotations
+
+import hashlib
+import json
+
+
+def canonical(value) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False)
+
+
+def digest(value) -> str:
+    """SHA-256 of the canonical form. ``value`` must be plain data: dict, list, str, int, float, bool, None."""
+    return hashlib.sha256(canonical(value).encode("utf-8")).hexdigest()

interlacing/base/edge.py

@@ -0,0 +1,61 @@
+"""The edge: one flow of information from an output port to an input port, under a protocol."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import NamedTuple
+
+
+class EdgeError(ValueError):
+    pass
+
+
+class Endpoint(NamedTuple):
+    node: str
+    port: str
+
+    def __str__(self):
+        return f"{self.node}.{self.port}"
+
+    @classmethod
+    def of(cls, value) -> "Endpoint":
+        """From an Endpoint, a ``(node, port)`` pair or the text ``"node.port"``."""
+        if isinstance(value, str):
+            node, dot, port = value.partition(".")
+            if not (node and dot and port):
+                raise EdgeError(f"expected 'node.port': {value!r}")
+            return cls(node, port)
+        try:
+            node, port = value
+        except (TypeError, ValueError):
+            raise EdgeError(f"expected (node, port): {value!r}") from None
+        return cls(str(node), str(port))
+
+
+@dataclass(frozen=True)
+class Edge:
+    """``back`` marks an edge that closes a loop: it never counts toward a node's first start, and it must say
+    how many rounds it may open at most (``max_rounds``), so no loop can run for ever by construction."""
+
+    id: str
+    source: Endpoint
+    target: Endpoint
+    protocol: str
+    back: bool = False
+    max_rounds: int | None = None
+
+    def __post_init__(self):
+        object.__setattr__(self, "source", Endpoint.of(self.source))
+        object.__setattr__(self, "target", Endpoint.of(self.target))
+        if not isinstance(self.id, str) or not self.id.strip():
+            raise EdgeError("an edge needs an id")
+        if not isinstance(self.protocol, str) or not self.protocol:
+            raise EdgeError(f"edge {self.id}: no protocol")
+        if self.back:
+            if type(self.max_rounds) is not int or self.max_rounds < 1:
+                raise EdgeError(f"edge {self.id}: a back edge needs max_rounds of at least 1")
+        elif self.max_rounds is not None:
+            raise EdgeError(f"edge {self.id}: only a back edge has max_rounds")
+
+    def describe(self) -> dict:
+        return {"id": self.id, "from": str(self.source), "to": str(self.target), "protocol": self.protocol,
+                "back": self.back, "max_rounds": self.max_rounds}

interlacing/base/envelope.py

@@ -0,0 +1,25 @@
+"""The envelope: the one form in which information travels along an edge."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Ref:
+    """A body kept elsewhere (a file, a large value): the envelope and the log carry only this reference."""
+
+    digest: str        # content hash, which is also how the content store finds it
+    size: int = 0
+    media: str = ""    # what it is, when known: "text/markdown", "application/json", ...
+
+
+@dataclass(frozen=True)
+class Envelope:
+    id: str
+    edge: str                       # the edge it travels on
+    seq: int                        # its number on that edge, from 1
+    round: int                      # the round of the activation that sent it
+    body: Any                       # small data inline, anything large as a Ref
+    digest: str                     # hash of the body
+    cause: tuple[str, ...] = ()     # the envelopes the sending activation had received: where this came from

interlacing/base/graph.py

@@ -0,0 +1,271 @@
+"""The graph: nodes joined by edges, checked once and then read-only.
+
+``GraphBuilder`` collects nodes and edges; ``compile`` checks the whole and returns a ``Graph`` with its
+indexes built. A graph never changes: a different graph is a new value with a new digest. Building costs
+time proportional to nodes plus edges (plus one walk per back edge); every lookup afterwards is a dictionary
+or tuple access.
+
+Rules checked by ``compile``:
+
+* every edge joins an existing output port to an existing input port, under a registered protocol that
+  accepts the pair;
+* an input that is not ``many`` has at most one forward feed (an edge or a graph input); back edges may
+  feed it as well, since they only arrive in later rounds, and so may any number of calls;
+* a required input has a forward feed, otherwise its node could never start;
+* without its back edges the graph has no cycle, and every back edge really closes a loop. With the
+  ``max_rounds`` every back edge carries, no run can go on for ever.
+"""
+from __future__ import annotations
+
+from collections import deque
+from types import MappingProxyType
+from typing import Iterable, Mapping
+
+from .canonical import digest
+from .edge import Edge, EdgeError, Endpoint
+from .node import Firing, Node
+from .protocol import Delivery, ProtocolError, Protocols
+
+
+class GraphError(ValueError):
+    pass
+
+
+class Graph:
+    """A compiled graph. Construct it with ``GraphBuilder.compile``."""
+
+    __slots__ = ("nodes", "edges", "inputs", "outputs", "order", "digest", "_node", "_edge", "_out", "_in", "_needs")
+
+    def __init__(self, nodes, edges, inputs, outputs, order, out_index, in_index, needs):
+        self.nodes: tuple[Node, ...] = nodes
+        self.edges: tuple[Edge, ...] = edges
+        self.inputs: Mapping[str, Endpoint] = MappingProxyType(inputs)     # the graph's own inputs, by name
+        self.outputs: Mapping[str, Endpoint] = MappingProxyType(outputs)   # the graph's own outputs, by name
+        self.order: tuple[str, ...] = order                                # node ids, upstream first (back edges ignored)
+        self._node = {node.id: node for node in nodes}
+        self._edge = {edge.id: edge for edge in edges}
+        self._out, self._in, self._needs = out_index, in_index, needs
+        self.digest: str = digest(self.describe())
+
+    # ---- lookups ---------------------------------------------------------------------------------------
+
+    def node(self, id: str) -> Node:
+        try:
+            return self._node[id]
+        except KeyError:
+            raise GraphError(f"no node {id!r}") from None
+
+    def edge(self, id: str) -> Edge:
+        try:
+            return self._edge[id]
+        except KeyError:
+            raise GraphError(f"no edge {id!r}") from None
+
+    def __contains__(self, id) -> bool:
+        return id in self._node
+
+    def __len__(self) -> int:
+        return len(self.nodes)
+
+    def outgoing(self, node: str, port: str | None = None) -> tuple[Edge, ...]:
+        """Edges leaving a node, or one of its output ports."""
+        ports = self._out[node]
+        return ports.get(port, ()) if port is not None else tuple(e for edges in ports.values() for e in edges)
+
+    def incoming(self, node: str, port: str | None = None) -> tuple[Edge, ...]:
+        """Edges arriving at a node, or one of its input ports."""
+        ports = self._in[node]
+        return ports.get(port, ()) if port is not None else tuple(e for edges in ports.values() for e in edges)
+
+    def needs(self, node: str) -> int:
+        """How many required inputs must arrive before the node's first activation (0: it starts by itself)."""
+        return self._needs[node]
+
+    @property
+    def sources(self) -> tuple[str, ...]:
+        """Nodes that wait for nothing."""
+        return tuple(id for id in self.order if not self._needs[id])
+
+    def describe(self) -> dict:
+        """The definition as plain data, in a fixed order: equal graphs describe, and so hash, the same."""
+        return {"nodes": sorted((n.describe() for n in self.nodes), key=lambda d: d["id"]),
+                "edges": sorted((e.describe() for e in self.edges), key=lambda d: d["id"]),
+                "inputs": {name: str(end) for name, end in sorted(self.inputs.items())},
+                "outputs": {name: str(end) for name, end in sorted(self.outputs.items())}}
+
+    def __repr__(self):
+        return f"<Graph {len(self.nodes)} nodes, {len(self.edges)} edges, {self.digest[:12]}>"
+
+
+class GraphBuilder:
+    def __init__(self):
+        self._nodes: dict[str, Node] = {}
+        self._edges: dict[str, Edge] = {}
+        self._inputs: dict[str, Endpoint] = {}
+        self._outputs: dict[str, Endpoint] = {}
+
+    @classmethod
+    def of(cls, graph: "Graph") -> "GraphBuilder":
+        """A builder holding everything ``graph`` has: the way to make a changed graph from an existing one."""
+        builder = cls()
+        builder._nodes = {node.id: node for node in graph.nodes}
+        builder._edges = {edge.id: edge for edge in graph.edges}
+        builder._inputs, builder._outputs = dict(graph.inputs), dict(graph.outputs)
+        return builder
+
+    def remove(self, node: str) -> "GraphBuilder":
+        """Take a node out, with every edge and graph port that touches it."""
+        if node not in self._nodes:
+            raise GraphError(f"no node {node!r}")
+        del self._nodes[node]
+        self._edges = {id: e for id, e in self._edges.items() if node not in (e.source.node, e.target.node)}
+        self._inputs = {name: end for name, end in self._inputs.items() if end.node != node}
+        self._outputs = {name: end for name, end in self._outputs.items() if end.node != node}
+        return self
+
+    def disconnect(self, edge: str) -> "GraphBuilder":
+        if edge not in self._edges:
+            raise GraphError(f"no edge {edge!r}")
+        del self._edges[edge]
+        return self
+
+    def add(self, *nodes: Node) -> "GraphBuilder":
+        for node in nodes:
+            if not isinstance(node, Node):
+                raise GraphError(f"not a node: {node!r}")
+            if node.id in self._nodes:
+                raise GraphError(f"duplicate node: {node.id}")
+            self._nodes[node.id] = node
+        return self
+
+    def connect(self, source, target, protocol: str, *, id: str | None = None, back: bool = False,
+                max_rounds: int | None = None) -> "GraphBuilder":
+        """Join ``"node.port"`` to ``"node.port"``. The id defaults to ``"a.out>b.in"``."""
+        try:
+            source, target = Endpoint.of(source), Endpoint.of(target)
+            edge = Edge(id or f"{source}>{target}", source, target, protocol, back, max_rounds)
+        except EdgeError as exc:
+            raise GraphError(str(exc)) from None
+        if edge.id in self._edges:
+            raise GraphError(f"duplicate edge: {edge.id}")
+        self._edges[edge.id] = edge
+        return self
+
+    def input(self, name: str, target) -> "GraphBuilder":
+        """Name an input port as an input of the graph itself: whoever runs the graph feeds it."""
+        return self._expose(self._inputs, name, target)
+
+    def output(self, name: str, source) -> "GraphBuilder":
+        """Name an output port as an output of the graph itself."""
+        return self._expose(self._outputs, name, source)
+
+    def _expose(self, table, name, end) -> "GraphBuilder":
+        if not isinstance(name, str) or not name or name in table:
+            raise GraphError(f"invalid or duplicate graph port: {name!r}")
+        try:
+            table[name] = Endpoint.of(end)
+        except EdgeError as exc:
+            raise GraphError(str(exc)) from None
+        return self
+
+    # ---- compile ---------------------------------------------------------------------------------------
+
+    def compile(self, protocols: Protocols) -> Graph:
+        nodes, edges = tuple(self._nodes.values()), tuple(self._edges.values())
+        if not nodes:
+            raise GraphError("a graph needs at least one node")
+        out_index: dict[str, dict[str, list]] = {n.id: {port: [] for port in n.outputs} for n in nodes}
+        in_index: dict[str, dict[str, list]] = {n.id: {port: [] for port in n.inputs} for n in nodes}
+        fed: dict[Endpoint, int] = {}           # forward feeds of each input port
+        called: set[Endpoint] = set()           # input ports that are the target of a call
+        for edge in edges:
+            source, target = self._port(edge.source, "outputs", edge), self._port(edge.target, "inputs", edge)
+            protocol = protocols.get(edge.protocol)
+            if protocol is None:
+                raise GraphError(f"edge {edge.id}: unknown protocol {edge.protocol!r}")
+            try:
+                protocol.check(source, target)
+            except ProtocolError as exc:
+                raise GraphError(f"edge {edge.id}: {exc}") from None
+            out_index[edge.source.node][edge.source.port].append(edge)
+            in_index[edge.target.node][edge.target.port].append(edge)
+            if protocol.delivery is Delivery.CALL:
+                called.add(edge.target)       # any number of callers may ask the same port
+            elif not edge.back:
+                fed[edge.target] = fed.get(edge.target, 0) + 1
+        for name, end in self._inputs.items():
+            self._port(end, "inputs", f"graph input {name}")
+            fed[end] = fed.get(end, 0) + 1
+        for name, end in self._outputs.items():
+            self._port(end, "outputs", f"graph output {name}")
+        needs = {}
+        for node in nodes:
+            count = 0
+            for port in node.inputs.values():
+                feeds = fed.get(Endpoint(node.id, port.name), 0)
+                if feeds > 1 and not port.many:
+                    raise GraphError(f"{node.id}.{port.name} takes one feed, {feeds} are connected")
+                if port.required:
+                    if not feeds and Endpoint(node.id, port.name) not in called:
+                        raise GraphError(f"{node.id}.{port.name} is required and nothing feeds it")
+                    count += 1
+            if node.firing is Firing.ANY:
+                if not any(fed.get(Endpoint(node.id, name)) or in_index[node.id][name] for name in node.inputs):
+                    raise GraphError(f"{node.id} fires on any input and nothing feeds it")
+                count = 1   # one arrival, on whichever port, is enough
+            needs[node.id] = count
+        order = self._order(nodes, edges)
+        self._check_loops(edges, out_index)
+        freeze = lambda index: {n: MappingProxyType({p: tuple(es) for p, es in ports.items()})  # noqa: E731
+                                for n, ports in index.items()}
+        return Graph(nodes, edges, dict(self._inputs), dict(self._outputs), order, freeze(out_index), freeze(in_index), needs)
+
+    def _port(self, end: Endpoint, side: str, where):
+        node = self._nodes.get(end.node)
+        if node is None:
+            raise GraphError(f"{where if isinstance(where, str) else 'edge ' + where.id}: no node {end.node!r}")
+        port = getattr(node, side).get(end.port)
+        if port is None:
+            kind = "output" if side == "outputs" else "input"
+            raise GraphError(f"{where if isinstance(where, str) else 'edge ' + where.id}: {end.node} has no {kind} port {end.port!r}")
+        return port
+
+    @staticmethod
+    def _order(nodes: Iterable[Node], edges: Iterable[Edge]) -> tuple[str, ...]:
+        """Upstream first, ignoring back edges; ties keep the order the nodes were added in."""
+        waiting = {n.id: 0 for n in nodes}
+        after: dict[str, list[str]] = {n.id: [] for n in nodes}
+        for edge in edges:
+            if not edge.back:
+                waiting[edge.target.node] += 1
+                after[edge.source.node].append(edge.target.node)
+        queue = deque(id for id, count in waiting.items() if not count)
+        order = []
+        while queue:
+            current = queue.popleft()
+            order.append(current)
+            for following in after[current]:
+                waiting[following] -= 1
+                if not waiting[following]:
+                    queue.append(following)
+        if len(order) != len(waiting):
+            stuck = sorted(id for id, count in waiting.items() if count)
+            raise GraphError(f"a loop needs a back edge: {', '.join(stuck[:8])} form a cycle of forward edges")
+        return tuple(order)
+
+    @staticmethod
+    def _check_loops(edges: Iterable[Edge], out_index) -> None:
+        """A back edge from A to B closes a loop only if B leads to A along forward edges."""
+        for edge in edges:
+            if not edge.back:
+                continue
+            goal, seen, stack = edge.source.node, {edge.target.node}, [edge.target.node]
+            while stack and goal not in seen:
+                for following in out_index[stack.pop()].values():
+                    for forward in following:
+                        if not forward.back and forward.target.node not in seen:
+                            seen.add(forward.target.node)
+                            stack.append(forward.target.node)
+            if goal not in seen:
+                raise GraphError(f"edge {edge.id} is marked back but closes no loop: "
+                                 f"{edge.target.node} does not lead to {edge.source.node}")

interlacing/base/method.py

@@ -0,0 +1,21 @@
+"""The method: a reusable way of joining nodes, a chain, a loop, a tree and so on.
+
+A method takes the parts it is given and returns a graph. How the result runs is already in that graph: each
+node says when it fires, each back edge says how many rounds it may open. A graph can be wrapped as one node,
+so methods nest.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from .graph import Graph
+from .protocol import Protocols
+
+
+class Method(ABC):
+    name: ClassVar[str] = ""
+
+    @abstractmethod
+    def build(self, protocols: Protocols) -> Graph:
+        """The graph this method makes of its parts."""

interlacing/base/node.py

@@ -0,0 +1,151 @@
+"""The node: anything that takes information in and gives information out.
+
+A node knows its ports and how to run once. It does not know which graph it is in, who is upstream or
+downstream, or how its outputs travel: everything it touches outside itself goes through the ``Context`` the
+engine hands it. An agent, a function, an external program, a device, a person and a whole sub-graph are all
+nodes, with no difference in standing.
+"""
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from enum import Enum
+from types import MappingProxyType
+from typing import Any, ClassVar, Iterable, Mapping
+
+from .port import Port
+
+ID = re.compile(r"[a-z][a-z0-9_-]{0,63}")
+
+
+class NodeError(ValueError):
+    pass
+
+
+class Invalid(NodeError):
+    """What a node sent, or was sent, did not pass a check. ``problem`` says what is wrong, in words meant
+    to be read by whoever can put it right. ``again`` is true when the node may correct it and send again
+    within the same activation; when it is false the node fails."""
+
+    def __init__(self, port: str, problem: str, again: bool = False):
+        super().__init__(f"{port}: {problem}")
+        self.port, self.problem, self.again = port, problem, again
+
+
+class Firing(Enum):
+    """When a node is activated."""
+
+    ALL = "all"   # once every required input has arrived
+    ANY = "any"   # each time any input arrives
+
+
+class Context(ABC):
+    """What the engine gives a node for one activation."""
+
+    node: str     # the node's id
+    round: int    # which activation of this node this is, from 1
+    problems: list  # when the activation is run again because what it sent was not accepted: what was wrong
+    within: Any     # when the graph runs inside a node of another: (node id, round) of each, outermost first
+    key: Any        # names this activation of this node in this run, and is the same when it runs again after
+                    # an interruption: give it to an outside service so that it does not do the same thing twice
+
+    @abstractmethod
+    def emit(self, port: str, payload: Any) -> None:
+        """Send ``payload`` out of an output port now (a node may emit many times during one activation).
+        Raises ``Invalid`` when the payload does not pass the port's checks; a node that can put it right
+        catches that, reads ``problem`` and, when ``again`` is true, sends a corrected payload."""
+
+    @abstractmethod
+    def call(self, port: str, payload: Any) -> Any:
+        """Send ``payload`` out of an output port whose edge is a call, wait, and return the other node's answer."""
+
+    @abstractmethod
+    def stopping(self) -> bool:
+        """True once the run is being stopped: a long activation should return soon."""
+
+    @abstractmethod
+    def engine(self, graph: Any, protocols: Any, *, workers: int = 0, firm: bool = False) -> Any:
+        """An engine for a graph that runs inside this activation. It stops when the outer run stops, keeps
+        its own journal beside the outer one when there is one, tells the outer observer what happens in it,
+        and works under the same time limit. ``go(inputs)`` runs it, or takes it up where an interrupted
+        earlier attempt at this same activation left it. ``firm=True`` is for a graph that is not trusted:
+        none of its nodes may give itself more time than the run allows."""
+
+    def use(self, **amounts: float) -> None:
+        """Report what this activation used up, under names of the node's choosing (``tokens=1200``,
+        ``calls=1``, ``seconds=3.5``). The run adds it up; when a total goes over the run's budget for that
+        name the run fails, and this raises so that the node stops at once."""
+
+
+def _ports(given: Iterable[Port] | Mapping[str, Port] | None, declared: Iterable[Port] | Mapping[str, Port]) -> Mapping[str, Port]:
+    ports = list(given.values() if isinstance(given, Mapping) else given) if given is not None else list(declared)
+    out: dict[str, Port] = {}
+    for port in ports:
+        if not isinstance(port, Port):
+            raise NodeError(f"not a port: {port!r}")
+        if port.name in out:
+            raise NodeError(f"duplicate port: {port.name}")
+        out[port.name] = port
+    return MappingProxyType(out)
+
+
+class Node(ABC):
+    """Subclass, set ``kind``, declare ports (on the class or per instance) and implement ``run``.
+
+    ``run`` receives the inputs that have arrived, by port name (a list for a ``many`` port). It may return a
+    mapping of output port to payload, call ``ctx.emit`` any number of times, or both. Returning ends the
+    activation.
+    """
+
+    kind: ClassVar[str] = ""                 # the name this kind of node is registered and stored under
+    # A class may declare its ports as a tuple of Ports; on an instance they are a mapping from name to Port.
+    inputs: Mapping[str, Port] = ()     # type: ignore[assignment]
+    outputs: Mapping[str, Port] = ()    # type: ignore[assignment]
+    firing: Firing = Firing.ALL
+    repairs: int = 0                         # how often an output may be corrected, for ports that do not say
+    time_limit: float | None = None          # the longest one activation may take, in seconds; None: the engine's
+
+    def __init__(self, id: str, *, inputs: Iterable[Port] | None = None, outputs: Iterable[Port] | None = None,
+                 firing: Firing | None = None):
+        if not isinstance(id, str) or not ID.fullmatch(id):
+            raise NodeError(f"invalid node id: {id!r}")
+        if not type(self).kind:
+            raise NodeError(f"{type(self).__name__} has no kind")
+        self.id = id
+        self.inputs = _ports(inputs, type(self).inputs)
+        self.outputs = _ports(outputs, type(self).outputs)
+        if firing is not None:
+            self.firing = Firing(firing)
+
+    def config(self) -> Mapping:
+        """Plain data that sets this node apart from another of the same kind (it goes into the graph digest)."""
+        return {}
+
+    def describe(self) -> dict:
+        own = self.__dict__.get("time_limit")
+        return {"id": self.id, "kind": type(self).kind, "firing": self.firing.value,
+                "inputs": [p.describe() for p in self.inputs.values()],
+                "outputs": [p.describe() for p in self.outputs.values()], "config": dict(self.config()),
+                **({"time_limit": own} if own is not None else {})}
+
+    # ---- lifecycle: only run is required --------------------------------------------------------------
+
+    def open(self, ctx: Context) -> None:
+        """Acquire what the node needs, once, before its first activation."""
+
+    @abstractmethod
+    def run(self, ctx: Context, inputs: Mapping[str, Any]) -> Mapping[str, Any] | None:
+        """One activation."""
+
+    def close(self, ctx: Context) -> None:
+        """Release what ``open`` acquired."""
+
+    def snapshot(self) -> Mapping:
+        """Plain data from which ``restore`` can rebuild the node's own state after a restart."""
+        return {}
+
+    def restore(self, state: Mapping) -> None:
+        pass
+
+    def __repr__(self):
+        return f"<{type(self).__name__} {self.id}>"