@senpi/runtime 3.0.9-dev.20260710204324 → 3.0.9-dev.feat-strategy-compos.20260716013009

package/dist/composer/pure_fn/models.py

@@ -0,0 +1,177 @@
+"""models — the per-graph pure-function node (D2 kind 2).
+
+A ``pure_fn`` node is NOT a registry entry. The registry stays the closed vocabulary of
+runtime-owned primitives (D4); ``pure_fn`` is the OPEN extension point — an LLM-written
+Python function with declared, typed input/output ports (drawn from the SAME closed
+:class:`PortType` vocabulary as the registry) and an inline function body. It is declared
+inline in the graph document:
+
+    - id: score_conviction
+      kind: pure_fn
+      inputs:
+        - { name: trend4h, type: feature_map }
+        - { name: momentum, type: feature_map }
+      outputs:
+        - { name: scores, type: score_map }
+      params:
+        - { name: min_score, type: float, default: 5 }
+      fn: |
+        def score_conviction(trend4h, momentum, min_score):
+            ...
+            return scores
+
+The declared ports (``inputs``/``outputs``) are what the graph WIRES against and are
+independent of the ``fn`` body — port typechecking, connectivity, and cycle detection all
+read them exactly as they read a registry NodeDef's ports (see ``resolve`` in
+``composer.pure_fn.interfaces``). The ``fn`` body is STATICALLY purity-checked and its
+signature is required to match ``inputs`` + ``params`` exactly (see
+``composer.pure_fn.purity``); inline ``tests`` are run at validation time
+(``composer.pure_fn.runtests``).
+
+This module only parses the declaration into a typed object and exposes it through the
+same duck-typed surface a registry NodeDef presents (``.name``, ``.kind``, ``.inputs``,
+``.outputs``, ``.summary``), so the validator's graph checks and the compiler can treat a
+pure_fn node like any other node.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import Optional
+
+from composer.registry import NodeKind, Port, PortType
+
+# The pure_fn param-type vocabulary mirrors the registry ParamType literals.
+_PARAM_TYPES = {"int", "float", "str", "bool", "list[str]", "map_str_float"}
+
+
+def is_pure_fn_entry(entry: object) -> bool:
+    """True when a graph node entry declares ``kind: pure_fn`` (the open extension point)."""
+    return isinstance(entry, dict) and entry.get("kind") == "pure_fn"
+
+
+def parse_single_def(src: str) -> Optional[ast.FunctionDef]:
+    """Return the sole top-level ``def`` in ``src`` (ignoring allow-listed imports), else None.
+
+    Purity (``composer.pure_fn.purity``) is what REJECTS a malformed body with a teaching
+    error; this helper is the tolerant reader the compiler uses once a graph is known valid.
+    """
+    try:
+        tree = ast.parse(src)
+    except SyntaxError:
+        return None
+    defs = [n for n in tree.body if isinstance(n, ast.FunctionDef)]
+    return defs[0] if len(defs) == 1 else None
+
+
+@dataclass(frozen=True)
+class PureFnParam:
+    """A typed literal parameter passed to the fn by the compiler (config, not an edge)."""
+
+    name: str
+    type: str
+    default: object = None
+
+
+@dataclass(frozen=True)
+class PureFnNode:
+    """A parsed pure_fn node, presenting the registry-NodeDef duck surface.
+
+    ``inputs``/``outputs`` reuse the registry :class:`Port` model so the validator's
+    existing port/type/connectivity/cycle logic operates on a pure_fn node unchanged.
+    Ports are single-writer, required (``merge=False``, ``required=True``) — a pure_fn
+    declares each typed input explicitly (D2), so there is no feature-merge port here.
+    """
+
+    id: str
+    inputs: tuple[Port, ...]
+    outputs: tuple[Port, ...]
+    params: tuple[PureFnParam, ...]
+    fn_src: str
+    tests: tuple[dict, ...] = ()
+    line: Optional[int] = None
+
+    # -- registry-NodeDef duck surface ------------------------------------------------
+    @property
+    def name(self) -> str:
+        return self.id
+
+    @property
+    def kind(self) -> NodeKind:
+        return NodeKind.pure_fn
+
+    @property
+    def summary(self) -> str:
+        return f"pure_fn node (LLM-written {len(self.inputs)}->{len(self.outputs)} function)"
+
+    # -- fn body ----------------------------------------------------------------------
+    def function_def(self) -> Optional[ast.FunctionDef]:
+        return parse_single_def(self.fn_src)
+
+    @property
+    def fn_name(self) -> Optional[str]:
+        fd = self.function_def()
+        return fd.name if fd is not None else None
+
+
+def _port(entry: dict, *, input_side: bool) -> Optional[Port]:
+    """Build a registry Port from a pure_fn port mapping, or None if the type is not in
+    the closed vocabulary (the schema stage already reports that; we skip it here)."""
+    if not isinstance(entry, dict):
+        return None
+    name = entry.get("name")
+    type_str = entry.get("type")
+    if not isinstance(name, str) or not name.strip():
+        return None
+    try:
+        ptype = PortType(type_str)
+    except ValueError:
+        return None
+    doc = entry.get("doc")
+    if not isinstance(doc, str) or not doc.strip():
+        doc = f"pure_fn {'input' if input_side else 'output'} {name!r}."
+    # pure_fn ports are single-writer, required inputs (no merge point on a pure_fn).
+    return Port(name=name, type=ptype, doc=doc, required=True, merge=False)
+
+
+def parse_pure_fn(entry: dict, line: Optional[int] = None) -> PureFnNode:
+    """Parse a graph node entry (kind: pure_fn) into a :class:`PureFnNode`.
+
+    Tolerant by design — malformed ports/params are dropped (the schema + the purity/test
+    stages carry the teaching errors); this only builds the structure downstream stages
+    walk. Ports whose ``type`` is outside the closed vocabulary are skipped.
+    """
+    node_id = entry.get("id")
+    node_id = node_id if isinstance(node_id, str) else "<pure_fn>"
+
+    inputs = tuple(
+        p for p in (_port(e, input_side=True) for e in (entry.get("inputs") or [])) if p is not None
+    )
+    outputs = tuple(
+        p for p in (_port(e, input_side=False) for e in (entry.get("outputs") or [])) if p is not None
+    )
+
+    params: list[PureFnParam] = []
+    for e in entry.get("params") or []:
+        if not isinstance(e, dict):
+            continue
+        name = e.get("name")
+        ptype = e.get("type")
+        if isinstance(name, str) and ptype in _PARAM_TYPES:
+            params.append(PureFnParam(name=name, type=ptype, default=e.get("default")))
+
+    fn_src = entry.get("fn")
+    fn_src = fn_src if isinstance(fn_src, str) else ""
+
+    tests = tuple(t for t in (entry.get("tests") or []) if isinstance(t, dict))
+
+    return PureFnNode(
+        id=node_id,
+        inputs=inputs,
+        outputs=outputs,
+        params=tuple(params),
+        fn_src=fn_src,
+        tests=tests,
+        line=line,
+    )

package/dist/composer/pure_fn/purity.py

@@ -0,0 +1,311 @@
+"""purity — the static AST gate on a pure_fn body (D2 kind 2; CMP04x teaching errors).
+
+Sandbox MECHANICS are punted for the POC (HLD open question): there is no RestrictedPython
+and no OS sandbox. The one gate is this static AST allowlist, run in the validator BEFORE
+anything executes, so an impure function is refused with a located, fix-hinted teaching
+error rather than doing I/O at runtime. The rules (each its own CMP04x class):
+
+    CMP040  the `fn:` block is not exactly one well-formed top-level `def`
+            (also: reserved / duplicate-across-nodes function name, unsupported construct).
+    CMP041  imports a module outside the allowlist — only `math` and `statistics`.
+    CMP042  uses a disallowed builtin or reflection escape (open/exec/eval/__import__/
+            getattr/print/... or any dunder attribute access like `x.__globals__`).
+    CMP043  references a forbidden or undeclared NAME (`ctx`, `senpi_mcp`, an un-imported
+            module, an external global) — this is where a ctx/MCP reference is caught.
+    CMP044  the function signature does not match the declared input ports + params.
+    CMP045  the function does not return its declared outputs (arity mismatch).
+    CMP046  writes global/nonlocal state (a `global`/`nonlocal` statement).
+
+Purity is checked against the DECLARED ports/params, not the wired graph, so it is a
+property of the node alone and reproducible in isolation (the fixture unit-test story).
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import Optional
+
+from composer.validator.errors import Location, TeachingError
+
+from .models import PureFnNode
+
+# Only these two modules may be imported by a pure_fn body (POC allowlist).
+ALLOWED_MODULES = frozenset({"math", "statistics"})
+
+# Builtins a pure_fn MAY reference. Deliberately small — pure numeric/collection work only.
+SAFE_BUILTINS = frozenset({
+    "abs", "all", "any", "bool", "dict", "divmod", "enumerate", "filter", "float",
+    "frozenset", "int", "len", "list", "map", "max", "min", "pow", "range", "reversed",
+    "round", "set", "sorted", "str", "sum", "tuple", "zip", "isinstance",
+})
+
+# Builtins whose mere reference is an escape hatch (I/O, dynamic eval, reflection).
+DANGEROUS_BUILTINS = frozenset({
+    "open", "exec", "eval", "compile", "__import__", "input", "globals", "locals",
+    "vars", "getattr", "setattr", "delattr", "hasattr", "dir", "memoryview",
+    "breakpoint", "exit", "quit", "help", "print", "__builtins__",
+})
+
+# Names a pure_fn's function may NOT take, because the emitted scan.py binds them for the
+# primitives/scaffold surface (a pure_fn def is emitted nested inside scan()).
+RESERVED_FN_NAMES = frozenset({
+    "scan", "inputs", "ctx", "src", "time", "base_universe", "make_adapter",
+    "emitters", "filters", "indicators", "rankers", "scorers", "sources", "stateful",
+    "math", "statistics",
+})
+
+
+def _err(code: str, message: str, fix_hint: str, node_id: str, line: Optional[int]) -> TeachingError:
+    return TeachingError(
+        code=code, message=message, fix_hint=fix_hint,
+        location=Location(node=node_id, line=line),
+    )
+
+
+def _bound_names(fn: ast.FunctionDef) -> set[str]:
+    """Every name bound anywhere in the function (params, assignments, loops, imports,
+    comprehensions, except-as, nested defs/lambdas + their args) plus the fn's own name."""
+    bound: set[str] = {fn.name}
+
+    def add_args(args: ast.arguments) -> None:
+        for a in (*args.posonlyargs, *args.args, *args.kwonlyargs):
+            bound.add(a.arg)
+        if args.vararg:
+            bound.add(args.vararg.arg)
+        if args.kwarg:
+            bound.add(args.kwarg.arg)
+
+    add_args(fn.args)
+    for node in ast.walk(fn):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            if node is not fn:
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    bound.add(node.name)
+                add_args(node.args)
+        elif isinstance(node, ast.Name) and isinstance(node.ctx, (ast.Store, ast.Del)):
+            bound.add(node.id)
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            for alias in node.names:
+                bound.add((alias.asname or alias.name).split(".")[0])
+        elif isinstance(node, ast.ExceptHandler) and node.name:
+            bound.add(node.name)
+        elif isinstance(node, (ast.comprehension,)):
+            for t in ast.walk(node.target):
+                if isinstance(t, ast.Name):
+                    bound.add(t.id)
+    return bound
+
+
+def _check_signature(fn: ast.FunctionDef, pfn: PureFnNode, errors: list, line) -> None:
+    a = fn.args
+    expected = [p.name for p in pfn.inputs] + [p.name for p in pfn.params]
+    got = [arg.arg for arg in (*a.posonlyargs, *a.args)]
+    extra = []
+    if a.vararg:
+        extra.append("*" + a.vararg.arg)
+    if a.kwarg:
+        extra.append("**" + a.kwarg.arg)
+    for kw in a.kwonlyargs:
+        extra.append(kw.arg)
+    if got != expected or extra:
+        errors.append(_err(
+            "CMP044",
+            f"pure_fn {pfn.id!r} signature is ({', '.join(got + extra) or ''}) but its "
+            f"declared inputs+params require ({', '.join(expected)}).",
+            f"Write `def {fn.name}({', '.join(expected)}):` — the parameters must be exactly "
+            f"the declared input ports then the params, in order, with no *args/**kwargs.",
+            pfn.id, line,
+        ))
+
+
+def _check_returns(fn: ast.FunctionDef, pfn: PureFnNode, errors: list, line) -> None:
+    n_out = len(pfn.outputs)
+    value_returns = [
+        n for n in ast.walk(fn)
+        if isinstance(n, ast.Return) and n.value is not None
+    ]
+    out_names = ", ".join(p.name for p in pfn.outputs)
+    if not value_returns:
+        errors.append(_err(
+            "CMP045",
+            f"pure_fn {pfn.id!r} never returns a value but declares output(s) ({out_names}).",
+            f"End the function with `return {out_names}` producing its declared output(s).",
+            pfn.id, line,
+        ))
+        return
+    for ret in value_returns:
+        is_tuple = isinstance(ret.value, ast.Tuple)
+        if n_out == 1 and is_tuple and len(ret.value.elts) != 1:
+            errors.append(_err(
+                "CMP045",
+                f"pure_fn {pfn.id!r} returns {len(ret.value.elts)} values but declares 1 "
+                f"output ({out_names}).",
+                f"Return a single {out_names} value, not a tuple.",
+                pfn.id, line,
+            ))
+            return
+        if n_out > 1:
+            if not is_tuple:
+                errors.append(_err(
+                    "CMP045",
+                    f"pure_fn {pfn.id!r} declares {n_out} outputs ({out_names}) but a return "
+                    f"does not return a tuple of {n_out} values.",
+                    f"Return a {n_out}-tuple `return {out_names}` matching the declared outputs.",
+                    pfn.id, line,
+                ))
+                return
+            if len(ret.value.elts) != n_out:
+                errors.append(_err(
+                    "CMP045",
+                    f"pure_fn {pfn.id!r} returns {len(ret.value.elts)} values but declares "
+                    f"{n_out} outputs ({out_names}).",
+                    f"Return exactly {n_out} values `return {out_names}`.",
+                    pfn.id, line,
+                ))
+                return
+
+
+def check_purity(pfn: PureFnNode, used_fn_names: set[str]) -> list[TeachingError]:
+    """Return every purity teaching error for one pure_fn node (empty == pure).
+
+    ``used_fn_names`` accumulates function names already claimed by earlier pure_fn nodes,
+    so a duplicate name (which would shadow in the shared emitted scan.py) is a CMP040.
+    """
+    errors: list[TeachingError] = []
+    line = pfn.line
+
+    if not pfn.fn_src.strip():
+        errors.append(_err(
+            "CMP040", f"pure_fn {pfn.id!r} has no `fn:` function body.",
+            "Add an `fn:` block containing exactly one top-level `def`.", pfn.id, line,
+        ))
+        return errors
+    if not pfn.outputs:
+        errors.append(_err(
+            "CMP040", f"pure_fn {pfn.id!r} declares no `outputs:`.",
+            "Declare at least one typed output port under `outputs:`.", pfn.id, line,
+        ))
+
+    try:
+        tree = ast.parse(pfn.fn_src)
+    except SyntaxError as exc:
+        errors.append(_err(
+            "CMP040", f"pure_fn {pfn.id!r} body is not valid Python: {exc.msg}.",
+            "Fix the syntax; the `fn:` block must be one well-formed `def`.", pfn.id, line,
+        ))
+        return errors
+
+    defs = [n for n in tree.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))]
+    others = [
+        n for n in tree.body
+        if not isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Import, ast.ImportFrom))
+    ]
+    if others:
+        errors.append(_err(
+            "CMP040", f"pure_fn {pfn.id!r} body has top-level code outside its `def`.",
+            "The `fn:` block must be exactly one `def` (plus, at most, allow-listed imports).",
+            pfn.id, line,
+        ))
+    if len(defs) != 1 or isinstance(defs[0], ast.AsyncFunctionDef):
+        errors.append(_err(
+            "CMP040",
+            f"pure_fn {pfn.id!r} must contain exactly one synchronous top-level `def` "
+            f"(found {len(defs)}).",
+            "Write a single plain `def name(...):` (no `async def`, no extra defs).",
+            pfn.id, line,
+        ))
+        return errors
+
+    fn = defs[0]
+    if fn.name in RESERVED_FN_NAMES:
+        errors.append(_err(
+            "CMP040",
+            f"pure_fn {pfn.id!r} function name {fn.name!r} is reserved by the emitted scan.py.",
+            f"Rename the function (reserved: sorted({sorted(RESERVED_FN_NAMES)[:4]})... and the "
+            f"primitive modules).",
+            pfn.id, line,
+        ))
+    elif fn.name in used_fn_names:
+        errors.append(_err(
+            "CMP040",
+            f"pure_fn {pfn.id!r} function name {fn.name!r} is already used by another pure_fn.",
+            "Give each pure_fn a distinct function name so they do not collide in scan.py.",
+            pfn.id, line,
+        ))
+    used_fn_names.add(fn.name)
+
+    _check_signature(fn, pfn, errors, line)
+    _check_returns(fn, pfn, errors, line)
+
+    bound = _bound_names(fn)
+
+    for node in ast.walk(fn):
+        # imports (anywhere) — allowlist only
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name.split(".")[0] not in ALLOWED_MODULES:
+                    errors.append(_err(
+                        "CMP041",
+                        f"pure_fn {pfn.id!r} imports {alias.name!r}, which is not allowed.",
+                        f"A pure_fn may import only {sorted(ALLOWED_MODULES)} — remove this import.",
+                        pfn.id, line,
+                    ))
+        elif isinstance(node, ast.ImportFrom):
+            if (node.module or "").split(".")[0] not in ALLOWED_MODULES:
+                errors.append(_err(
+                    "CMP041",
+                    f"pure_fn {pfn.id!r} imports from {node.module!r}, which is not allowed.",
+                    f"A pure_fn may import only {sorted(ALLOWED_MODULES)} — remove this import.",
+                    pfn.id, line,
+                ))
+        # global / nonlocal writes
+        elif isinstance(node, (ast.Global, ast.Nonlocal)):
+            kw = "global" if isinstance(node, ast.Global) else "nonlocal"
+            errors.append(_err(
+                "CMP046",
+                f"pure_fn {pfn.id!r} uses `{kw}` — a pure_fn may not write outside its own scope.",
+                f"Remove the `{kw}` statement; compute and `return` values instead.",
+                pfn.id, line,
+            ))
+        # generators / awaits are not pure straight-line functions
+        elif isinstance(node, (ast.Yield, ast.YieldFrom, ast.Await)):
+            errors.append(_err(
+                "CMP042",
+                f"pure_fn {pfn.id!r} uses a generator/await construct.",
+                "A pure_fn must be a plain synchronous function that returns a value.",
+                pfn.id, line,
+            ))
+        # dunder attribute access (reflection escape: x.__globals__ / ().__class__)
+        elif isinstance(node, ast.Attribute):
+            if node.attr.startswith("__") and node.attr.endswith("__"):
+                errors.append(_err(
+                    "CMP042",
+                    f"pure_fn {pfn.id!r} accesses dunder attribute {node.attr!r} (reflection escape).",
+                    "Remove the dunder attribute access; a pure_fn may not reach runtime internals.",
+                    pfn.id, line,
+                ))
+        # name loads
+        elif isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+            n = node.id
+            if n in bound or n in SAFE_BUILTINS or n in ALLOWED_MODULES:
+                continue
+            if n in DANGEROUS_BUILTINS:
+                errors.append(_err(
+                    "CMP042",
+                    f"pure_fn {pfn.id!r} uses the disallowed builtin {n!r} (I/O or dynamic execution).",
+                    f"Remove {n!r}; a pure_fn may only do numeric/collection work "
+                    f"(no I/O, no eval/exec/import).",
+                    pfn.id, line,
+                ))
+            else:
+                errors.append(_err(
+                    "CMP043",
+                    f"pure_fn {pfn.id!r} references undeclared name {n!r} "
+                    f"(no ctx/MCP/I/O and no external globals are available).",
+                    f"A pure_fn sees only its parameters ({', '.join(a.arg for a in fn.args.args)}), "
+                    f"locals, {sorted(ALLOWED_MODULES)}, and safe builtins — declare {n!r} as an "
+                    f"input port or compute it locally.",
+                    pfn.id, line,
+                ))
+
+    return errors

package/dist/composer/pure_fn/runtests.py

@@ -0,0 +1,155 @@
+"""runtests — run a pure_fn's inline fixture tests at validation time (CMP05x).
+
+A pure_fn node may carry inline ``tests:`` — a list of ``{name, inputs, expect}`` fixture
+cases. Because a pure_fn is pure by construction (statically enforced in
+``composer.pure_fn.purity``), a failing unit test is a DEFECT IN THE FUNCTION, catchable
+before deploy — so the validator RUNS the cases (same-process, the POC decision) and
+turns any failure into a teaching error:
+
+    CMP050  a case produced the wrong output (shows expected vs got).
+    CMP051  a case raised an exception when run.
+    CMP052  a case is malformed (does not bind a required arg, or names an unknown output).
+
+Execution is only reached AFTER purity passes for the node, so the body is already known
+to touch nothing but its parameters, ``math``/``statistics``, and safe builtins. We still
+exec it under a restricted ``__builtins__`` (the same allowlist) so the test harness cannot
+accidentally widen what the function can do.
+"""
+
+from __future__ import annotations
+
+import builtins as _builtins
+import math
+import statistics
+from typing import Optional
+
+from composer.validator.errors import Location, TeachingError
+
+from .models import PureFnNode
+from .purity import SAFE_BUILTINS
+
+
+def _safe_import(name, *_a, **_k):
+    if name in ("math", "statistics"):
+        return __import__(name)
+    raise ImportError(f"pure_fn may not import {name!r}")
+
+
+def _safe_namespace() -> dict:
+    safe = {n: getattr(_builtins, n) for n in SAFE_BUILTINS if hasattr(_builtins, n)}
+    safe["__import__"] = _safe_import
+    return {"__builtins__": safe, "math": math, "statistics": statistics}
+
+
+def _short(value) -> str:
+    text = repr(value)
+    return text if len(text) <= 200 else text[:197] + "..."
+
+
+def run_inline_tests(pfn: PureFnNode) -> list[TeachingError]:
+    """Run every inline test for one (already-pure) pure_fn node; return teaching errors."""
+    if not pfn.tests:
+        return []
+
+    fd = pfn.function_def()
+    if fd is None:  # pragma: no cover - purity guarantees a def by the time we run
+        return []
+
+    ns = _safe_namespace()
+    try:
+        exec(compile(pfn.fn_src, f"<pure_fn {pfn.id}>", "exec"), ns)  # noqa: S102 - purity-gated
+    except Exception as exc:  # noqa: BLE001
+        return [TeachingError(
+            code="CMP051",
+            message=f"pure_fn {pfn.id!r} body failed to load for testing: {exc!r}.",
+            fix_hint="Fix the function body so it defines cleanly.",
+            location=Location(node=pfn.id, line=pfn.line),
+        )]
+    fn = ns.get(fd.name)
+
+    sig_names = [p.name for p in pfn.inputs] + [p.name for p in pfn.params]
+    param_defaults = {p.name: p.default for p in pfn.params}
+    out_names = [p.name for p in pfn.outputs]
+
+    errors: list[TeachingError] = []
+    for i, case in enumerate(pfn.tests):
+        name = case.get("name", f"#{i + 1}")
+        loc = Location(node=pfn.id, line=pfn.line)
+        given = case.get("inputs") or {}
+        expect = case.get("expect")
+
+        if not isinstance(given, dict) or not isinstance(expect, dict):
+            errors.append(TeachingError(
+                code="CMP052",
+                message=f"pure_fn {pfn.id!r} test {name!r} is malformed (needs mapping `inputs`/`expect`).",
+                fix_hint="Give the test `inputs:` (a mapping of port/param -> value) and `expect:` "
+                         "(a mapping of output-port -> expected value).",
+                location=loc,
+            ))
+            continue
+
+        if set(expect) != set(out_names):
+            errors.append(TeachingError(
+                code="CMP052",
+                message=f"pure_fn {pfn.id!r} test {name!r} `expect:` keys {sorted(expect)} "
+                        f"are not the declared outputs {out_names}.",
+                fix_hint=f"`expect:` must have exactly the output-port keys {out_names}.",
+                location=loc,
+            ))
+            continue
+
+        try:
+            args = []
+            for arg_name in sig_names:
+                if arg_name in given:
+                    args.append(given[arg_name])
+                elif arg_name in param_defaults:
+                    args.append(param_defaults[arg_name])
+                else:
+                    raise KeyError(arg_name)
+        except KeyError as missing:
+            errors.append(TeachingError(
+                code="CMP052",
+                message=f"pure_fn {pfn.id!r} test {name!r} does not bind required argument {missing}.",
+                fix_hint=f"Provide a value for {missing} under the test's `inputs:` "
+                         f"(signature: {sig_names}).",
+                location=loc,
+            ))
+            continue
+
+        try:
+            result = fn(*args)
+        except Exception as exc:  # noqa: BLE001
+            errors.append(TeachingError(
+                code="CMP051",
+                message=f"pure_fn {pfn.id!r} test {name!r} raised {exc!r}.",
+                fix_hint="Make the function handle this input without raising (guard missing keys, "
+                         "empty series, division by zero, etc.).",
+                location=loc,
+            ))
+            continue
+
+        if len(out_names) == 1:
+            actual = {out_names[0]: result}
+        else:
+            if not isinstance(result, (tuple, list)) or len(result) != len(out_names):
+                errors.append(TeachingError(
+                    code="CMP050",
+                    message=f"pure_fn {pfn.id!r} test {name!r} returned {_short(result)}, "
+                            f"expected {len(out_names)} outputs {out_names}.",
+                    fix_hint=f"Return a {len(out_names)}-tuple matching {out_names}.",
+                    location=loc,
+                ))
+                continue
+            actual = dict(zip(out_names, result))
+
+        if actual != expect:
+            errors.append(TeachingError(
+                code="CMP050",
+                message=f"pure_fn {pfn.id!r} test {name!r} failed: expected {_short(expect)}, "
+                        f"got {_short(actual)}.",
+                fix_hint="Fix the function (or the expected value) so this fixture case passes.",
+                location=loc,
+            ))
+
+    return errors

package/dist/composer/registry/__init__.py

@@ -0,0 +1,40 @@
+"""registry — the node registry, single source of truth for the whole composer (D4, D8).
+
+Every node the composer knows is declared here once as a pydantic model carrying its
+name, typed input/output ports, parameter schema, docstring, example snippet, and cost
+note. The JSON Schema for the graph format, the ~1-2k-token catalog index, the per-node
+``describe`` text, the validator's type rules, and the compiler's emission all derive
+from these models, so none of them can drift and a registry entry with a bogus port type
+fails at model construction rather than at use. This closed world is what lets the agent
+know authoritatively what is possible: an unknown node becomes a precise validator
+refusal and feasibility is checkable at interview time. (Populated in slice 1 with the
+primitive subset the POC graphs need — sources, indicators, filters, rankers, emitters.)
+
+Public API:
+    models   — NodeDef / Port / Param / PortType / NodeKind and the construction validators.
+    nodes    — NODES (the 26 corpus primitives), NODES_BY_NAME, sorted_nodes(), KIND_ORDER.
+    generate — deterministic artifact generation (JSON Schema + catalog + describe).
+"""
+
+from .models import (
+    SCHEMA_VERSION,
+    NodeDef,
+    NodeKind,
+    Param,
+    Port,
+    PortType,
+)
+from .nodes import KIND_ORDER, NODES, NODES_BY_NAME, sorted_nodes
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "NodeDef",
+    "NodeKind",
+    "Param",
+    "Port",
+    "PortType",
+    "KIND_ORDER",
+    "NODES",
+    "NODES_BY_NAME",
+    "sorted_nodes",
+]