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

package/dist/composer/authoring/builder.py

@@ -0,0 +1,191 @@
+"""builder — construct a strategy graph from the SAME registry types (D7 step 2).
+
+Archetype templates are CODE, not YAML-with-holes: they call this builder, which resolves
+every node against the registry (``NODES_BY_NAME``) and every edge port against the node's
+declared ``Port``s. A template that names a nonexistent node raises ``KeyError`` at
+``add()``; a template that wires a nonexistent port raises ``ValueError`` at ``connect()``.
+Both fire at construction time, so "construct every archetype and validate its output" (the
+CI test) is a hard guarantee that a template can never drift from the vocabulary — the
+build-guide's archetype table cannot rot the way an 83-package clone corpus did.
+
+A :class:`GraphBuilder` accumulates an ORDERED node list and edge list plus presentation
+metadata (per-node header comments, per-param TODO-slot comments, edge section labels, and
+which node is the scoring "edge anchor"). ``composer.authoring.emit`` turns that into the
+teaching YAML. The builder itself emits nothing and interprets no edge text — it only
+guarantees structural validity against the registry.
+
+pure_fn nodes (D2 kind 2) are added via :meth:`add_pure_fn`; their declared inputs/outputs
+are validated as ports here too, so wiring against a pure_fn is checked identically to a
+primitive.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from composer.registry import NODES_BY_NAME, Port, PortType
+
+
+@dataclass
+class BuiltNode:
+    """One node in the builder's ordered list (primitive or pure_fn)."""
+
+    id: str
+    node: Optional[str] = None            # registry node name (primitive)
+    kind: Optional[str] = None            # "pure_fn" or None
+    params: dict = field(default_factory=dict)      # `with:` values (primitive)
+    # pure_fn payload
+    inputs: tuple[dict, ...] = ()
+    outputs: tuple[dict, ...] = ()
+    pure_params: tuple[dict, ...] = ()
+    fn: Optional[str] = None
+    tests: tuple[dict, ...] = ()
+    # presentation
+    header: tuple[str, ...] = ()          # comment lines emitted above the node
+    param_comments: dict = field(default_factory=dict)   # param -> trailing comment
+    slot_params: tuple[str, ...] = ()     # params that are TODO(edit) slots
+
+    def out_ports(self) -> set[str]:
+        if self.kind == "pure_fn":
+            return {p["name"] for p in self.outputs}
+        return {p.name for p in NODES_BY_NAME[self.node].outputs}
+
+    def in_ports(self) -> set[str]:
+        if self.kind == "pure_fn":
+            return {p["name"] for p in self.inputs}
+        return {p.name for p in NODES_BY_NAME[self.node].inputs}
+
+
+@dataclass
+class BuiltEdge:
+    frm: str        # "node_id.port"
+    to: str         # "node_id.port"
+    section: Optional[str] = None   # comment line emitted before this edge (a group label)
+
+
+class GraphBuilder:
+    """Accumulates nodes + edges against the registry; the archetype templates' one API."""
+
+    def __init__(self) -> None:
+        self._nodes: list[BuiltNode] = []
+        self._edges: list[BuiltEdge] = []
+        self._by_id: dict[str, BuiltNode] = {}
+        self.edge_anchor: Optional[str] = None   # node the EDGE comment block sits above
+
+    # ------------------------------------------------------------------ node construction
+    def add(
+        self,
+        node_id: str,
+        node: str,
+        params: Optional[dict] = None,
+        *,
+        header: tuple[str, ...] = (),
+        param_comments: Optional[dict] = None,
+        slots: tuple[str, ...] = (),
+    ) -> "GraphBuilder":
+        """Add a primitive node. ``KeyError`` if ``node`` is not in the registry; a param
+        naming a key the node does not declare is a ``ValueError`` (CI catches template drift)."""
+        nd = NODES_BY_NAME[node]                     # KeyError = nonexistent node -> CI fail
+        params = dict(params or {})
+        declared = {p.name for p in nd.params}
+        for key in params:
+            if key not in declared:
+                raise ValueError(
+                    f"archetype template error: node {node_id!r} ({node}) sets unknown "
+                    f"param {key!r} (declared: {sorted(declared)})"
+                )
+        self._register(
+            BuiltNode(
+                id=node_id,
+                node=node,
+                params=params,
+                header=tuple(header),
+                param_comments=dict(param_comments or {}),
+                slot_params=tuple(slots),
+            )
+        )
+        return self
+
+    def add_pure_fn(
+        self,
+        node_id: str,
+        *,
+        inputs: tuple[dict, ...],
+        outputs: tuple[dict, ...],
+        params: tuple[dict, ...],
+        fn: str,
+        tests: tuple[dict, ...] = (),
+        header: tuple[str, ...] = (),
+    ) -> "GraphBuilder":
+        """Add a per-graph pure_fn node (D2 kind 2). Its declared ports must use the closed
+        PortType vocabulary — a bad type is a ``ValueError`` (CI catches template drift)."""
+        for side, ports in (("input", inputs), ("output", outputs)):
+            for p in ports:
+                try:
+                    PortType(p["type"])
+                except ValueError as exc:
+                    raise ValueError(
+                        f"archetype template error: pure_fn {node_id!r} {side} port "
+                        f"{p.get('name')!r} has bad type {p.get('type')!r}"
+                    ) from exc
+        self._register(
+            BuiltNode(
+                id=node_id,
+                kind="pure_fn",
+                inputs=tuple(inputs),
+                outputs=tuple(outputs),
+                pure_params=tuple(params),
+                fn=fn,
+                tests=tuple(tests),
+                header=tuple(header),
+            )
+        )
+        return self
+
+    def connect(
+        self, frm_id: str, frm_port: str, to_id: str, to_port: str, *, section: Optional[str] = None
+    ) -> "GraphBuilder":
+        """Wire ``frm_id.frm_port`` -> ``to_id.to_port``, validating both ports exist.
+
+        A port the node does not declare is a ``ValueError`` here (construction time), so a
+        template can never emit a graph that references a nonexistent port — the CI guarantee.
+        """
+        frm = self._by_id.get(frm_id)
+        to = self._by_id.get(to_id)
+        if frm is None:
+            raise ValueError(f"archetype template error: edge from unknown node {frm_id!r}")
+        if to is None:
+            raise ValueError(f"archetype template error: edge to unknown node {to_id!r}")
+        if frm_port not in frm.out_ports():
+            raise ValueError(
+                f"archetype template error: node {frm_id!r} has no output port {frm_port!r} "
+                f"(has: {sorted(frm.out_ports())})"
+            )
+        if to_port not in to.in_ports():
+            raise ValueError(
+                f"archetype template error: node {to_id!r} has no input port {to_port!r} "
+                f"(has: {sorted(to.in_ports())})"
+            )
+        self._edges.append(BuiltEdge(frm=f"{frm_id}.{frm_port}", to=f"{to_id}.{to_port}", section=section))
+        return self
+
+    def set_edge_anchor(self, node_id: str) -> "GraphBuilder":
+        """Mark the scoring node above which the verbatim EDGE comment block is emitted."""
+        self.edge_anchor = node_id
+        return self
+
+    # ------------------------------------------------------------------ accessors
+    @property
+    def nodes(self) -> list[BuiltNode]:
+        return list(self._nodes)
+
+    @property
+    def edges(self) -> list[BuiltEdge]:
+        return list(self._edges)
+
+    def _register(self, node: BuiltNode) -> None:
+        if node.id in self._by_id:
+            raise ValueError(f"archetype template error: duplicate node id {node.id!r}")
+        self._nodes.append(node)
+        self._by_id[node.id] = node

package/dist/composer/authoring/emit.py

@@ -0,0 +1,264 @@
+"""emit — render a built graph into teaching YAML (D7 step 3; the machine-generated anchor).
+
+The emitted graph must be a COMPLETE, VALID, COMPILING artifact before any edit (the
+zero-edit oracle), and it must teach in place so a small model can move it toward the edge
+by editing marked slots only (D7). This renderer therefore does three things beyond dumping
+data:
+
+  * slot comments — every bespoke slot (weights, thresholds, fn bodies) carries a
+    ``# TODO(edit): ...`` comment in the hand-written examples' voice, WITH a working
+    default already in place so the graph validates and compiles unedited.
+  * verbatim edge — the user's EDGE free-text is emitted as a comment block directly above
+    the scoring slot; the machine never interprets it (that is the model's only job).
+  * content marker — a ``metadata.generated.content_hash`` over the emitted text (with the
+    hash field itself blanked). ``composer new`` uses it for no-clobber: an unchanged file
+    re-hashes to its stored marker (regenerable), an edited one does not (refused; D7 step 5).
+
+Determinism is a hard property (the byte-identical oracle): the renderer is a pure function
+of the builder + answers, emits dicts/lists in a fixed order, and carries no timestamps.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+from .answers import Answers
+from .builder import BuiltNode, GraphBuilder
+
+_HASH_PLACEHOLDER = "0" * 64
+_HASH_RE = re.compile(r'(content_hash: ")([0-9a-f]{64})(")')
+
+_PLAIN_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_.-]*$")
+_YAML_KEYWORDS = {"true", "false", "null", "yes", "no", "on", "off", "~"}
+
+
+# --------------------------------------------------------------------------- scalars
+
+def _dq(s: str) -> str:
+    escaped = s.replace("\\", "\\\\").replace('"', '\\"')
+    escaped = escaped.replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
+    return '"' + escaped + '"'
+
+
+def _plain_ok(s: str) -> bool:
+    return bool(_PLAIN_RE.match(s)) and s.lower() not in _YAML_KEYWORDS
+
+
+def _float(v: float) -> str:
+    """Render a float so PyYAML parses it back as a float (D6: YAML authored, JSON canonical).
+
+    PyYAML's implicit float resolver requires a decimal point in the mantissa, so bare
+    scientific notation (``repr(1e-7) == '1e-07'``) round-trips as a STRING and fails schema
+    typing. Insert the missing ``.0`` into the mantissa (e.g. ``1e-07`` -> ``1.0e-07``).
+    """
+    s = repr(v)
+    if "e" in s or "E" in s:
+        mant, _, exp = s.replace("E", "e").partition("e")
+        if "." not in mant:
+            mant += ".0"
+        return f"{mant}e{exp}"
+    return s
+
+
+def _scalar(v) -> str:
+    """A single YAML scalar. Strings are emitted plain when unambiguous, else double-quoted;
+    types like ``list[str]`` (which carry brackets) fall to the quoted branch automatically."""
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, int):
+        return str(v)
+    if isinstance(v, float):
+        return _float(v)
+    s = str(v)
+    return s if _plain_ok(s) else _dq(s)
+
+
+def _inline(v) -> str:
+    """A value in YAML flow style (used for `with:` params, ports, and leaf test maps).
+
+    Strings are always quoted here (matches the hand-written examples' `dex: "xyz"` /
+    `interval: "4h"` aesthetic); numbers/bools bare; dicts/lists recurse in flow style.
+    """
+    if isinstance(v, dict):
+        if not v:
+            return "{}"
+        items = [f"{_key(k)}: {_inline(val)}" for k, val in v.items()]
+        return "{ " + ", ".join(items) + " }"
+    if isinstance(v, (list, tuple)):
+        if not v:
+            return "[]"
+        return "[" + ", ".join(_inline(x) for x in v) + "]"
+    if isinstance(v, str):
+        return _dq(v)
+    return _scalar(v)
+
+
+def _key(k) -> str:
+    ks = str(k)
+    return ks if _plain_ok(ks) else _dq(ks)
+
+
+# --------------------------------------------------------------------------- block emitter
+
+def _emit_kv(key, value, indent: int) -> list[str]:
+    """Emit `key: value` in block style; dicts recurse, scalar-lists inline, and lists of
+    mappings become `- ` items. Used for metadata and pure_fn inline tests."""
+    pad = " " * indent
+    if isinstance(value, dict):
+        if not value:
+            return [f"{pad}{_key(key)}: {{}}"]
+        out = [f"{pad}{_key(key)}:"]
+        for k, v in value.items():
+            out.extend(_emit_kv(k, v, indent + 2))
+        return out
+    if isinstance(value, (list, tuple)):
+        if not value:
+            return [f"{pad}{_key(key)}: []"]
+        if all(_is_scalar(x) for x in value):
+            return [f"{pad}{_key(key)}: {_inline(list(value))}"]
+        out = [f"{pad}{_key(key)}:"]
+        for item in value:
+            item_lines: list[str] = []
+            for k, v in item.items():
+                item_lines.extend(_emit_kv(k, v, indent + 4))
+            out.append(f"{pad}  - " + item_lines[0].strip())
+            out.extend(item_lines[1:])
+        return out
+    return [f"{pad}{_key(key)}: {_scalar(value)}"]
+
+
+def _is_scalar(x) -> bool:
+    return x is None or isinstance(x, (str, int, float, bool))
+
+
+# --------------------------------------------------------------------------- ports/params
+
+def _inline_port(p: dict) -> str:
+    return f"{{ name: {_scalar(p['name'])}, type: {_scalar(p['type'])}, doc: {_dq(p.get('doc', ''))} }}"
+
+
+def _inline_pure_param(p: dict) -> str:
+    parts = [f"name: {_scalar(p['name'])}", f"type: {_scalar(p['type'])}"]
+    if "default" in p:
+        parts.append(f"default: {_inline(p['default'])}")
+    parts.append(f"doc: {_dq(p.get('doc', ''))}")
+    return "{ " + ", ".join(parts) + " }"
+
+
+# --------------------------------------------------------------------------- node emitter
+
+def _emit_node(bn: BuiltNode) -> list[str]:
+    lines: list[str] = []
+    for h in bn.header:
+        lines.append(f"  # {h}")
+    lines.append(f"  - id: {bn.id}")
+
+    if bn.kind == "pure_fn":
+        lines.append("    kind: pure_fn")
+        lines.append("    inputs:")
+        for p in bn.inputs:
+            lines.append(f"      - {_inline_port(p)}")
+        lines.append("    outputs:")
+        for p in bn.outputs:
+            lines.append(f"      - {_inline_port(p)}")
+        if bn.pure_params:
+            lines.append("    params:")
+            for p in bn.pure_params:
+                lines.append(f"      - {_inline_pure_param(p)}")
+        lines.append("    fn: |")
+        for fl in (bn.fn or "").rstrip("\n").split("\n"):
+            lines.append(f"      {fl}" if fl.strip() else "")
+        if bn.tests:
+            for line in _emit_kv("tests", list(bn.tests), 4):
+                lines.append(line)
+        return lines
+
+    lines.append(f"    node: {bn.node}")
+    if bn.params:
+        lines.append("    with:")
+        for k, v in bn.params.items():
+            line = f"      {_key(k)}: {_inline(v)}"
+            comment = bn.param_comments.get(k)
+            if comment:
+                line += f"   # {comment}"
+            lines.append(line)
+    return lines
+
+
+# --------------------------------------------------------------------------- driver
+
+def render(builder: GraphBuilder, answers: Answers, banner: list[str]) -> str:
+    """Render the built graph to teaching YAML text with a stamped content hash."""
+    lines: list[str] = []
+    for b in banner:
+        lines.append(f"# {b}" if b else "#")
+    lines.append("")
+    lines.append("version: 1")
+    lines.append("")
+
+    # --- metadata (D7: the spec file IS the state — answers live here) ---
+    lines.append("metadata:")
+    meta = {
+        "archetype": answers.archetype,
+        "strategy": answers.strategy,
+        "generated": {"by": "composer new", "content_hash": _HASH_PLACEHOLDER},
+        "answers": answers.metadata_block(),
+    }
+    for k, v in meta.items():
+        lines.extend(_emit_kv(k, v, 2))
+    if answers.edge:
+        lines.append(
+            f"  # EDGE (verbatim, machine never interprets): {_dq(answers.edge)}"
+        )
+    lines.append("")
+
+    # --- nodes ---
+    lines.append("nodes:")
+    for bn in builder.nodes:
+        if builder.edge_anchor == bn.id and answers.edge:
+            lines.append("  # ---------------------------------------------------------------")
+            lines.append("  # EDGE (verbatim — the machine did NOT interpret this; encode it")
+            lines.append("  # by editing the TODO slots on this scoring node):")
+            for eline in answers.edge.split("\n"):
+                lines.append(f"  #   {eline}")
+            lines.append("  # ---------------------------------------------------------------")
+        lines.extend(_emit_node(bn))
+    lines.append("")
+
+    # --- edges ---
+    lines.append("edges:")
+    for e in builder.edges:
+        if e.section:
+            lines.append(f"  # {e.section}")
+        lines.append(f"  - {{ from: {e.frm}, to: {e.to} }}")
+
+    text = "\n".join(ln.rstrip() for ln in lines).rstrip("\n") + "\n"
+    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
+    return text.replace(_HASH_PLACEHOLDER, digest, 1)
+
+
+# --------------------------------------------------------------------------- no-clobber
+
+def stored_hash(text: str):
+    """The content_hash marker in an emitted file, or None if it carries none."""
+    m = _HASH_RE.search(text)
+    return m.group(2) if m else None
+
+
+def is_unedited_generated(text: str):
+    """True if ``text`` is an unmodified composer-generated graph, False if edited, None if
+    it is not a composer-generated file at all (no marker).
+
+    Recomputes the hash the generator would have produced for this exact content (with the
+    marker blanked) and compares to the stored marker: equal => nobody touched it since
+    generation (safe to regenerate over); unequal => hand-edited (refuse without --force).
+    """
+    stored = stored_hash(text)
+    if stored is None:
+        return None
+    blanked = _HASH_RE.sub(rf"\g<1>{_HASH_PLACEHOLDER}\g<3>", text, count=1)
+    recomputed = hashlib.sha256(blanked.encode("utf-8")).hexdigest()
+    return recomputed == stored

package/dist/composer/authoring/gaps.py

@@ -0,0 +1,115 @@
+"""gaps — feasibility gap report at `new` time (D7 step 4; D4 made mechanical).
+
+Feasibility is enforced BEFORE anything is written: an answer that references a source or
+capability the registry does not have does not crash and does not silently emit a broken
+graph — it produces a structured, printable, ``--json``-able gap report naming each missing
+capability, and ``composer new`` writes no file.
+
+This is D4 ("the agent can authoritatively know what is impossible") turned into a build
+step: the closed registry vocabulary is the oracle, so "can this strategy be built?" is a
+set-membership check, not a judgement call. The report is a teaching artifact in the same
+spirit as the validator's errors — for each missing capability it names what was asked for,
+what kind of node it would be, why the strategy needs it, and the nearest things the
+registry DOES have — so the boundary reads as an honest "here is what's pending", exactly
+the whalehunter paper-exercise story (its ~6 tier-3 pieces are deliberately absent).
+"""
+
+from __future__ import annotations
+
+import difflib
+from dataclasses import dataclass, field
+
+from composer.registry import NODES_BY_NAME
+
+from .answers import Answers
+
+
+@dataclass(frozen=True)
+class Gap:
+    """One missing capability: what was asked for and the nearest registry alternatives."""
+
+    name: str
+    kind: str
+    need: str
+    nearest: tuple[str, ...] = ()
+
+    def render(self) -> str:
+        head = f"  - {self.name} ({self.kind})"
+        if self.need:
+            head += f": {self.need}"
+        near = (
+            f"      nearest in registry: {', '.join(self.nearest)}"
+            if self.nearest
+            else "      nearest in registry: (nothing comparable — this is a new capability)"
+        )
+        return head + "\n" + near
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "kind": self.kind,
+            "need": self.need,
+            "nearest": list(self.nearest),
+        }
+
+
+@dataclass
+class GapReport:
+    """The result of the feasibility check: every capability the registry lacks."""
+
+    strategy: str
+    archetype: str
+    gaps: list[Gap] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.gaps
+
+    def render(self) -> str:
+        if self.ok:
+            return (
+                f"OK: every capability {self.strategy!r} references is in the registry "
+                f"(no gaps)."
+            )
+        n = len(self.gaps)
+        lines = [
+            f"GAP REPORT: strategy {self.strategy!r} (archetype {self.archetype!r}) "
+            f"references {n} capabilit{'ies' if n != 1 else 'y'} the registry does not have.",
+            "Nothing was written — these must be added to the registry (runtime-owned) first:",
+            "",
+        ]
+        for gap in self.gaps:
+            lines.append(gap.render())
+        lines.append("")
+        lines.append(
+            f"{n} pending capabilit{'ies' if n != 1 else 'y'}. Run `composer catalog` to "
+            f"see what IS available; a strategy that needs these is not yet buildable."
+        )
+        return "\n".join(lines) + "\n"
+
+    def to_json(self) -> dict:
+        return {
+            "strategy": self.strategy,
+            "archetype": self.archetype,
+            "ok": self.ok,
+            "gap_count": len(self.gaps),
+            "gaps": [g.to_dict() for g in self.gaps],
+        }
+
+
+def detect_gaps(answers: Answers) -> GapReport:
+    """Check every registry-name reference in the answers against the closed vocabulary.
+
+    Only the ``requires`` list is checked here: an archetype template supplies its own
+    (known-good) nodes, so the only place an answer can name a capability the machine cannot
+    provide is when it explicitly declares a needed capability that the archetype cannot
+    cover. Each unknown name becomes a :class:`Gap` with the nearest registry alternatives.
+    """
+    valid = sorted(NODES_BY_NAME)
+    gaps: list[Gap] = []
+    for cap in answers.requires:
+        if cap.name in NODES_BY_NAME:
+            continue
+        nearest = tuple(difflib.get_close_matches(cap.name, valid, n=3, cutoff=0.3))
+        gaps.append(Gap(name=cap.name, kind=cap.kind, need=cap.need, nearest=nearest))
+    return GapReport(strategy=answers.strategy, archetype=answers.archetype, gaps=gaps)