pen-stack 0.1.0__py3-none-any.whl

pen_stack/graph/cell_types.py

@@ -0,0 +1,58 @@
+"""Cell-type coverage cards + cross-type OOD labelling + graceful degradation.
+
+Each cell type is a graph node carrying a **coverage card** (which data tracks exist). A score is only as
+trustworthy as its coverage: a partial-coverage cell type **degrades gracefully** (its confidence is capped),
+and a score computed in one cell type but *queried* for another is **OOD-labelled**, the finding that
+chromatin marks are conserved, so cross-cell-type context is intrinsically weak/heuristic, not a guarantee.
+Tier-B cell types are a documented roadmap, never silently extrapolated.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+
+# graceful-degradation policy: the maximum trustworthy confidence a cell type's coverage supports.
+_MAX_CONF = {"full": 1.0, "partial": 0.6, "none": 0.0}
+
+
+@lru_cache(maxsize=1)
+def _cfg() -> dict:
+    return yaml.safe_load(resource("configs/cell_types.yaml").read_text(encoding="utf-8"))
+
+
+def coverage_card(cell_type: str) -> dict | None:
+    return _cfg()["cell_types"].get(cell_type)
+
+
+def cell_types() -> list[str]:
+    return list(_cfg()["cell_types"])
+
+
+def tier_b_roadmap() -> list[dict]:
+    return list(_cfg().get("tier_b_roadmap", []))
+
+
+def degrade(raw_confidence: float, cell_type: str) -> dict:
+    """Cap a confidence by the cell type's coverage (graceful degradation). Returns the degraded value +
+    whether degradation was applied + the coverage label, never silently inflates."""
+    card = coverage_card(cell_type) or {}
+    cov = card.get("coverage", "none")
+    cap = _MAX_CONF.get(cov, 0.0)
+    degraded = min(float(raw_confidence), cap)
+    return {"cell_type": cell_type, "coverage": cov, "raw_confidence": round(float(raw_confidence), 4),
+            "confidence": round(degraded, 4), "degraded": degraded < float(raw_confidence),
+            "cap": cap, "tracks": card.get("tracks", [])}
+
+
+def cross_cell_type_ood(query_cell_type: str, scored_in_cell_type: str) -> dict:
+    """Label a cross-cell-type query as OOD/extrapolating (cross-type signal is weak, heuristic).
+    Same cell type = in-distribution; different = extrapolating."""
+    ood = query_cell_type != scored_in_cell_type
+    return {"query_cell_type": query_cell_type, "scored_in_cell_type": scored_in_cell_type,
+            "ood": ood,
+            "label": "extrapolating (cross-cell-type; chromatin conserved -> weak heuristic)"
+                     if ood else "in-distribution",
+            "note": "cross-cell-type transfer is a heuristic signal, not a guarantee; reported, not hidden"}

pen_stack/graph/ingest.py

@@ -0,0 +1,132 @@
+"""The gated living-ingestion loop, the agent proposes; a gate disposes.
+
+The living-literature monitor (Europe PMC scan) and agents emit **candidate** nodes/edges from new evidence.
+Principle 1 is inviolable and encoded here: **no process auto-edits the curated world-model.** Candidates are
+*quarantined*; the ONLY way one enters the graph is `gate_admit(...)` with (a) automated checks passing AND
+(b) explicit approval. Every admission is versioned with date + evidence + the gate that admitted it
+(auditable history, Principle 3).
+
+There is deliberately no bulk-merge / auto-accept function: `propose(...)` only appends to the quarantine and
+never receives a `Graph`, so it *cannot* mutate the graph (asserted by test).
+"""
+from __future__ import annotations
+
+import datetime as _dt
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from pen_stack.graph.schema import Edge, Graph, Node
+
+CandidateKind = Literal["node", "edge"]
+Status = Literal["quarantined", "admitted", "rejected"]
+
+
+@dataclass
+class Candidate:
+    kind: CandidateKind
+    payload: dict[str, Any] # a Node-like or Edge-like dict
+    provenance: dict[str, Any] # MUST carry a source + (doi or europepmc id)
+    evidence: str = "predicted" # measured / curated / predicted
+    status: Status = "quarantined"
+    note: str | None = None
+
+
+@dataclass
+class Quarantine:
+    """Holds candidates; NEVER holds or touches a Graph. The only sink for `propose`."""
+    items: list[Candidate] = field(default_factory=list)
+
+    def propose(self, c: Candidate) -> None:
+        c.status = "quarantined" # forced; a proposal is never pre-approved
+        self.items.append(c)
+
+    def pending(self) -> list[Candidate]:
+        return [c for c in self.items if c.status == "quarantined"]
+
+
+def automated_checks(c: Candidate) -> tuple[bool, list[str]]:
+    """Gate stage 1: a candidate must be provenance-bearing + well-typed before a human can even approve it."""
+    reasons = []
+    prov = c.provenance or {}
+    if not (prov.get("source") or prov.get("doi") or prov.get("europepmc")):
+        reasons.append("no provenance (need source / doi / europepmc id)")
+    if c.evidence not in ("measured", "curated", "predicted"):
+        reasons.append(f"invalid evidence kind {c.evidence!r}")
+    if c.kind == "node" and not (c.payload.get("id") and c.payload.get("type")):
+        reasons.append("node payload missing id/type")
+    if c.kind == "edge" and not all(c.payload.get(k) for k in ("src", "dst", "etype")):
+        reasons.append("edge payload missing src/dst/etype")
+    return (not reasons), reasons
+
+
+def gate_admit(graph: Graph, candidate: Candidate, *, approved: bool, admitted_by: str,
+               log: list[dict] | None = None) -> dict:
+    """The ONLY path a candidate enters the curated graph. Requires automated checks AND explicit approval;
+    records a versioned admission. Returns the decision record; the graph is mutated ONLY on admit."""
+    log = log if log is not None else []
+    ok, reasons = automated_checks(candidate)
+    decision = {"date": _dt.date.today().isoformat(), "kind": candidate.kind,
+                "payload_id": candidate.payload.get("id") or candidate.payload.get("etype"),
+                "evidence": candidate.evidence, "provenance": candidate.provenance,
+                "automated_checks_passed": ok, "approved": bool(approved), "admitted_by": admitted_by}
+    if not (ok and approved):
+        candidate.status = "rejected"
+        decision["admitted"] = False
+        decision["reasons"] = reasons or ["not approved by gate"]
+        log.append(decision)
+        return decision
+    # admit
+    if candidate.kind == "node":
+        graph.add_node(Node(id=candidate.payload["id"], type=candidate.payload["type"],
+                            props=candidate.payload.get("props", {})))
+    else:
+        graph.add_edge(Edge(src=candidate.payload["src"], dst=candidate.payload["dst"],
+                            etype=candidate.payload["etype"], evidence=candidate.evidence,
+                            confidence=candidate.payload.get("confidence"),
+                            scope=candidate.payload.get("scope"), provenance=candidate.provenance))
+    candidate.status = "admitted"
+    decision["admitted"] = True
+    log.append(decision)
+    return decision
+
+
+# --------------------------------------------------------------------------------------------------
+# back-test: surface a KNOWN recent addition as a candidate (deterministic / CI-safe, no network)
+# --------------------------------------------------------------------------------------------------
+def back_test_candidates() -> list[Candidate]:
+    """The pre-registered back-test fixture: the recently-published bridge system **ISPpu10** (Europe PMC
+    PPR1218813; bioRxiv 2026-03-19), which the live monitor surfaces. Proposed as a candidate writer node +
+    a `performs insertion` edge, to be admitted only through the gate."""
+    prov = {"source": "Europe PMC monitor", "europepmc": "PPR1218813",
+            "doi": "10.64898/2026.03.19.712850", "date": "2026-03-19"}
+    return [
+        Candidate(kind="node", evidence="predicted", provenance=prov,
+                  payload={"id": "writer:ISPpu10", "type": "writer",
+                           "props": {"family": "bridge_IS110", "system": "ISPpu10",
+                                     "output_form": "DNA", "note": "structure-gated bridge recombinase"}}),
+        Candidate(kind="edge", evidence="predicted", provenance=prov,
+                  payload={"src": "writer:ISPpu10", "dst": "write_type:insertion", "etype": "performs",
+                           "scope": "coverage_only (newly reported; not yet human-cell measured)"}),
+    ]
+
+
+def propose_from_monitor(since: str = "2026-01-01", back_test: bool = False) -> Quarantine:
+    """Run the monitor and quarantine its hits as candidates (live path; network-guarded). The back-test
+    path is deterministic. Candidates are ALWAYS quarantined, never merged here."""
+    q = Quarantine()
+    if back_test:
+        for c in back_test_candidates():
+            q.propose(c)
+        return q
+    try:
+        from pen_stack.monitor.run import run_monitor
+        rep = run_monitor(since=since)
+        for row in rep.get("queue", []) if isinstance(rep, dict) else []:
+            q.propose(Candidate(kind="node", evidence="predicted",
+                                provenance={"source": "monitor", "doi": row.get("doi"),
+                                            "europepmc": row.get("id")},
+                                payload={"id": f"writer:{row.get('name', 'candidate')}", "type": "writer",
+                                         "props": row}))
+    except Exception: # noqa: BLE001 - network/Europe PMC absent -> empty quarantine, never fabricates
+        pass
+    return q

pen_stack/graph/query.py

@@ -0,0 +1,148 @@
+"""Multi-hop queries over the world-model graph.
+
+An agent asks a design question as ONE grounded multi-hop traversal, "which writers reach locus L AND are
+deliverable by a vehicle carrying their cargo form?", and every answer carries the **provenanced edges** it
+traversed, so the result is grounded by construction (no-fabrication: the answer is the path, not free text).
+The flat atlas/crosslink joins become graph *views* (`writers_for_locus`, `vehicles_for_writer`) for parity.
+"""
+from __future__ import annotations
+
+from pen_stack.graph.build import build_graph
+from pen_stack.graph.schema import Edge, Graph
+
+
+def graph() -> Graph:
+    return build_graph()
+
+
+# ---- table-view parity queries (reproduce the joins) --------------------------------------
+def vehicles_for_writer(family: str, g: Graph | None = None) -> list[dict]:
+    g = g or graph()
+    wid = f"writer:{family}"
+    return [{"vehicle": e.dst.split(":", 1)[1], "evidence": e.evidence, "scope": e.scope,
+             "provenance": e.provenance} for e in g.out_edges(wid, "deliverable_by")]
+
+
+def writers_for_locus(locus: str, g: Graph | None = None) -> list[dict]:
+    g = g or graph()
+    lid = f"locus:{locus}"
+    out = []
+    for w in g.nodes_of("writer"):
+        for e in g.out_edges(w.id, "reaches"):
+            if e.dst == lid:
+                out.append({"writer": w.props["family"], "evidence": e.evidence, "scope": e.scope,
+                            "provenance": e.provenance})
+    return out
+
+
+# common safe-harbour aliases not captured by the GSH name or its anchor gene (case-insensitive).
+_LOCUS_ALIASES = {"rosa26": "hrosa26", "rosa-26": "hrosa26", "hipp11": "h11", "hipp-11": "h11"}
+
+
+def _resolve_gsh_locus(query: str, g: Graph) -> str | None:
+    """Resolve a user's locus query to a curated GSH node id, matching (case-insensitively) the GSH NAME, its
+    ANCHOR GENE, or a common alias, so AAVS1, its anchor PPP1R12C, and ROSA26 (the curated node is hRosa26)
+    all reach the same node. Returns the node id (``locus:<name>``) or None if it is not a curated safe harbour."""
+    q = str(query or "").strip().lower()
+    if not q:
+        return None
+    q = _LOCUS_ALIASES.get(q, q)
+    for n in g.nodes_of("locus"):
+        name = n.id.split(":", 1)[1]
+        anchor = str(n.props.get("anchor_gene") or "")
+        if q in {name.lower(), anchor.lower()}:
+            return n.id
+    return None
+
+
+def _answer(w, reach_edges: list[Edge], deliv: list[Edge]) -> dict:
+    path: list[Edge] = reach_edges[:1] + deliv
+    return {
+        "writer": w.props["family"], "output_form": w.props["output_form"],
+        "vehicles": [e.dst.split(":", 1)[1] for e in deliv],
+        "provenance_path": [{"src": e.src, "dst": e.dst, "etype": e.etype, "evidence": e.evidence,
+                             "scope": e.scope, "provenance": e.provenance} for e in path],
+    }
+
+
+# ---- multi-hop design query (the headline graph capability) ------------------------------------
+def writers_reaching_and_deliverable(locus: str, cargo_form: str | None = None,
+                                     g: Graph | None = None) -> dict:
+    """Multi-hop: writers that REACH `locus` AND are DELIVERABLE_BY a vehicle (optionally carrying
+    `cargo_form`). Returns each answer with the full provenanced edge path (grounded answer).
+
+    Locus resolution (the graph only materialised curated safe-harbour nodes, so anything but their
+    exact name returned nothing): a query is first resolved to a curated GSH node by name / anchor gene / alias.
+    Failing that, if it resolves to a REAL gene, the answer is the tier-1 reprogrammable writers, which reach
+    ANY locus at the locus level (the documented crosslink property), with a scope flag saying so and that it is
+    NOT a curated safe harbour. A query that is neither returns a clean, explained empty result, never an error."""
+    g = g or graph()
+    gsh_id = _resolve_gsh_locus(locus, g)
+
+    if gsh_id is not None:  # curated safe harbour: the existing grounded traversal
+        resolved = gsh_id.split(":", 1)[1]
+        answers = []
+        for w in g.nodes_of("writer"):
+            if cargo_form is not None and w.props.get("output_form") != cargo_form:
+                continue
+            reach = [e for e in g.out_edges(w.id, "reaches") if e.dst == gsh_id]
+            deliv = g.out_edges(w.id, "deliverable_by")
+            if reach and deliv:
+                answers.append(_answer(w, reach, deliv))
+        note = ("every answer is a provenanced multi-hop path over the graph"
+                + (f"; '{locus}' resolved to curated safe harbour '{resolved}'" if resolved.lower() != str(locus).strip().lower() else ""))
+        return {"locus": locus, "resolved_locus": resolved, "is_curated_safe_harbour": True,
+                "cargo_form": cargo_form, "n_answers": len(answers), "answers": answers,
+                "grounded": all(a["provenance_path"] for a in answers), "no_fabrication": True, "note": note}
+
+    # not a curated GSH: does it resolve to a real gene? -> tier-1 reprogrammable writers reach ANY locus.
+    resolved_gene = None
+    try:
+        from pen_stack.planner.optimize import gene_region, resolve_gene
+        rg = resolve_gene(str(locus))
+        resolved_gene = rg if gene_region(rg) else None
+    except Exception:  # noqa: BLE001 - gene-coords absent (CI/offline) -> no fallback, clean empty
+        resolved_gene = None
+
+    if resolved_gene is None:
+        return {"locus": locus, "resolved_locus": None, "is_curated_safe_harbour": False,
+                "cargo_form": cargo_form, "n_answers": 0, "answers": [], "grounded": True, "no_fabrication": True,
+                "note": (f"'{locus}' is neither a curated safe-harbour locus nor a resolvable gene symbol, no "
+                         "grounded writer→locus→vehicle path (a clean empty result, not an error).")}
+
+    # tier-1 = the writers the graph gives locus-level `reaches` edges (near-universal reprogrammable reach).
+    tier1 = {e.src for e in g.edges if e.etype == "reaches"}
+    answers = []
+    for w in g.nodes_of("writer"):
+        if w.id not in tier1:
+            continue
+        if cargo_form is not None and w.props.get("output_form") != cargo_form:
+            continue
+        deliv = g.out_edges(w.id, "deliverable_by")
+        if not deliv:
+            continue
+        synth = Edge(w.id, f"locus:{resolved_gene}", "reaches", "predicted",
+                     scope="locus-level reachability (per-site element check is Planner work); NOT a curated "
+                           "safe-harbour node, tier-1 reprogrammable near-universal reach",
+                     provenance={"source": "crosslink reachability_tier (tier-1 reprogrammable); locus resolved "
+                                           "to a real gene, not a curated GSH, treat as a candidate, verify per-site"})
+        answers.append(_answer(w, [synth], deliv))
+    return {"locus": locus, "resolved_locus": resolved_gene, "is_curated_safe_harbour": False,
+            "cargo_form": cargo_form, "n_answers": len(answers), "answers": answers,
+            "grounded": all(a["provenance_path"] for a in answers), "no_fabrication": True,
+            "note": (f"'{resolved_gene}' is not a curated safe harbour; these are the tier-1 reprogrammable writers, "
+                     "which reach any locus at the locus level (a candidate, not a validated safe-harbour path, "
+                     "per-site reachability + safety are the Planner / Guardian's job).")}
+
+
+def outcomes_for_writer(family: str, g: Graph | None = None) -> list[dict]:
+    """Documented (measured) writes performed by a writer family, the outcome edges."""
+    g = g or graph()
+    wid = f"writer:{family}"
+    out = []
+    for o in g.nodes_of("outcome"):
+        for e in g.out_edges(o.id, "used_writer"):
+            if e.dst == wid:
+                out.append({"outcome": o.id.split(":", 1)[1], "cargo_bp": o.props["cargo_bp"],
+                            "evidence": e.evidence, "doi": o.props["doi"]})
+    return out

pen_stack/graph/schema.py

@@ -0,0 +1,100 @@
+"""The living world-model knowledge graph, schema.
+
+The substrate's ground truth (L3) was flat tables joined by code. Promotes it to a queryable
+**knowledge graph**: typed nodes (writer / locus / cargo / vehicle / cell_type / write_type / outcome) joined
+by typed edges (reaches / deliverable_by / performs / durable_in / carries / used_writer / observed_at), where
+**every edge carries its provenance, its uncertainty, and the scope within which it holds** (Principle 2).
+
+Edges are typed by evidence kind, `measured` (a documented experimental outcome) > `curated` (a
+hand-verified fact, e.g. a delivery-vehicle property) > `predicted` (a model/homology inference), so an
+agent traversing the graph always knows how much to trust each hop. Nodes/edges are plain dataclasses; the
+store (build/query) is pure-Python + JSON/sqlite (Docker-friendly, no graph-DB dependency).
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal
+
+NodeType = Literal["writer", "locus", "cargo", "vehicle", "cell_type", "write_type", "outcome"]
+EdgeType = Literal["reaches", "deliverable_by", "performs", "durable_in", "carries",
+                   "used_writer", "observed_at"]
+EvidenceKind = Literal["measured", "curated", "predicted"]
+
+
+@dataclass
+class Node:
+    id: str
+    type: NodeType
+    props: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class Edge:
+    src: str
+    dst: str
+    etype: EdgeType
+    evidence: EvidenceKind # measured / curated / predicted (trust ordering)
+    confidence: float | None = None # [0,1] where known; None = not quantified (abstain)
+    scope: str | None = None # the context within which the edge holds (limit)
+    provenance: dict[str, Any] = field(default_factory=dict) # {source, doi, date, ...}
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @property
+    def key(self) -> tuple:
+        return (self.src, self.dst, self.etype)
+
+
+class Graph:
+    """An in-memory typed multigraph with provenance-tagged edges. Pure Python; serialises to JSON."""
+
+    def __init__(self) -> None:
+        self.nodes: dict[str, Node] = {}
+        self.edges: list[Edge] = []
+        self._adj: dict[str, list[Edge]] = {} # src -> edges (built lazily)
+
+    # ---- construction --------------------------------------------------------------------------
+    def add_node(self, node: Node) -> None:
+        self.nodes[node.id] = node
+
+    def add_edge(self, edge: Edge) -> None:
+        if edge.src not in self.nodes or edge.dst not in self.nodes:
+            raise KeyError(f"edge {edge.key} references an unknown node")
+        self.edges.append(edge)
+        self._adj.setdefault(edge.src, []).append(edge)
+
+    # ---- traversal -----------------------------------------------------------------------------
+    def out_edges(self, node_id: str, etype: EdgeType | None = None) -> list[Edge]:
+        es = self._adj.get(node_id, [])
+        return [e for e in es if etype is None or e.etype == etype]
+
+    def neighbors(self, node_id: str, etype: EdgeType | None = None) -> list[str]:
+        return [e.dst for e in self.out_edges(node_id, etype)]
+
+    def nodes_of(self, ntype: NodeType) -> list[Node]:
+        return [n for n in self.nodes.values() if n.type == ntype]
+
+    # ---- serialisation -------------------------------------------------------------------------
+    def to_dict(self) -> dict:
+        return {"nodes": [n.to_dict() for n in self.nodes.values()],
+                "edges": [e.to_dict() for e in self.edges]}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Graph":
+        g = cls()
+        for n in d["nodes"]:
+            g.add_node(Node(**n))
+        for e in d["edges"]:
+            g.add_edge(Edge(**e))
+        return g
+
+    def summary(self) -> dict:
+        from collections import Counter
+        return {"n_nodes": len(self.nodes), "n_edges": len(self.edges),
+                "nodes_by_type": dict(Counter(n.type for n in self.nodes.values())),
+                "edges_by_type": dict(Counter(e.etype for e in self.edges)),
+                "edges_by_evidence": dict(Counter(e.evidence for e in self.edges))}

pen_stack/loop/__init__.py

@@ -0,0 +1,15 @@
+"""pen_stack.loop, the closed loop, autonomy Level 3.
+
+PEN-STACK generates safe legal designs, predicts their outcomes, chooses the most informative experiments,
+exports gated protocols, runs them in the simulated lab or a real one, ingests results through the world-model's
+gate, and updates its calibration, twin, and immune labels round after round, detecting when observations drift
+from predictions and widening uncertainty rather than over-trusting a stale model. It keeps a human in control at
+every gate, never fabricates a number, and stops deliberately at autonomy Level 3.
+"""
+from __future__ import annotations
+
+from pen_stack.loop.continual import continual_update
+from pen_stack.loop.cycle import AUTONOMY_LEVEL, loop_converges_faster_than_random, run_loop
+from pen_stack.loop.drift import detect_drift
+
+__all__ = ["run_loop", "continual_update", "detect_drift", "loop_converges_faster_than_random", "AUTONOMY_LEVEL"]

pen_stack/loop/continual.py

@@ -0,0 +1,61 @@
+"""Gated, versioned, reversible continual learning, the closed loop.
+
+Recalibrates the trust layer + the twin + the immune proxies on ADMITTED outcomes only, never on
+un-gated evidence. Every update is versioned and reversible (carries a `rollback_to` pointer), attributable to
+the admitted evidence and the approver. High drift widens intervals rather than over-trusting a shifting model.
+This is recalibration, NOT full retraining of the foundation models.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from statistics import mean
+
+
+def _evidence_digest(admitted_results: list) -> str:
+    payloads = [getattr(r, "payload", r) for r in admitted_results]
+    return hashlib.sha256(json.dumps(payloads, sort_keys=True, default=str).encode()).hexdigest()[:12]
+
+
+def _readouts(admitted_results: list) -> list[float]:
+    out = []
+    for r in admitted_results:
+        payload = getattr(r, "payload", r)
+        ro = payload.get("readout") if isinstance(payload, dict) else None
+        if ro is not None:
+            out.append(float(ro))
+    return out
+
+
+def _update_immune_labels(admitted_results: list) -> dict:
+    """Immune-measurement results can move an axis proxy -> outcome-validated (recorded). Requires an
+    admitted measurement that names an immune axis + a CI (the calibration rule); else no graduation."""
+    graduated = []
+    for r in admitted_results:
+        payload = getattr(r, "payload", r)
+        if isinstance(payload, dict) and payload.get("immune_axis_measured") and payload.get("ci"):
+            graduated.append(payload["immune_axis_measured"])
+    return {"graduated_to_validated": graduated,
+            "note": "graduation requires an admitted immune measurement with a CI (the immune-calibration gate)"}
+
+
+def continual_update(admitted_results: list, *, drift: dict | None = None, approver: str,
+                     prev_version: str | None = None) -> dict:
+    """Recalibrate trust + twin + immune proxies on ADMITTED outcomes only. Versioned + reversible. High drift
+    widens intervals rather than over-trusting a shifting model."""
+    if not admitted_results:
+        return {"updated": False, "reason": "no admitted evidence", "rollback_to": prev_version}
+    readouts = _readouts(admitted_results)
+    calibration = {"mean_readout": round(mean(readouts), 4) if readouts else None, "n": len(readouts)}
+    interval_inflation = 1.0
+    if drift and drift.get("severity") == "high":
+        interval_inflation = 1.0 + min(1.0, drift.get("ece", 0.0)) # widen, don't over-trust
+    imm_lbls = _update_immune_labels(admitted_results)
+    version = f"v{_evidence_digest(admitted_results)}"
+    return {
+        "updated": True, "version": version, "by": approver,
+        "n_evidence": len(admitted_results), "calibration": calibration,
+        "interval_inflation": round(interval_inflation, 4), "immune_labels": imm_lbls,
+        "rollback_to": prev_version, # reversible: revert to the prior belief version
+        "note": "recalibration only (not foundation-model retraining); admitted-evidence-only; versioned+reversible",
+    }

pen_stack/loop/cycle.py

@@ -0,0 +1,84 @@
+"""The DBTL orchestrator, the closed loop.
+
+One continual design→build→test→learn cycle, integrating every prior cycle:
+  generate → decide/batch → safety-gated export → run (sim-lab / real lab) →
+  ingest (gate) → drift → continual learn.
+**Autonomy Level 3**: closed, but with humans/lab IN CONTROL at every gate (safety, build, belief-admission),
+not autonomous. Numbers come only from tools; no stage fabricates a value.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+AUTONOMY_LEVEL = 3
+
+
+def _converged(history: list[dict]) -> bool:
+    """Converge when the best observed readout stops improving meaningfully over the last two rounds."""
+    bests = [h.get("best_readout") for h in history if h.get("best_readout") is not None]
+    return len(bests) >= 2 and abs(bests[-1] - bests[-2]) < 0.01
+
+
+def _best_readout(results: list) -> float | None:
+    vals = []
+    for r in results:
+        payload = getattr(r, "payload", r)
+        ro = payload.get("readout") if isinstance(payload, dict) else None
+        if ro is not None:
+            vals.append(float(ro))
+    return max(vals) if vals else None
+
+
+def run_loop(goal: dict, cell_state: str, *, candidates: list[dict] | None = None, rounds: int = 5,
+             use_lab: bool = False, approver: str = "human", seed: int = 0) -> dict[str, Any]:
+    """One Level-3 DBTL campaign. Gated: safety + build + belief-admission each await `approver`. Optimises
+    efficacy AND immune-risk; numbers come only from tools; no stage fabricates. Pass an explicit `candidates`
+    pool to run atlas-independently (sim-lab is the default; a real lab attaches at the same interface)."""
+    from pen_stack.active.design import select_batch
+    from pen_stack.build.ingest import ingest_result
+    from pen_stack.build.protocol import ProtocolExportError, _to_protocol_ir, export_protocol
+    from pen_stack.build.simlab import run_simulated
+    from pen_stack.design.generate import generate_designs
+    from pen_stack.loop.continual import continual_update
+    from pen_stack.loop.drift import detect_drift
+
+    history: list[dict] = []
+    prev_version: str | None = None
+    for r in range(rounds):
+        cands = generate_designs(goal, candidates=candidates, keep=8, actor=approver) # (safe+legal+calibrated)
+        if not cands:
+            history.append({"round": r, "n": 0, "note": "no surviving candidates (atlas absent or all discarded)"})
+            break
+        batch = select_batch(cands, cell_state, {"round": r}, k=4) # (info + immune-VOI)
+        admitted, blocked = [], 0
+        for d in batch:
+            try:
+                export_protocol(d, {"round": r}, actor=approver) # safety-gate (may block)
+            except ProtocolExportError:
+                blocked += 1
+                continue
+            ir = _to_protocol_ir(d, {"round": r})
+            res = (_run_real(ir, d) if use_lab else run_simulated(ir, d, cell_state, seed=seed + r))
+            admitted.append(ingest_result(res, admitted_by=approver)) # gate (human approves)
+        drift = detect_drift(batch, admitted, cell_state=cell_state)
+        update = continual_update(admitted, drift=drift, approver=approver, prev_version=prev_version)
+        prev_version = update.get("version", prev_version)
+        history.append({"round": r, "n": len(admitted), "blocked": blocked, "best_readout": _best_readout(admitted),
+                        "drift": drift, "update": update})
+        if _converged(history):
+            break
+    return {"goal": goal, "history": history, "final_model_version": prev_version,
+            "autonomy_level": AUTONOMY_LEVEL, "human_in_control": True, "no_fabrication": True}
+
+
+def _run_real(protocol_ir: dict, design: dict): # pragma: no cover - a real lab attaches here
+    raise NotImplementedError("attach a real lab at this interface (same shape as the sim-lab)")
+
+
+def loop_converges_faster_than_random(reps: int = 15, rounds: int = 6) -> dict:
+    """The loop's active Learn stage reaches a target model quality in FEWER rounds than random,
+    proven retrospectively with reps + a bootstrap CI (the convergence headline; reuses the prior validation)."""
+    from pen_stack.active.validate import retrospective_active_learning
+    r = retrospective_active_learning(reps=reps, rounds=rounds)
+    return {"reaches_optimum_faster_than_random": r["active_beats_random"],
+            "active_vs_random_ci": r["active_vs_random"]["ci"], "honest_note": r["honest_note"]}

pen_stack/loop/drift.py

@@ -0,0 +1,41 @@
+"""Drift detection, the closed loop.
+
+Compares what the twin PREDICTED against what the experiments OBSERVED. Growing miscalibration => drift => widen
+uncertainty and flag, rather than over-trusting a stale model. Covers calibration/residual shift, not every
+failure mode.
+"""
+from __future__ import annotations
+
+
+def _predicted(design: dict, cell_state: str) -> float | None:
+    from pen_stack.twin.outcome import predict_outcome
+    v = predict_outcome(design, design.get("cell_state") or cell_state or "k562")
+    return v["predicted_outcome"].get("relative_expression")
+
+
+def _empirical_calibration_error(designs: list, results: list, cell_state: str = "") -> tuple[float, int]:
+    errs = []
+    for d, r in zip(designs, results):
+        pred = _predicted(d, cell_state)
+        obs = (r.get("payload", {}) if hasattr(r, "get") else {}).get("readout") if not isinstance(r, dict) else r.get("readout")
+        # results may be raw dicts (sim/ingest) or Candidates; read the readout from either
+        if obs is None and hasattr(r, "payload"):
+            obs = r.payload.get("readout")
+        if pred is not None and obs is not None:
+            errs.append(abs(float(pred) - float(obs)))
+    if not errs:
+        return 0.0, 0
+    return sum(errs) / len(errs), len(errs)
+
+
+def _drift_threshold() -> float:
+    return 0.20 # mean abs predicted-vs-observed error above which we flag drift
+
+
+def detect_drift(designs: list, results: list, *, cell_state: str = "") -> dict:
+    """Predicted (twin) vs observed (results). Growing miscalibration => drift => widen + flag."""
+    ece_now, n = _empirical_calibration_error(designs, results, cell_state)
+    sev = "high" if ece_now > _drift_threshold() else "low"
+    return {"severity": sev, "ece": round(ece_now, 4), "n": n,
+            "action": "inflate_intervals" if sev == "high" else "monitor",
+            "note": "calibration/residual drift only, not every failure mode"}

pen_stack/mech/__init__.py

@@ -0,0 +1 @@
+"""pen_stack.mech - see the PEN-STACK program doc."""