without-dag 0.0.1__tar.gz

without_dag-0.0.1/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: without-dag
+Version: 0.0.1
+Summary: Bounded-concurrency execution of DAG-shaped async workflows for without, liftable into a Processor.
+Author: Josh Karpel
+Author-email: Josh Karpel <josh.karpel@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: without-core==0.0.1
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# without-dag
+
+Concurrent execution of DAG-shaped async workflows, liftable into a `without`
+`Processor`. A `Processor[In, Out]` is otherwise an opaque stream-to-stream
+closure; this package lets the *inside* of a per-event step be a graph of async
+sub-steps that run with bounded concurrency and recombine into one output. It is
+the value-level fan-out/fan-in the substrate leaves room for: one input value
+drives many concurrent computations.
+
+`Graph` is the typed frontend: a builder that threads value types through the
+wiring so a mismatched dependency is a mypy error and a cycle is unrepresentable.
+It compiles once into a `CompiledGraph`, an async callable reused per event:
+
+```python
+from without_dag import Graph
+
+async def fetch(request: Request) -> Fetched: ...
+async def parse(fetched: Fetched) -> Parsed: ...
+async def render(fetched: Fetched, parsed: Parsed) -> Report: ...
+
+graph, (request,) = Graph.of(Request)
+fetched = graph.node(fetch, request)
+parsed = graph.node(parse, fetched)
+report = graph.node(render, fetched, parsed)
+run = graph.build(output=report, limit=4)
+
+result: Report = await run(some_request)
+```
+
+Each node runs once (memoized, so a diamond's shared ancestor executes a single
+time with no glitch), acyclicity is proven at the boundary via stdlib
+`graphlib`, and a single-input graph is an async `(In) -> Out` callable, exactly
+what `from_map` lifts into a `Processor`.
+
+See the
+[`without-dag` guide](https://without.help/guides/without-dag/)
+(with the [API reference](https://without.help/reference/without_dag/))
+for the full surface: the object-seam execution core (`Plan`, `drive`,
+`evaluate`), the typed frontend, and lifting into a processor.

without_dag-0.0.1/README.md

@@ -0,0 +1,39 @@
+# without-dag
+
+Concurrent execution of DAG-shaped async workflows, liftable into a `without`
+`Processor`. A `Processor[In, Out]` is otherwise an opaque stream-to-stream
+closure; this package lets the *inside* of a per-event step be a graph of async
+sub-steps that run with bounded concurrency and recombine into one output. It is
+the value-level fan-out/fan-in the substrate leaves room for: one input value
+drives many concurrent computations.
+
+`Graph` is the typed frontend: a builder that threads value types through the
+wiring so a mismatched dependency is a mypy error and a cycle is unrepresentable.
+It compiles once into a `CompiledGraph`, an async callable reused per event:
+
+```python
+from without_dag import Graph
+
+async def fetch(request: Request) -> Fetched: ...
+async def parse(fetched: Fetched) -> Parsed: ...
+async def render(fetched: Fetched, parsed: Parsed) -> Report: ...
+
+graph, (request,) = Graph.of(Request)
+fetched = graph.node(fetch, request)
+parsed = graph.node(parse, fetched)
+report = graph.node(render, fetched, parsed)
+run = graph.build(output=report, limit=4)
+
+result: Report = await run(some_request)
+```
+
+Each node runs once (memoized, so a diamond's shared ancestor executes a single
+time with no glitch), acyclicity is proven at the boundary via stdlib
+`graphlib`, and a single-input graph is an async `(In) -> Out` callable, exactly
+what `from_map` lifts into a `Processor`.
+
+See the
+[`without-dag` guide](https://without.help/guides/without-dag/)
+(with the [API reference](https://without.help/reference/without_dag/))
+for the full surface: the object-seam execution core (`Plan`, `drive`,
+`evaluate`), the typed frontend, and lifting into a processor.

without_dag-0.0.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["uv_build>=0.11.25,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "without-dag"
+version = "0.0.1"
+description = "Bounded-concurrency execution of DAG-shaped async workflows for without, liftable into a Processor."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Josh Karpel", email = "josh.karpel@gmail.com" },
+]
+requires-python = ">=3.14"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "without-core==0.0.1",
+]
+
+[tool.uv.sources]
+without-core = { workspace = true }

without_dag-0.0.1/src/without_dag/__init__.py

@@ -0,0 +1,19 @@
+from without_dag.execution import Node
+from without_dag.execution import NodeKey
+from without_dag.execution import Plan
+from without_dag.execution import drive
+from without_dag.execution import evaluate
+from without_dag.graph import CompiledGraph
+from without_dag.graph import Graph
+from without_dag.graph import Handle
+
+__all__ = [
+    "CompiledGraph",
+    "Graph",
+    "Handle",
+    "Node",
+    "NodeKey",
+    "Plan",
+    "drive",
+    "evaluate",
+]

without_dag-0.0.1/src/without_dag/execution.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import asyncio
+from collections import Counter
+from collections import deque
+from collections.abc import AsyncGenerator
+from collections.abc import Awaitable
+from collections.abc import Callable
+from collections.abc import Hashable
+from collections.abc import Iterable
+from collections.abc import Mapping
+from dataclasses import dataclass
+from graphlib import TopologicalSorter
+
+from without import cancel_futures
+
+type NodeKey = Hashable
+
+
+@dataclass(frozen=True, slots=True)
+class Node:
+    """
+    One async step in a graph, named by `key` and wired by `dependencies`.
+
+    The narrow seam a graph-defining frontend lowers onto: a `Node` is a value,
+    not a place. `run` receives its dependencies' results as a tuple in
+    `dependencies` order and returns this node's single result. Results cross
+    this seam as `object` (the executor cannot know each step's type); a typed
+    frontend restores precision above it, exactly as `without-web`'s `Extractor`
+    is collected as `Extractor[object]` and re-typed by `into`.
+    """
+
+    key: NodeKey
+    dependencies: tuple[NodeKey, ...]
+    run: Callable[[tuple[object, ...]], Awaitable[object]]
+
+
+@dataclass(frozen=True, slots=True)
+class Plan:
+    """
+    A node set compiled into its input-independent scheduling structure.
+
+    Everything a run needs that does *not* depend on the input values: the nodes
+    by key, the dependency edges (as the graph `graphlib` wants), and the number
+    of consumers per key (so a result can be freed once its last dependent has
+    read it). Computed once and reused across runs as a value, so a fixed graph
+    driven per event never rebuilds any of it.
+    """
+
+    by_key: Mapping[NodeKey, Node]
+    dependencies: Mapping[NodeKey, tuple[NodeKey, ...]]
+    consumers: Mapping[NodeKey, int]
+
+    @classmethod
+    def of(cls, nodes: Iterable[Node]) -> Plan:
+        """Compile a node set into a reusable `Plan`."""
+        by_key = {node.key: node for node in nodes}
+        dependencies = {key: node.dependencies for key, node in by_key.items()}
+        consumers: Counter[NodeKey] = Counter()
+        for node in by_key.values():
+            consumers.update(node.dependencies)
+        return cls(by_key=by_key, dependencies=dependencies, consumers=consumers)
+
+
+async def drive(
+    plan: Plan,
+    inputs: Mapping[NodeKey, object],
+    limit: int | None,
+) -> AsyncGenerator[tuple[NodeKey, object]]:
+    """
+    Run a compiled `Plan`, yielding each `(key, result)` the instant it completes.
+
+    The streaming core, and the *events* half of the model. Yields completions in
+    whatever order nodes finish; the only ordering guarantee is the causal one, a
+    node after the dependencies it consumed. `inputs` pre-supplies the values of
+    source keys, marked done without running and never yielded. `limit` caps how
+    many nodes run concurrently (`None` is unbounded).
+
+    Scheduling replicates the shape of `without.limit_concurrency`
+    (`asyncio.wait(..., return_when=FIRST_COMPLETED)`) rather than calling it: the
+    scheduler needs the completed task's `NodeKey` to unlock successors, which
+    that lazy source hides. Acyclicity is proven by `TopologicalSorter.prepare`,
+    which raises `graphlib.CycleError`. Each node runs once; a result is dropped
+    as soon as its last dependent has captured it. A node that raises fails the
+    whole run, cancelling in-flight siblings, which is also how closing the
+    iterator early tears the run down.
+    """
+    if limit is not None and limit < 1:
+        raise ValueError(f"limit must be at least 1 or None, but got {limit}")
+
+    sorter: TopologicalSorter[NodeKey] = TopologicalSorter(plan.dependencies)
+    sorter.prepare()
+    consumers: Counter[NodeKey] = Counter(plan.consumers)
+    results: dict[NodeKey, object] = dict(inputs)
+    running: dict[asyncio.Future[object], NodeKey] = {}
+    ready: deque[NodeKey] = deque(sorter.get_ready())
+    try:
+        while sorter.is_active():
+            while ready and (limit is None or len(running) < limit):
+                key = ready.popleft()
+                if key in results:
+                    sorter.done(key)
+                    ready.extend(sorter.get_ready())
+                    continue
+                if key not in plan.by_key:
+                    raise KeyError(f"{key!r} is neither a supplied input nor a defined node")
+                node = plan.by_key[key]
+                args = tuple(results[dependency] for dependency in node.dependencies)
+                for dependency in node.dependencies:
+                    consumers[dependency] -= 1
+                    if consumers[dependency] == 0:
+                        del results[dependency]
+                running[asyncio.ensure_future(node.run(args))] = key
+            done, _ = await asyncio.wait(running, return_when=asyncio.FIRST_COMPLETED)
+            for future in done:
+                key = running.pop(future)
+                value = future.result()
+                results[key] = value
+                sorter.done(key)
+                ready.extend(sorter.get_ready())
+                yield key, value
+    finally:
+        await cancel_futures(running)
+
+
+async def evaluate(plan: Plan, target: NodeKey, inputs: Mapping[NodeKey, object], limit: int | None) -> object:
+    """
+    Run every node in `plan` and return `target`'s value: the *behavior* read.
+
+    A consumer of `drive` that runs the whole graph and keeps the one value the
+    caller wants, dropping the rest. `target` is a node whose completion supplies
+    the value, or a supplied input returned directly (an identity plan). There is
+    deliberately no early return on `target`: the graph is run to completion, so
+    the result reflects the whole graph and every node's effects have happened.
+
+    A `target` that is neither a defined node nor a supplied input raises
+    `KeyError`, matching `drive`, rather than silently reading back as `None`.
+    """
+    if target not in plan.by_key and target not in inputs:
+        raise KeyError(f"{target!r} is neither a supplied input nor a defined node")
+    # `target` is either a node, whose completion `drive` yields (and overwrites
+    # this), or a supplied input, which `drive` never yields: default to its value
+    # so an identity graph (the output is an input) returns it.
+    result: object = inputs.get(target)
+    async for key, value in drive(plan, inputs, limit):
+        if key == target:
+            result = value
+    return result

without_dag-0.0.1/src/without_dag/graph.py

@@ -0,0 +1,438 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from collections.abc import Awaitable
+from collections.abc import Callable
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Generic
+from typing import TypeVar
+from typing import cast
+from typing import overload
+
+from without_dag.execution import Node
+from without_dag.execution import NodeKey
+from without_dag.execution import Plan
+from without_dag.execution import drive
+from without_dag.execution import evaluate
+
+# Covariant: `T` names the node's result but is a phantom (no field holds it), so
+# a `Handle[int]` is a `Handle[object]`. That is what lets the `node` runtime
+# collect a heterogeneous mix of dependency handles as `*deps: Handle[object]`
+# while the overloads keep each one's precise type. The legacy `TypeVar` is
+# needed because PEP 695 infers an unused parameter as invariant; the variance is
+# sound here, so we state it explicitly (see `without_web.extractors.Extractor`).
+_T_co = TypeVar("_T_co", covariant=True)
+
+
+@dataclass(frozen=True, slots=True)
+class Handle(Generic[_T_co]):  # noqa: UP046 - PEP 695 infers a phantom parameter as invariant; the covariant TypeVar is deliberate (see above)
+    """
+    A typed reference to a node's future result.
+
+    The token the builder hands back from `of`/`node` and takes back as a
+    dependency. `T` is phantom: the handle carries only an opaque `key`, but the
+    type flows through the wiring so a downstream step is checked against the
+    types of the handles it depends on. Because a caller can only pass handles
+    that already exist, a cycle is unrepresentable through this API.
+    """
+
+    key: NodeKey
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledGraph[*Ins, Out]:
+    """
+    A frozen graph that *is* an async callable `(*Ins) -> Out`.
+
+    `build` returns one of these. It runs one bounded-concurrency execution per
+    call, seeding each entry the graph was opened over with the matching
+    positional argument and returning the value of its `output`. A single-input
+    graph is a plain `Callable[[In], Awaitable[Out]]`, so it lifts into a
+    `Processor` with `from_map`. The scheduling structure is compiled once at
+    `build` into `_plan` and reused by every call and `stream`, so a graph driven
+    per event never recomputes it. `nodes` is kept so the structure is
+    *recoverable* (a future diagram is derived from this one declaration, not
+    maintained beside it).
+    """
+
+    nodes: tuple[Node, ...]
+    inputs: tuple[NodeKey, ...]
+    output: NodeKey
+    limit: int | None
+    _plan: Plan
+
+    async def __call__(self, *values: *Ins) -> Out:
+        result = await evaluate(self._plan, self.output, self._seed(values), self.limit)
+        return cast(Out, result)
+
+    def stream(self, *values: *Ins) -> AsyncGenerator[tuple[NodeKey, object]]:
+        """
+        Run the whole graph, yielding each node's `(key, result)` as it completes.
+
+        The streaming counterpart to calling the graph: `__call__` samples the
+        single `output` value (a behavior), `stream` reports every completion as
+        it happens (the events), letting the caller react as results land or read
+        several outputs. The positional arguments seed the graph's inputs,
+        checked against `*Ins` exactly as the call is; match a yielded key against
+        a `Handle`'s `key` to pick out a node's result.
+        """
+        return drive(self._plan, self._seed(values), self.limit)
+
+    def _seed(self, values: tuple[object, ...]) -> dict[NodeKey, object]:
+        return dict(zip(self.inputs, values, strict=True))
+
+
+@dataclass(frozen=True, slots=True)
+class Graph[*Ins]:
+    """
+    A builder that records async steps and returns typed `Handle`s.
+
+    `of` opens a graph over its entry types and hands back a tuple of one `Handle`
+    per type, `node` adds a step wired to the handles it depends on, and `build` freezes the
+    result into a `CompiledGraph`. Because the graph carries its entry pack in
+    its type (`Graph[*Ins]`), `build` needs only the output handle: it recovers
+    the inputs the graph already knows, so there is no second place to keep in
+    sync. The builder itself is a frozen value; the only mutation is appending to
+    its interior list of recorded nodes. Each step's function receives its
+    dependencies' results as positional arguments in the order its handles were
+    passed.
+    """
+
+    _nodes: list[Node] = field(default_factory=list)
+    _input_keys: tuple[NodeKey, ...] = ()
+
+    # [[[cog import cog; from dag_ladders import emit; cog.outl(emit("of")) ]]]
+    @overload
+    @staticmethod
+    def of() -> tuple[
+        Graph[()],
+        tuple[()],
+    ]: ...
+
+    @overload
+    @staticmethod
+    def of[A](
+        a: type[A],
+        /,
+    ) -> tuple[
+        Graph[A],
+        tuple[Handle[A]],
+    ]: ...
+
+    @overload
+    @staticmethod
+    def of[A, B](
+        a: type[A],
+        b: type[B],
+        /,
+    ) -> tuple[
+        Graph[A, B],
+        tuple[Handle[A], Handle[B]],
+    ]: ...
+
+    @overload
+    @staticmethod
+    def of[A, B, C](
+        a: type[A],
+        b: type[B],
+        c: type[C],
+        /,
+    ) -> tuple[
+        Graph[A, B, C],
+        tuple[Handle[A], Handle[B], Handle[C]],
+    ]: ...
+
+    @overload
+    @staticmethod
+    def of[A, B, C, D](
+        a: type[A],
+        b: type[B],
+        c: type[C],
+        d: type[D],
+        /,
+    ) -> tuple[
+        Graph[A, B, C, D],
+        tuple[Handle[A], Handle[B], Handle[C], Handle[D]],
+    ]: ...
+
+    @overload
+    @staticmethod
+    def of[A, B, C, D, E](
+        a: type[A],
+        b: type[B],
+        c: type[C],
+        d: type[D],
+        e: type[E],
+        /,
+    ) -> tuple[
+        Graph[A, B, C, D, E],
+        tuple[Handle[A], Handle[B], Handle[C], Handle[D], Handle[E]],
+    ]: ...
+
+    @overload
+    @staticmethod
+    def of[A, B, C, D, E, F](
+        a: type[A],
+        b: type[B],
+        c: type[C],
+        d: type[D],
+        e: type[E],
+        f: type[F],
+        /,
+    ) -> tuple[
+        Graph[A, B, C, D, E, F],
+        tuple[Handle[A], Handle[B], Handle[C], Handle[D], Handle[E], Handle[F]],
+    ]: ...
+
+    @overload
+    @staticmethod
+    def of[A, B, C, D, E, F, G](
+        a: type[A],
+        b: type[B],
+        c: type[C],
+        d: type[D],
+        e: type[E],
+        f: type[F],
+        g: type[G],
+        /,
+    ) -> tuple[
+        Graph[A, B, C, D, E, F, G],
+        tuple[Handle[A], Handle[B], Handle[C], Handle[D], Handle[E], Handle[F], Handle[G]],
+    ]: ...
+
+    @overload
+    @staticmethod
+    def of[A, B, C, D, E, F, G, H](
+        a: type[A],
+        b: type[B],
+        c: type[C],
+        d: type[D],
+        e: type[E],
+        f: type[F],
+        g: type[G],
+        h: type[H],
+        /,
+    ) -> tuple[
+        Graph[A, B, C, D, E, F, G, H],
+        tuple[Handle[A], Handle[B], Handle[C], Handle[D], Handle[E], Handle[F], Handle[G], Handle[H]],
+    ]: ...
+
+    @overload
+    @staticmethod
+    def of[A, B, C, D, E, F, G, H, J](
+        a: type[A],
+        b: type[B],
+        c: type[C],
+        d: type[D],
+        e: type[E],
+        f: type[F],
+        g: type[G],
+        h: type[H],
+        j: type[J],
+        /,
+    ) -> tuple[
+        Graph[A, B, C, D, E, F, G, H, J],
+        tuple[Handle[A], Handle[B], Handle[C], Handle[D], Handle[E], Handle[F], Handle[G], Handle[H], Handle[J]],
+    ]: ...
+
+    @overload
+    @staticmethod
+    def of[A, B, C, D, E, F, G, H, J, K](
+        a: type[A],
+        b: type[B],
+        c: type[C],
+        d: type[D],
+        e: type[E],
+        f: type[F],
+        g: type[G],
+        h: type[H],
+        j: type[J],
+        k: type[K],
+        /,
+    ) -> tuple[
+        Graph[A, B, C, D, E, F, G, H, J, K],
+        tuple[
+            Handle[A], Handle[B], Handle[C], Handle[D], Handle[E], Handle[F], Handle[G], Handle[H], Handle[J], Handle[K]
+        ],
+    ]: ...
+    # [[[end]]]
+    @staticmethod
+    def of(*inputs: type[object]) -> tuple[object, ...]:
+        """Open a graph over `inputs`, returning it and a tuple of one `Handle` per entry type."""
+        handles: tuple[Handle[object], ...] = tuple(Handle(object()) for _ in inputs)
+        graph: Graph[*tuple[object, ...]] = Graph(_input_keys=tuple(handle.key for handle in handles))
+        return (graph, handles)
+
+    # [[[cog cog.outl(emit("node")) ]]]
+    @overload
+    def node[T](
+        self,
+        fn: Callable[[], Awaitable[T]],
+        /,
+    ) -> Handle[T]: ...
+
+    @overload
+    def node[T, A](
+        self,
+        fn: Callable[[A], Awaitable[T]],
+        a: Handle[A],
+        /,
+    ) -> Handle[T]: ...
+
+    @overload
+    def node[T, A, B](
+        self,
+        fn: Callable[[A, B], Awaitable[T]],
+        a: Handle[A],
+        b: Handle[B],
+        /,
+    ) -> Handle[T]: ...
+
+    @overload
+    def node[T, A, B, C](
+        self,
+        fn: Callable[[A, B, C], Awaitable[T]],
+        a: Handle[A],
+        b: Handle[B],
+        c: Handle[C],
+        /,
+    ) -> Handle[T]: ...
+
+    @overload
+    def node[T, A, B, C, D](
+        self,
+        fn: Callable[[A, B, C, D], Awaitable[T]],
+        a: Handle[A],
+        b: Handle[B],
+        c: Handle[C],
+        d: Handle[D],
+        /,
+    ) -> Handle[T]: ...
+
+    @overload
+    def node[T, A, B, C, D, E](
+        self,
+        fn: Callable[[A, B, C, D, E], Awaitable[T]],
+        a: Handle[A],
+        b: Handle[B],
+        c: Handle[C],
+        d: Handle[D],
+        e: Handle[E],
+        /,
+    ) -> Handle[T]: ...
+
+    @overload
+    def node[T, A, B, C, D, E, F](
+        self,
+        fn: Callable[[A, B, C, D, E, F], Awaitable[T]],
+        a: Handle[A],
+        b: Handle[B],
+        c: Handle[C],
+        d: Handle[D],
+        e: Handle[E],
+        f: Handle[F],
+        /,
+    ) -> Handle[T]: ...
+
+    @overload
+    def node[T, A, B, C, D, E, F, G](
+        self,
+        fn: Callable[[A, B, C, D, E, F, G], Awaitable[T]],
+        a: Handle[A],
+        b: Handle[B],
+        c: Handle[C],
+        d: Handle[D],
+        e: Handle[E],
+        f: Handle[F],
+        g: Handle[G],
+        /,
+    ) -> Handle[T]: ...
+
+    @overload
+    def node[T, A, B, C, D, E, F, G, H](
+        self,
+        fn: Callable[[A, B, C, D, E, F, G, H], Awaitable[T]],
+        a: Handle[A],
+        b: Handle[B],
+        c: Handle[C],
+        d: Handle[D],
+        e: Handle[E],
+        f: Handle[F],
+        g: Handle[G],
+        h: Handle[H],
+        /,
+    ) -> Handle[T]: ...
+
+    @overload
+    def node[T, A, B, C, D, E, F, G, H, J](
+        self,
+        fn: Callable[[A, B, C, D, E, F, G, H, J], Awaitable[T]],
+        a: Handle[A],
+        b: Handle[B],
+        c: Handle[C],
+        d: Handle[D],
+        e: Handle[E],
+        f: Handle[F],
+        g: Handle[G],
+        h: Handle[H],
+        j: Handle[J],
+        /,
+    ) -> Handle[T]: ...
+
+    @overload
+    def node[T, A, B, C, D, E, F, G, H, J, K](
+        self,
+        fn: Callable[[A, B, C, D, E, F, G, H, J, K], Awaitable[T]],
+        a: Handle[A],
+        b: Handle[B],
+        c: Handle[C],
+        d: Handle[D],
+        e: Handle[E],
+        f: Handle[F],
+        g: Handle[G],
+        h: Handle[H],
+        j: Handle[J],
+        k: Handle[K],
+        /,
+    ) -> Handle[T]: ...
+    # [[[end]]]
+    def node[T](self, fn: Callable[..., Awaitable[T]], *deps: Handle[object]) -> Handle[T]:
+        """
+        Add a node computing `fn` from the handles it depends on, returning its
+        result handle.
+
+        `fn` is called with the dependencies' results as positional arguments in
+        the order their handles are passed. The overloads above tie each handle's
+        type to `fn`'s matching parameter, so a mismatch is a static error.
+        """
+        key = object()
+        dependencies = tuple(dep.key for dep in deps)
+
+        async def run(args: tuple[object, ...]) -> object:
+            return await fn(*args)
+
+        self._nodes.append(Node(key=key, dependencies=dependencies, run=run))
+        return Handle(key)
+
+    def build[Out](self, *, output: Handle[Out], limit: int | None = None) -> CompiledGraph[*Ins, Out]:
+        """
+        Freeze the recorded steps into a callable graph over the graph's inputs.
+
+        The scheduling structure is compiled once here, so running the graph
+        repeats no graph analysis. `limit` caps how many nodes run concurrently;
+        it defaults to `None`, which leaves concurrency unbounded (every ready
+        node runs at once). Pass an integer to cap it when the steps contend for
+        a scarce resource.
+        """
+        if limit is not None and limit < 1:
+            raise ValueError(f"limit must be at least 1 or None, but got {limit}")
+
+        nodes = tuple(self._nodes)
+        return CompiledGraph(
+            nodes=nodes,
+            inputs=self._input_keys,
+            output=output.key,
+            limit=limit,
+            _plan=Plan.of(nodes),
+        )