archforge-optimizer 0.1.0__py3-none-any.whl

archforge/gatekeeper.py

@@ -0,0 +1,290 @@
+"""The Gatekeeper — the P-E-C "Commit" step (spec §3, §4, §6, §8).
+
+Lone enforcer of "fail closed to the incumbent": it is the only thing that ever
+moves the `active` pointer (via SpecStore.set_active) or flips an Attempt's
+verdict beyond INITIAL. Its `decide(...)` returns a `Decision` naming the action;
+`apply(...)` executes it (or you can decide without applying to inspect).
+
+Decision rules (thresholds from `m.Thresholds`):
+  * unrunnable (candidate suite >ε crashed) -> DISCARD (before any margin math, E4)
+  * cross-rubric/cross-suite      -> DISCARD (the only valid comparison is same
+    rubric + same suite; I5 — never silently compare across rubrics)
+  * candidate_mean - incumbent_mean <  τ  -> DISCARD        (E1 noise inside τ)
+  * win + scope SMALL                          -> AUTO_PROMOTE (active = candidate)
+  * win + scope STRUCTURAL                    -> QUEUE_HUMAN   (never auto-promote, I4)
+  * promoted-then-regresses (≥ δ on the standard suite) -> ROLLBACK
+    (active = parent, candidate archived, verdict ROLLED_BACK; pointer swap, E6)
+
+Structural changes are queued even on a clear win — the human gate the user
+locked in. `apply` returns the updated Attempt (verdict set) so the orchestrator
+can record the cycle's outcome. Rollback uses the lineage pointer; no Spec is
+ever deleted (archived, never deleted).
+
+Human approval (`approve`) is the second path — besides AUTO_PROMOTE/ROLLBACK —
+that may move `active`: a queued (PENDING_HUMAN) structural change the human
+accepts becomes the incumbent; a rejection (`reject`) leaves the incumbent alone
+and archives the candidate as a recorded dead end.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+import archforge.models as m
+from archforge.stores.attempt_store import AttemptStore
+from archforge.stores.spec_store import SpecStore
+
+
+class Action(str, Enum):
+    """What the Gatekeeper decided to do with this candidate."""
+
+    AUTO_PROMOTE = "auto_promote"     # small win -> active = candidate
+    QUEUE_HUMAN = "queue_human"       # structural win -> Approval Queue
+    DISCARD = "discard"               # loss / unrunnable / cross-rubric
+    ROLLBACK = "rollback"             # promoted-then-regressed (E6)
+
+
+class Decision(BaseModel):
+    """The Gatekeeper's verdict on a candidate. ``Gatekeeper.apply_decision`` executes it."""
+
+    model_config = ConfigDict(extra="allow")
+
+    action: Action
+    attempt_id: str | None = None      # the candidate Attempt this decides
+    reason: str                         # human-readable, surfaced to the report
+    margin: float = 0.0                # candidate_mean - incumbent_mean (signed)
+    by_rule: str = ""                  # which rule fired ("auto_promote", "rollback", ...)
+
+    def __repr__(self) -> str:  # pragma: no cover  (debug aid)
+        return (f"Decision(action={self.action.value}, margin={self.margin:+.3f}, "
+                f"rule={self.by_rule}, reason={self.reason!r})")
+
+
+class _AttemptNotFoundError(KeyError):
+    """The candidate Attempt given to the Gatekeeper was never persisted."""
+
+
+class Gatekeeper:
+    """The lone enforcer of promotion + rollback.
+
+    Constructed once per run with the (SpecStore, AttemptStore) it mutates and a
+    `Thresholds` (τ, δ, ε). Stateless across calls otherwise — the incumbent + a
+    candidate's SuiteRun are passed in `decide`.
+    """
+
+    def __init__(
+        self,
+        spec_store: SpecStore,
+        attempt_store: AttemptStore,
+        *,
+        thresholds: m.Thresholds | None = None,
+    ) -> None:
+        self._specs = spec_store
+        self._attempts = attempt_store
+        self._th = thresholds or m.Thresholds()
+
+    # ----------------------------------------------------------------- decide
+    def decide(
+        self,
+        attempt_id: str,
+        candidate: Any,                 # SuiteRun (typed loosely to avoid an import cycle)
+        incumbent: "m.SuiteRun | None" = None,
+    ) -> Decision:
+        """Decide the fate of a candidate `SuiteRun` vs the incumbent `SuiteRun`.
+
+        Both are `SuiteRun` objects (archforge.suite). `incumbent=None` means
+        "no incumbent yet" — only AUTO_PROMOTE-like forward progress is valid,
+        but a structural candidate still queues for human review.
+        """
+        # NOTE: `m.SuiteRun` lives in archforge.suite, not archforge.models, so we
+        # accept it as `Any` here and pull attributes defensively (duck-typed).
+
+        if candidate.unrunnable:
+            return _decision(Action.DISCARD, attempt_id,
+                            "candidate suite was unrunnable (>ε tasks crashed/unscored)",
+                            rule="unrunnable")
+
+        if incumbent is not None and not _same_geometry(incumbent, candidate):
+            return _decision(Action.DISCARD, attempt_id,
+                            "candidate vs incumbent differ in rubric or suite "
+                            "(cross-geometry comparison blocked, I5)",
+                            rule="cross_geometry")
+
+        inc_mean = incumbent.mean if incumbent is not None else 0.0
+        margin = candidate.mean - inc_mean
+        cand_scope = self._candidate_scope(attempt_id)
+
+        if margin < self._th.tau:
+            return _decision(Action.DISCARD, attempt_id,
+                            f"candidate did not clear margin τ={self._th.tau} "
+                            f"(margin {margin:+.3f}); noise not promoted (E1)",
+                            margin=margin, rule="below_margin")
+
+        # win past τ
+        if cand_scope is m.Scope.STRUCTURAL:
+            return _decision(Action.QUEUE_HUMAN, attempt_id,
+                            f"structural win by {margin:+.3f} >= τ but structural "
+                            f"changes require human approval (I4)",
+                            margin=margin, rule="structural_wins_queue")
+        return _decision(Action.AUTO_PROMOTE, attempt_id,
+                         f"small win by {margin:+.3f} >= τ={self._th.tau}; promoted",
+                         margin=margin, rule="auto_promote")
+
+    # ----------------------------------------------------------------- apply
+    def apply_decision(self, decision: Decision) -> m.Attempt:
+        """Execute a Decision against the stores and return the updated Attempt."""
+
+        if decision.attempt_id is None:
+            raise ValueError("cannot apply a Decision with no attempt_id")
+        att = self._attempts.require(decision.attempt_id)
+
+        if decision.action is Action.AUTO_PROMOTE:
+            spec_id = att.candidate_spec_id
+            self._specs.set_active(spec_id)
+            verdict = m.Verdict.PROMOTED
+        elif decision.action is Action.QUEUE_HUMAN:
+            verdict = m.Verdict.PENDING_HUMAN
+        elif decision.action is Action.DISCARD:
+            verdict = m.Verdict.REJECTED
+        elif decision.action is Action.ROLLBACK:
+            self._rollback(att)
+            verdict = m.Verdict.ROLLED_BACK
+        else:  # pragma: no cover  (enum exhaustive)
+            raise ValueError(f"unknown action {decision.action}")
+
+        return self._attempts.set_verdict(decision.attempt_id, verdict)
+
+    # ----------------------------------------------------------------- human gate
+    def approve(self, attempt_id: str) -> m.Attempt:
+        """Human approves a queued (PENDING_HUMAN) structural change (spec I4).
+
+        This is the one path besides AUTO_PROMOTE/ROLLBACK that may move the
+        `active` pointer — the human gate the user locked in: a structural win is
+        never auto-promoted, only ever promoted through here. `active` -> the
+        candidate, verdict -> PROMOTED. Idempotent for an already-promoted attempt
+        (a no-op). Raises `ValueError` if the attempt is not queued, so the CLI
+        cannot rewrite history (only decide what the gate queued).
+        """
+
+        att = self._attempts.require(attempt_id)
+        if att.verdict is m.Verdict.PROMOTED:
+            return att                       # already approved (idempotent)
+        if att.verdict is not m.Verdict.PENDING_HUMAN:
+            raise ValueError(
+                f"cannot approve attempt {attempt_id}: verdict is "
+                f"{att.verdict.value}; only PENDING_HUMAN (queued) changes can be approved"
+            )
+        self._specs.set_active(att.candidate_spec_id)
+        return self._attempts.set_verdict(attempt_id, m.Verdict.PROMOTED)
+
+    def reject(self, attempt_id: str, *, reason: str = "human-reject") -> m.Attempt:
+        """Human rejects a queued structural change: verdict -> REJECTED, active unchanged.
+
+        The incumbent is left alone. The candidate Spec is archived (never
+        deleted) with `reason="human-reject"` so the dead end is recorded for
+        lineage/dedup queries. Idempotent for an already-rejected attempt.
+        Raises `ValueError` if the attempt is not queued.
+        """
+
+        att = self._attempts.require(attempt_id)
+        if att.verdict is m.Verdict.REJECTED:
+            return att
+        if att.verdict is not m.Verdict.PENDING_HUMAN:
+            raise ValueError(
+                f"cannot reject attempt {attempt_id}: verdict is "
+                f"{att.verdict.value}; only PENDING_HUMAN (queued) changes can be rejected"
+            )
+        self._specs.archive(att.candidate_spec_id, reason=reason)
+        return self._attempts.set_verdict(attempt_id, m.Verdict.REJECTED)
+
+    # ----------------------------------------------------------------- rollback (E6)
+    def rollback(
+        self,
+        attempt_id: str,
+        *,
+        regressed_mean: float,
+        pre_promotion_mean: float,
+    ) -> Decision:
+        """Decide+apply a rollback after a promoted Spec regressed (E6).
+
+        Rolls back iff `pre_promotion_mean - regressed_mean >= δ` on the standard
+        suite (same rubric+suite, I5). Otherwise the regression is within the
+        noise floor and the incumbent is left alone. Returns the Decision (which
+        has already been applied if action is ROLLBACK).
+        """
+
+        drop = pre_promotion_mean - regressed_mean
+        # Idempotency: a repeated regression check on an already-rolled-back
+        # attempt must not downgrade its verdict or move the active pointer
+        # again. Return a benign DISCARD decision without touching the stores.
+        current_verdict = self._attempts.require(attempt_id).verdict
+        if current_verdict is m.Verdict.ROLLED_BACK:
+            return _decision(Action.DISCARD, attempt_id,
+                             "regression check on an already-rolled-back attempt; "
+                             "no further action",
+                             margin=-drop, rule="already_rolled_back")
+
+        if drop < self._th.delta:
+            # Regression is within the δ noise floor: the promotion stands, the
+            # incumbent (the promoted Spec) is left in place, and the attempt's
+            # verdict is NOT mutated — a real small-won, the dip is just noise.
+            return _decision(Action.DISCARD, attempt_id,
+                            f"regression {drop:+.3f} < δ={self._th.delta}; within the "
+                            f"noise floor, incumbent left alone",
+                            margin=-drop, rule="regression_within_floor")
+
+        d = _decision(Action.ROLLBACK, attempt_id,
+                      f"regression {drop:+.3f} >= δ={self._th.delta}; rolling back to "
+                      f"parent (pointer swap, archived, never deleted)",
+                      margin=-drop, rule="rollback")
+        att = self._attempts.require(attempt_id)
+        self._rollback(att)
+        self._attempts.set_verdict(attempt_id, m.Verdict.ROLLED_BACK)
+        return d
+
+    def _rollback(self, att: m.Attempt) -> None:
+        """Active -> parent; candidate archived. Pointer swap, never deleted (E6/I3)."""
+
+        spec = self._specs.get(att.candidate_spec_id)
+        parent_id = spec.parent_spec_id
+        if parent_id is None:
+            # root incumbent regressed: nothing to roll back to; leave pointer, mark rejected
+            self._specs.archive(att.candidate_spec_id, reason="rollback_rootless")
+            return
+        if not self._specs.has(parent_id):
+            raise _AttemptNotFoundError(
+                f"rollback target parent {parent_id} not in store"
+            )
+        self._specs.set_active(parent_id)         # pointer swap — the incumbent reverts
+        self._specs.archive(att.candidate_spec_id, reason="rollback")
+
+    # ----------------------------------------------------------------- helpers
+    def _candidate_scope(self, attempt_id: str) -> m.Scope:
+        att = self._attempts.require(attempt_id)
+        return att.change.scope
+
+
+# --------------------------------------------------------------------------- #
+# helpers (module-private)
+# --------------------------------------------------------------------------- #
+
+
+def _decision(
+    action: Action, attempt_id: str | None, reason: str,
+    *, margin: float = 0.0, rule: str = "",
+) -> Decision:
+    return Decision(action=action, attempt_id=attempt_id, reason=reason,
+                   margin=margin, by_rule=rule)
+
+
+def _same_geometry(inc: Any, cand: Any) -> bool:
+    """Invariant I5: comparisons only valid under identical (rubric, suite)."""
+
+    return (getattr(inc, "rubric_id", None) == getattr(cand, "rubric_id", None)
+            and getattr(inc, "suite_id", None) == getattr(cand, "suite_id", None))
+
+
+__all__ = ["Action", "Decision", "Gatekeeper"]

archforge/host/__init__.py

@@ -0,0 +1,20 @@
+"""Host multi-agent system integration (spec §3, §4).
+
+ArchForge does not depend on any specific agentic framework. A host MAS
+implements the `HostMAS` contract: it can build an executable pipeline from a
+`Spec` and run a `Task` through it, emitting one `Step` per agent. The
+`TracingMiddleware` attaches as both observer (records steps to TraceStore) and
+config bridge (applies the live Spec's prompt/model/knobs to each agent at
+invoke time — so evolving the pipeline is swapping which Spec the host uses).
+"""
+
+from __future__ import annotations
+
+from archforge.host.base import Agent, AgentResponse, HostMAS, Runnable, Task
+from archforge.host.fake import (
+    FakeAgent, FakeHostMAS, FakeRuleAgent, FakeRetrieverAgent, FakeToolAgent,
+)
+
+__all__ = ["Agent", "AgentResponse", "HostMAS", "Runnable", "Task",
+           "FakeHostMAS", "FakeAgent", "FakeRuleAgent", "FakeRetrieverAgent",
+           "FakeToolAgent"]

archforge/host/adapters/__init__.py

@@ -0,0 +1,41 @@
+"""archforge.host.adapters — the reusable adapter kit.
+
+The single place a new MAS author looks: subclass `BaseHostAdapter` + a small
+`BaseAgent` per node, fill `call()` (the node's real work), and override the
+hooks (`execution_order` / `resolve_prompt` / `stage_context`) only when the
+MAS's data-shaping is non-default. The kit owns the run loop, content-decouple,
+config-decay, perf, and partial-trace flush — the recurring scaffolding every
+adapter previously re-derived.
+
+`helpers` is also re-exported so an author extending the loop's primitives
+(topo order, run-id, config decay) does so against one source.
+"""
+from archforge.host.adapters.base import (
+    BaseAgent, BaseHostAdapter, BasePipeline, CallResult, RunContext,
+)
+from archforge.host.adapters.helpers import (
+    KnobVote, cfg_as_kwargs, cfg_decay, estimate_tokens, run_id, topo_order,
+)
+# LangGraph adapter — re-exported eagerly. The module is langgraph-FREE (it
+# imports no langgraph types; the dependency enters only when a concrete app's
+# `graph_factory` builds the real graph), so importing it here keeps
+# `import archforge` framework-free.
+from archforge.host.adapters.langgraph import (
+    EdgeSpec, LangGraphApp, LangGraphHostAdapter, LangGraphRunnable, Nd,
+    NodeIdMap, build_optimized_envelope, export_optimized, export_spec_sidecar,
+    load_optimized, load_spec_sidecar, node_ids,
+)
+# `wrapped` is deliberately NOT re-exported at the package level: a MAS authors
+# the id ONCE in its `build_graph` via `add(name, fn)` and imports `wrapped`
+# from `archforge.host.adapters.langgraph` (the adapter module the MAS already
+# touches) — never from `archforge.otel` directly, and never from this package.
+
+__all__ = [
+    "BaseHostAdapter", "BaseAgent", "BasePipeline", "CallResult", "RunContext",
+    "run_id", "topo_order", "cfg_decay", "cfg_as_kwargs", "KnobVote",
+    "estimate_tokens",
+    "Nd", "EdgeSpec", "LangGraphApp", "LangGraphHostAdapter",
+    "LangGraphRunnable", "NodeIdMap", "node_ids",
+    "export_spec_sidecar", "load_spec_sidecar",
+    "build_optimized_envelope", "export_optimized", "load_optimized",
+]

archforge/host/adapters/base.py

@@ -0,0 +1,311 @@
+"""The ArchForge adapter kit — a reusable implementation of the host seam.
+
+`HostMAS` / `Agent` / `Runnable` (in ``host/base.py``) are the *contract*; this
+module is a *reusable implementation of it* that owns the scaffolding every MAS
+adapter repeats:
+
+  * one ``Agent`` per Spec node;
+  * the run loop: ``begin_run`` → ordered walk → ``end_run``, with a monotonic
+    run-id (unique across R-repeats), partial-trace flush on any crash (E4);
+  * the **content-decouple**: score the agent's *content*, thread its
+    *plumbing* onward via an ``AgentResponse`` extra (``extra="allow"`` lets a
+    ``thread`` field ride without a model change);
+  * the **config-decay** (phase-2 rule): thread model/temperature/max_tokens
+    always (base run == agent default → behaviour-preserving) and system_prompt
+    only when mutated.
+
+The genuinely-MAS-specific bits are exposed as a few imperative hooks an adapter
+overrides when its MAS needs them — *not* a declarative graph interpreter (so
+hard data-shaping — file-stage handoffs, multi-input joins — is just imperative
+code in a hook, never a drop off a declarative cliff).
+"""
+from __future__ import annotations
+
+import time
+from contextlib import nullcontext
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+import archforge.models as m
+from archforge.host.adapters.helpers import cfg_decay, estimate_tokens, run_id, topo_order
+from archforge.host.base import AgentResponse, HostMAS, Runnable, Task
+from archforge.middleware import TracingMiddleware
+
+
+# --------------------------------------------------------------------------- #
+# Run context — what the loop carries between nodes
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class RunContext:
+    """The state threaded through one run, advanced by the loop and read by
+    the adapter's ``resolve_prompt``.
+
+    ``last_content`` is what each step's response *recorded* (what the Judge
+    scores); ``last_thread`` is what each step *threads onward* (plumbing: a
+    file path, a ref… — usually the same as content for text-in/text-out MASes,
+    different for file-staged ones like Lumina). ``per_node`` lets a join node
+    recall a sibling threaded earlier (the report 3-way join reads sibling
+    gap/cross paths here).
+    """
+
+    last_content: str
+    last_thread: str | None = None
+    per_node: dict[str, Any] = field(default_factory=dict)
+
+    def advance(self, node_id: str, resp: AgentResponse) -> None:
+        self.last_content = resp.text
+        # `thread` rides as an AgentResponse extra (extra="allow"); fall back to
+        # the scored content if the adapter didn't set one (text-in/text-out).
+        self.last_thread = getattr(resp, "thread", None) or resp.text
+        self.per_node[node_id] = self.last_thread
+
+
+# --------------------------------------------------------------------------- #
+# CallResult — the content-decouple made first-class
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class CallResult:
+    """What an agent's ``call`` returns: ``thread`` flows to the next node
+    (plumbing), ``content`` is what the trace records and the Judge scores.
+
+    Promoted from the Lumina adapter's ``RunResult`` so every kit-made adapter
+    gets content-decouple for free instead of re-inventing it.
+    """
+
+    thread: str | None
+    content: str
+
+
+# --------------------------------------------------------------------------- #
+# BaseAgent — implements `Agent`; owns invoke; author overrides `call`
+# --------------------------------------------------------------------------- #
+
+
+class BaseAgent:
+    """One node's executor. The kit owns ``invoke`` (the content-decouple +
+    config-decay + perf measurement); the adapter fills ``call`` — the node's
+    real work — and is handed a config map it forwards to its agent call.
+    """
+
+    def __init__(self, node: m.Node, adapter: "BaseHostAdapter") -> None:
+        self._node = node
+        self._adapter = adapter
+
+    @property
+    def node_id(self) -> str:
+        return self._node.node_id
+
+    @property
+    def role(self) -> str:
+        return self._node.role
+
+    def call(self, prompt: str, vote: "KnobVote") -> CallResult:  # noqa: ARG002
+        """The one abstract hook: run the node, return (thread, content).
+
+        ``vote`` is the DECAYED live config (a `KnobVote`: model / temperature /
+        max_tokens / retries / system_prompt, each ``None`` meaning "use your
+        default"). The adapter binds exactly the keys its agent accepts — the
+        kit owns the decay logic, not the agent's signature. Subclasses override.
+        """
+        raise NotImplementedError(f"{type(self).__name__}.call() not implemented")
+
+    def invoke(
+        self,
+        prompt: str,
+        *,
+        system_prompt: str | None,
+        model: str | None,
+        knobs: m.Knobs | None,
+        tools: list[str] | None,
+        kind: m.NodeKind = m.NodeKind.LLM,
+    ) -> AgentResponse:
+        """Kit-owned: fulfils the `Agent` protocol. Applies config-decay, calls
+        the node's real work, packs an AgentResponse that records *content* and
+        carries *plumbing* onward via the `thread` extra.
+
+        `kind` is accepted for protocol parity with the middleware (which threads
+        the live node's `NodeKind` to every wrapped agent) and defaults to `LLM`
+        so existing kit adapters keep working unchanged. It is UNUSED here: a kit
+        adapter that needs kind-specific behaviour reads `self._node.kind` in its
+        `call` override (the node is already held on the agent).
+        """
+        vote = self._adapter.cfg_for(self.node_id, system_prompt, model, knobs, tools)
+        t0 = time.perf_counter()
+        cr = self.call(prompt, vote)
+        latency = round((time.perf_counter() - t0) * 1000.0, 3)
+        # `text` is what the trace records + the Judge scores (content); the
+        # `thread` extra is what flows to the next node (plumbing).
+        return AgentResponse(
+            text=cr.content,
+            tool_calls=[],
+            thread=cr.thread if cr.thread is not None else cr.content,
+            perf=m.StepPerf(tokens=estimate_tokens(cr.content), latency_ms=latency),
+        )
+
+
+def _estimate(text: str) -> int:  # kept as a thin alias for any external callers
+    return estimate_tokens(text)
+
+
+# --------------------------------------------------------------------------- #
+# BaseHostAdapter — implements `HostMAS`; owns instantiate; delegates the run
+# --------------------------------------------------------------------------- #
+
+
+class BaseHostAdapter:
+    """A `HostMAS` that builds a `BasePipeline` from a Spec.
+
+    An adapter subclasses this and overrides the hooks that are non-default for
+    its MAS:
+
+      * ``make_agent``  — wrap one framework agent per Spec node (the per-node
+        factory that chooses the right ``BaseAgent`` subclass).
+      * ``execution_order``  — default: topological from edges; override for a
+        fixed sequence (Lumina's 7-step).
+      * ``resolve_prompt``  — default: the last step's content; override for a
+        file path when a node needs upstream plumbing (joins, file-stage handoffs).
+      * ``stage_context``  — default: none; override for a per-run scratch area
+        (Lumina: a temp dir + chdir, released on exit).
+
+    The run loop, content-decouple, config-decay, partial-trace flush, perf —
+    none of those are the adapter's concern; the kit owns them.
+    """
+
+    #: The seeded/default prompts, so `cfg_decay` can tell a *mutated* prompt
+    #: (an Architect prompt_edit) from the default and only thread the former.
+    #: Subclasses populate this (often from their base Spec).
+    base_prompts: dict[str, str] = {}
+
+    # ---- hooks (override when the MAS needs non-default behaviour) -------- #
+
+    def make_agent(self, node: m.Node) -> BaseAgent:
+        """Pick the `BaseAgent` subclass for `node` (one per Spec node)."""
+        raise NotImplementedError("make_agent must return a BaseAgent for each node")
+
+    def execution_order(self, spec: m.Spec) -> list[str]:
+        """Order to run nodes in. Default: topological from the Spec's edges."""
+        return topo_order(spec)
+
+    def resolve_prompt(self, node_id: str, ctx: RunContext) -> str:
+        """What `node_id` receives as its prompt. Default: the last step's
+        *content* (text-in/text-out). Override to pass a file path / sibling
+        ref when the node needs upstream plumbing (joins, file-stage handoffs)."""
+        return ctx.last_content
+
+    def stage_context(self):
+        """A context manager wrapping one run. Default: none. Override for a
+        per-run scratch area — e.g. a temp dir + chdir (Lumina) — that this
+        releases on exit. The loop's `finally` cleanup lives here."""
+        return nullcontext()
+
+    # ---- kit-internal seam (rarely overridden) --------------------------- #
+
+    def cfg_for(
+        self, node_id: str, system_prompt: str | None, model: str | None,
+        knobs: m.Knobs | None, tools: list[str] | None,
+    ) -> "KnobVote":
+        """Live-config → the DECAYED values the adapter's ``call`` forwards to
+        its agent. Defaults to the phase-2 `cfg_decay` rule; returns a
+        ``KnobVote`` so each adapter binds EXACTLY the keys its agent accepts
+        (the kit owns the decay logic, not the agent's signature). Override only
+        if the MAS's config-decay differs."""
+        return cfg_decay(node_id, system_prompt, model, knobs, tools,
+                         base_prompts=self.base_prompts)
+
+    # ---- kit-owned: the existing HostMAS.instantiate contract, un-touched -- #
+
+    def instantiate(self, spec: m.Spec, middleware: TracingMiddleware) -> Runnable:
+        agents: dict[str, BaseAgent] = {}
+        for node in spec.nodes:
+            agents[node.node_id] = self._agent_for(node)
+        return BasePipeline(spec, middleware, agents, self)
+
+    def _agent_for(self, node: m.Node) -> BaseAgent:
+        """One agent per Spec node; an unknown node_id (an `add_node` we can't
+        run) becomes a _RaisingAgent, surfacing as an errored run that scoring
+        rejects — structural changes stay human-gated (I4)."""
+        try:
+            return self.make_agent(node)
+        except NotImplementedError:
+            return _RaisingAgent(node, self)
+
+
+# --------------------------------------------------------------------------- #
+# BasePipeline — implements `Runnable`; owns the run loop
+# --------------------------------------------------------------------------- #
+
+
+class BasePipeline:
+    """A Spec rendered as an executable pipeline by the kit's run loop.
+
+    The loop only calls the adapter's hooks — it never inspects framework
+    specifics — so the same loop ranges over a stateless pipeline MAS
+    (text-in/text-out, default hooks) and a file-staged one (Lumina, override
+    order/prompt/context). ``run`` returns a full `Trace` (ok or not); a mid-run
+    crash flushes a partial trace with the Steps that ran (E4) — never lost.
+    """
+
+    def __init__(
+        self,
+        spec: m.Spec,
+        middleware: TracingMiddleware,
+        agents: dict[str, BaseAgent],
+        adapter: BaseHostAdapter,
+    ) -> None:
+        self._spec = spec
+        self._mw = middleware
+        self._agents = agents
+        self._adapter = adapter
+        self._run_counter = 0
+
+    def run(self, task: Task) -> m.Trace:
+        sid = self._spec.spec_id or self._spec.compute_spec_id()
+        rid = run_id(sid, task.task_id, self._run_counter)
+        self._run_counter += 1
+        self._mw.begin_run(rid, self._spec, task.task_id)
+
+        present = {n.node_id for n in self._spec.nodes}
+        ctx = RunContext(last_content=task.input)
+        final_output: str | None = None
+        try:
+            with self._adapter.stage_context():
+                for node_id in self._adapter.execution_order(self._spec):
+                    if node_id not in present or node_id not in self._agents:
+                        continue  # a remove_node mutation simply skips a step
+                    prompt = self._adapter.resolve_prompt(node_id, ctx)
+                    wrapped = self._mw.wrap(self._agents[node_id])
+                    resp = wrapped.invoke(prompt)
+                    ctx.advance(node_id, resp)
+                    final_output = resp.text
+            return self._mw.end_run(final_output, ok=True, error=None)
+        except Exception as exc:  # noqa: BLE001 — flush a partial trace (E4)
+            return self._mw.end_run(final_output, ok=False, error=repr(exc))
+
+
+# --------------------------------------------------------------------------- #
+# Unknown-node agent — structural mutations that can't yet run
+# --------------------------------------------------------------------------- #
+
+
+class _RaisingAgent(BaseAgent):
+    """A node the adapter can't execute (an `add_node` it has no entry-point
+    for). `invoke` runs (so the trace records the step) but `call` raises,
+    surfacing as ok=False — scoring rejects it, structural changes stay
+    human-gated (I4)."""
+
+    def call(self, prompt: str, vote: "KnobVote") -> CallResult:  # noqa: ARG002
+        raise RuntimeError(
+            f"Adapter {type(self._adapter).__name__} can't execute node "
+            f"{self.node_id!r}: not in its node map (add_node mutations aren't "
+            f"runnable yet; the run errors and is rejected by scoring)."
+        )
+
+
+__all__ = [
+    "RunContext", "CallResult", "BaseAgent", "BaseHostAdapter",
+    "BasePipeline", "run_id", "topo_order", "cfg_decay",
+]