pen-stack 0.1.0__py3-none-any.whl

pen_stack/adapt/ingest.py

@@ -0,0 +1,86 @@
+"""Ingest a user's private assay into per-site labels matching the model's feature schema.
+
+The runnable in-code path is TABULAR: a CSV/TSV/Parquet of sites + an outcome label (and, optionally, the
+released-model score column or the per-bin features to attach). The upstream FASTQ/BAM -> per-site label
+derivation (integration-site sequencing, GUIDE-seq, expression-stability profiling) is documented in
+docs/private_data_formats.md and runs in the Docker image with the usual aligners; it produces exactly the
+tabular schema this module validates, so the two halves compose.
+
+Schema (standardized output): chrom, bin, ct, label, [score], [features...]
+  * label: 0/1 (discrimination) or a real value in [0,1] (calibration target).
+  * score: the released model's output for that site (safety / p_durable / writability) - the thing we
+    recalibrate. If absent, attach_features() joins it from the writability atlas.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+BIN_BP = 1000
+REQUIRED = ("chrom", "label") # plus one of {bin, pos}
+
+
+def load_user_labels(path: str | Path) -> pd.DataFrame:
+    """Load + validate a user label table (.csv/.tsv/.parquet). Returns a frame with chrom, bin, ct, label."""
+    p = Path(path)
+    if p.suffix in (".parquet", ".pq"):
+        df = pd.read_parquet(p)
+    else:
+        df = pd.read_csv(p, sep="\t" if p.suffix in (".tsv", ".txt") else ",")
+    return normalize(df)
+
+
+def normalize(df: pd.DataFrame) -> pd.DataFrame:
+    """Validate columns and standardize: derive `bin` from `pos` if needed; coerce label; default ct."""
+    df = df.copy()
+    missing = [c for c in REQUIRED if c not in df.columns]
+    if missing:
+        raise ValueError(f"user table missing required columns: {missing} (have {list(df.columns)})")
+    if "bin" not in df.columns:
+        if "pos" not in df.columns:
+            raise ValueError("user table needs a 'bin' or a 'pos' column to locate each site")
+        df["bin"] = (df["pos"].astype(int) // BIN_BP).astype(int)
+    if "ct" not in df.columns:
+        df["ct"] = "user"
+    lab = pd.to_numeric(df["label"], errors="coerce")
+    if lab.isna().any():
+        raise ValueError("label column has non-numeric / missing values")
+    if not (((lab == 0) | (lab == 1)).all() or ((lab >= 0) & (lab <= 1)).all()):
+        raise ValueError("label must be binary {0,1} or a probability in [0,1]")
+    df["label"] = lab.astype(float)
+    keep = ["chrom", "bin", "ct", "label"] + [c for c in df.columns
+                                              if c not in ("chrom", "bin", "ct", "label", "pos")]
+    return df[keep].reset_index(drop=True)
+
+
+def attach_features(df: pd.DataFrame, target: str = "safety", ct: str = "k562") -> pd.DataFrame:
+    """Join the released model's score for `target` (safety|p_durable|writability) from the writability atlas.
+
+    No-op if the score column is already present (user supplied it). Raises if the atlas is unavailable and
+    no score column exists - the caller then supplies scores directly.
+    """
+    col = {"safety": "safety", "durability": "p_durable", "p_durable": "p_durable",
+           "writability": "writability"}.get(target, target)
+    if col in df.columns and df[col].notna().any():
+        return df.rename(columns={col: "score"}) if col != "score" else df
+    if "score" in df.columns:
+        return df
+    atlas = Path(__file__).resolve().parents[2].parent / "phase_1" / "out" / f"atlas_{ct}.parquet"
+    if not atlas.exists():
+        raise FileNotFoundError(
+            f"no '{col}'/'score' column and atlas absent ({atlas}); supply the released-model score "
+            "column in the user table, or run inside the image where the atlas is mounted.")
+    a = pd.read_parquet(atlas, columns=["chrom", "bin", col])
+    out = df.merge(a, on=["chrom", "bin"], how="left").rename(columns={col: "score"})
+    if out["score"].isna().any():
+        out = out.dropna(subset=["score"]).reset_index(drop=True)
+    return out
+
+
+def schema_summary(df: pd.DataFrame) -> dict:
+    return {"n_sites": int(len(df)), "n_chroms": int(df["chrom"].nunique()),
+            "label_kind": "binary" if set(np.unique(df["label"])) <= {0.0, 1.0} else "continuous",
+            "positive_rate": round(float(df["label"].mean()), 4),
+            "has_score": "score" in df.columns}

pen_stack/adapt/pipeline.py

@@ -0,0 +1,101 @@
+"""The adaptation pipeline (ingest -> split -> recalibrate/finetune -> held-out gate -> version).
+
+`adapt()` is the one entry point. It splits the user's sites into train/held-out (chromosome-grouped when
+possible), fits the adaptation on train, scores the released vs adapted model on the SAME held-out split,
+and applies the validation gate. The adapted artifact is written under models/local_<id>/ ONLY - the
+released model is never overwritten, and its fingerprint is checked before/after to prove it (acceptance).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from pen_stack.adapt import report as R
+from pen_stack.adapt.recalibrate import recalibrate
+
+_ROOT = Path(__file__).resolve().parents[2]
+_MODELS = _ROOT / "models"
+# released score-producing modules - the "released model" we must prove is unchanged by adaptation.
+_RELEASED = [_ROOT / "pen_stack" / "wgenome" / m for m in ("safety.py", "durability.py", "writability.py")]
+
+
+def _split(df: pd.DataFrame, seed: int, holdout_frac: float = 0.3):
+    """Chromosome-grouped holdout when >=2 chromosomes (no leakage); else a seeded random split."""
+    rng = np.random.default_rng(seed)
+    chroms = df["chrom"].unique()
+    if len(chroms) >= 2:
+        n_ho = max(1, int(round(len(chroms) * holdout_frac)))
+        ho_chroms = set(rng.choice(chroms, size=n_ho, replace=False))
+        mask = df["chrom"].isin(ho_chroms)
+    else:
+        mask = pd.Series(rng.random(len(df)) < holdout_frac, index=df.index)
+    return df[~mask].reset_index(drop=True), df[mask].reset_index(drop=True)
+
+
+def adapt(df: pd.DataFrame, target: str = "safety", method: str = "isotonic", local_id: str = "local",
+          seed: int = 20260604, primary: str = "brier", margin: float = 0.0,
+          feature_cols: list[str] | None = None, models_dir: str | Path = _MODELS) -> dict:
+    """Recalibrate (or fine-tune) the released `target` score on the user frame (needs 'score' + 'label').
+
+    Returns the held-out before/after report + the gate decision + the artifact paths. The adapted model is
+    activated (written + flagged) only if it beats the released model on the held-out split.
+    """
+    if "score" not in df.columns or "label" not in df.columns:
+        raise ValueError("adapt() needs standardized columns 'score' and 'label' (see adapt.ingest)")
+    fp_before = R.released_fingerprint(*_RELEASED)
+
+    train, holdout = _split(df, seed)
+    if len(train) < 5 or len(holdout) < 3:
+        raise ValueError(f"not enough data after split (train={len(train)}, holdout={len(holdout)})")
+
+    base_holdout = np.clip(holdout["score"].to_numpy(float), 0, 1) # released score as a probability
+    if method == "isotonic":
+        cal = recalibrate(train["score"], train["label"])
+        adapted_holdout = cal.transform(holdout["score"])
+        artifact = "calibrator.json"
+    elif method == "finetune":
+        from pen_stack.adapt.finetune import finetune_head, predict_proba
+        cols = feature_cols or ["score"]
+        model = finetune_head(train[cols].to_numpy(float), train["label"], seed=seed)
+        adapted_holdout = predict_proba(model, holdout[cols].to_numpy(float))
+        cal, artifact = None, "head.txt"
+    else:
+        raise ValueError(f"unknown method: {method!r} (use 'isotonic' or 'finetune')")
+
+    # no-skill constant predictor: the TRAIN base rate applied to every held-out site (no leakage). The
+    # adapted model must beat this too, else its 'improvement' is just regression to climatology.
+    base_rate = float(np.clip(train["label"].mean(), 1e-6, 1 - 1e-6))
+    no_skill = R.evaluate(np.full(len(holdout), base_rate), holdout["label"])
+
+    base = R.evaluate(base_holdout, holdout["label"])
+    adapted = R.evaluate(adapted_holdout, holdout["label"])
+    gate = R.gate(base, adapted, primary=primary, margin=margin, no_skill=no_skill)
+
+    out_dir = Path(models_dir) / f"local_{local_id}"
+    fp_after = R.released_fingerprint(*_RELEASED)
+    released_unchanged = fp_before == fp_after
+    report = {"local_id": local_id, "target": target, "method": method,
+              "n_train": int(len(train)), "n_holdout": int(len(holdout)),
+              "held_out_before": base, "held_out_after": adapted, "held_out_no_skill": no_skill, "gate": gate,
+              "released_model_unchanged": released_unchanged,
+              "released_fingerprint": fp_after, "activated": gate["activate"]}
+    card = R.model_card(f"local_{local_id}", target, method, base, adapted, gate,
+                        len(train), len(holdout), fp_after)
+    paths = R.write_report(out_dir, report, card)
+    # persist the adapted artifact ONLY when the gate passes; otherwise remove any stale artifact so a
+    # previously-activated adaptation that now fails the gate is not left active (released model stays in force).
+    artifact_path = out_dir / artifact
+    if gate["activate"]:
+        if method == "isotonic":
+            cal.save(artifact_path)
+        else:
+            model.booster_.save_model(str(artifact_path))
+        paths["artifact"] = str(artifact_path)
+    else:
+        for stale in (out_dir / "calibrator.json", out_dir / "head.txt"):
+            if stale.exists():
+                stale.unlink()
+    report["paths"] = paths
+    return report

pen_stack/adapt/recalibrate.py

@@ -0,0 +1,58 @@
+"""Isotonic recalibration of a released score on user labels (private, in-container).
+
+Isotonic regression learns a monotonic map released_score -> calibrated probability. Being monotonic it
+NEVER changes the ranking (AUROC is preserved); it only fixes calibration (Brier / ECE). Small and robust on
+the small datasets users typically have. The calibrator is saved as plain JSON under models/local_<id>/ -
+the released model is untouched.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+
+
+class IsotonicCalibrator:
+    """Thin, serializable wrapper around sklearn's IsotonicRegression (saved as JSON, no pickle)."""
+
+    def __init__(self):
+        self._iso = None
+        self.fitted = False
+
+    def fit(self, scores, labels) -> "IsotonicCalibrator":
+        from sklearn.isotonic import IsotonicRegression
+        s, y = np.asarray(scores, float), np.asarray(labels, float)
+        self._iso = IsotonicRegression(out_of_bounds="clip", y_min=0.0, y_max=1.0)
+        self._iso.fit(s, y)
+        self.fitted = True
+        return self
+
+    def transform(self, scores):
+        if not self.fitted:
+            raise RuntimeError("calibrator not fitted")
+        return self._iso.predict(np.asarray(scores, float))
+
+    def to_dict(self) -> dict:
+        return {"kind": "isotonic", "x": list(map(float, self._iso.X_thresholds_)),
+                "y": list(map(float, self._iso.y_thresholds_))}
+
+    def save(self, path: str | Path) -> Path:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        Path(path).write_text(json.dumps(self.to_dict(), indent=2), encoding="utf-8")
+        return Path(path)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "IsotonicCalibrator":
+        d = json.loads(Path(path).read_text(encoding="utf-8"))
+        obj = cls()
+        from sklearn.isotonic import IsotonicRegression
+        iso = IsotonicRegression(out_of_bounds="clip", y_min=0.0, y_max=1.0)
+        iso.fit(np.asarray(d["x"], float), np.asarray(d["y"], float)) # re-fit on the stored knots
+        obj._iso, obj.fitted = iso, True
+        return obj
+
+
+def recalibrate(scores, labels) -> IsotonicCalibrator:
+    """Fit an isotonic calibrator mapping a released score to a calibrated probability on user labels."""
+    return IsotonicCalibrator().fit(scores, labels)

pen_stack/adapt/report.py

@@ -0,0 +1,130 @@
+"""Held-out evaluation, the validation GATE, and the model card.
+
+The adapted artifact ACTIVATES only if it beats the released model on the user's held-out split (the gate).
+Calibration is judged by Brier score + expected calibration error (ECE, lower is better); discrimination by
+AUROC (higher is better). The released model is provably unchanged (its artifact hash is recorded and
+re-checked); a before/after report and a model card are always written.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+
+
+def _auroc(scores, labels) -> float:
+    pos = [s for s, y in zip(scores, labels) if y == 1]
+    neg = [s for s, y in zip(scores, labels) if y == 0]
+    if not pos or not neg:
+        return float("nan")
+    return sum((p > n) + 0.5 * (p == n) for p in pos for n in neg) / (len(pos) * len(neg))
+
+
+def _ece(probs, labels, n_bins: int = 10) -> float:
+    probs, labels = np.asarray(probs, float), np.asarray(labels, float)
+    edges = np.linspace(0, 1, n_bins + 1)
+    ece, n = 0.0, len(probs)
+    for i in range(n_bins):
+        m = (probs >= edges[i]) & (probs < edges[i + 1] if i < n_bins - 1 else probs <= edges[i + 1])
+        if m.sum():
+            ece += (m.sum() / n) * abs(probs[m].mean() - labels[m].mean())
+    return float(ece)
+
+
+def evaluate(probs, labels) -> dict:
+    """Calibration + discrimination metrics for a set of probabilities against binary labels."""
+    probs, labels = np.asarray(probs, float), np.asarray(labels, float)
+    brier = float(np.mean((probs - labels) ** 2))
+    biny = labels if set(np.unique(labels)) <= {0.0, 1.0} else (labels >= 0.5).astype(float)
+    return {"n": int(len(probs)), "brier": round(brier, 5), "ece": round(_ece(probs, biny), 5),
+            "auroc": round(_auroc(list(probs), list(biny)), 4)}
+
+
+def gate(base: dict, adapted: dict, primary: str = "brier", margin: float = 0.0,
+         no_skill: dict | None = None) -> dict:
+    """Activate the adapted model only if it BEATS the released model AND the no-skill constant predictor on
+    the held-out primary metric.
+
+    primary='brier'|'ece' -> lower is better; primary='auroc' -> higher is better. `margin` is the minimum
+    improvement required (guards against noise on small holdouts). The `no_skill` guard is essential:
+    recalibration can trivially lower Brier by regressing to the base rate, so we require the adapted model
+    to beat the constant base-rate predictor too - otherwise the 'improvement' is no skill, just climatology.
+    """
+    lower_better = primary in ("brier", "ece")
+
+    def better(x, ref):
+        return (ref - x) if lower_better else (x - ref)
+
+    b, a = base[primary], adapted[primary]
+    imp_released = better(a, b)
+    beats_released = imp_released > margin
+    beats_no_skill = True
+    ns = None
+    if no_skill is not None:
+        ns = no_skill[primary]
+        beats_no_skill = better(a, ns) > margin
+    activate = bool(beats_released and beats_no_skill)
+    if activate:
+        decision = "ADAPTED ACTIVATED (beats released AND the no-skill constant on held-out)"
+    elif not beats_no_skill:
+        decision = "ADAPTED REJECTED (improvement is no skill - does not beat the constant base rate)"
+    else:
+        decision = "ADAPTED REJECTED (does not beat released; released model kept)"
+    return {"primary_metric": primary, "lower_is_better": lower_better,
+            "released": b, "adapted": a, "no_skill_constant": ns,
+            "improvement_vs_released": round(imp_released, 5), "margin": margin,
+            "beats_released": bool(beats_released), "beats_no_skill": bool(beats_no_skill),
+            "activate": activate, "decision": decision}
+
+
+def released_fingerprint(*paths: str | Path) -> dict:
+    """Hash designated released-model artifacts so we can prove they are unchanged by adaptation."""
+    import hashlib
+    fp = {}
+    for p in paths:
+        p = Path(p)
+        if p.exists():
+            fp[str(p.name)] = hashlib.sha256(p.read_bytes()).hexdigest()[:16]
+    return fp
+
+
+def model_card(local_id: str, target: str, method: str, base: dict, adapted: dict, gate_res: dict,
+               n_train: int, n_holdout: int, released_fp: dict) -> str:
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    return "\n".join([
+        f"# PEN-STACK local adaptation - {local_id}",
+        "",
+        f"- **Date:** {ts}",
+        f"- **Target score:** {target} **Method:** {method}",
+        f"- **Data:** {n_train} train / {n_holdout} held-out sites (private, in-container)",
+        f"- **Released-model fingerprint (unchanged):** {released_fp}",
+        "",
+        "## Held-out before/after",
+        "| metric | released | adapted |",
+        "|---|---|---|",
+        f"| Brier (lower better) | {base['brier']} | {adapted['brier']} |",
+        f"| ECE (lower better) | {base['ece']} | {adapted['ece']} |",
+        f"| AUROC (higher better) | {base['auroc']} | {adapted['auroc']} |",
+        "",
+        f"## Gate: **{gate_res['decision']}**",
+        f"- primary metric `{gate_res['primary_metric']}`: released {gate_res['released']} -> adapted "
+        f"{gate_res['adapted']} (improvement vs released {gate_res['improvement_vs_released']}, "
+        f"no-skill constant {gate_res.get('no_skill_constant')}, margin {gate_res['margin']}; "
+        f"beats released={gate_res['beats_released']}, beats no-skill={gate_res['beats_no_skill']}).",
+        "",
+        "## Scope",
+        "Recalibration / light fine-tuning on a small private dataset; overfitting is mitigated (not "
+        "eliminated) by the held-out gate. Not unsupervised learning from raw reads. The released model is "
+        "never overwritten - this artifact lives under `models/local_<id>/` and activates only if the gate "
+        "passed.",
+    ])
+
+
+def write_report(out_dir: str | Path, report: dict, card: str) -> dict:
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "report.json").write_text(json.dumps(report, indent=2, default=str), encoding="utf-8")
+    (out / "model_card.md").write_text(card, encoding="utf-8")
+    return {"report": str(out / "report.json"), "model_card": str(out / "model_card.md")}

pen_stack/agent/__init__.py

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

pen_stack/agent/cite.py

@@ -0,0 +1,175 @@
+"""Cited mechanistic rationale + scoped generalisation.
+
+Every recommendation carries a short, literature-cited "why". Crucially the citations are **drawn from the
+curated world-model** (the verifier rule provenance, the writer/delivery/locus DOIs), not generated by a
+language model, so they **resolve by construction**. A hallucinated-citation guard rejects any DOI that is
+not in the curated, already-verified set. Numbers in the rationale remain tool-sourced (the prose is
+a presentation layer over verified facts; no quantity is invented).
+
+Generalisation toward adjacent genetic-engineering tasks is **grounded-or-refused**, a task is
+answered only if it maps to an existing grounded capability; anything else is refused with a scope statement,
+never faked.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+
+
+@lru_cache(maxsize=1)
+def curated_dois() -> frozenset[str]:
+    """The set of DOIs that appear in the CURATED, already-verified world-model (delivery palette, GSH loci,
+    writer panel, rule provenance). A citation is 'grounded' iff its DOI is in this set, so a citation can
+    only ever point at a source the substrate has actually curated (no hallucinated references)."""
+    dois: set[str] = set()
+    veh = yaml.safe_load(resource("configs/delivery_vehicles.yaml").read_text(encoding="utf-8"))["vehicles"]
+    for v in veh.values():
+        dois.update(v.get("dois", []) or [])
+        dois.update((v.get("immune_safety") or {}).get("immune_dois", []) or []) # immune priors
+    # computed-oracle provenance (genotoxicity: VISDB/COSMIC; capsid epitope: MHCflurry/HLA)
+    for _art in ("configs/genotoxicity_oracle.yaml", "configs/capsid_epitope_oracle.yaml"):
+        try:
+            a = yaml.safe_load(resource(_art).read_text(encoding="utf-8"))
+            dois.update(a.get("provenance_dois", []) or [])
+        except FileNotFoundError:
+            pass
+    # computed innate-sensing provenance (CpG-TLR9 / AAV CpG-depletion / RNA modification)
+    from pen_stack.planner.innate_sensing import PROVENANCE_DOIS as _innate_dois
+    dois.update(_innate_dois)
+    # off-target nomination provenance (GUIDE/CIRCLE/CHANGE/SITE-seq assays + CRISOT predictor + LSI assays)
+    try:
+        from pen_stack.wgenome.offtarget_data import (
+            ASSAY_PROVENANCE,
+            INTEGRASE_ASSAY_PROVENANCE,
+            PREDICTOR_PROVENANCE,
+        )
+        for _src in (ASSAY_PROVENANCE, PREDICTOR_PROVENANCE, INTEGRASE_ASSAY_PROVENANCE):
+            for _rec in _src.values():
+                if _rec.get("doi"):
+                    dois.add(_rec["doi"])
+    except Exception: # noqa: BLE001
+        pass
+    # delivery provenance (FLIP-AAV capsid-fitness + approved-therapy serotype->tissue priors)
+    try:
+        trop = yaml.safe_load(resource("configs/aav_serotype_tropism.yaml").read_text(encoding="utf-8")) or {}
+        dois.update(trop.get("provenance_dois", []) or [])
+        for _rec in (trop.get("serotypes") or {}).values():
+            if _rec.get("doi"):
+                dois.add(_rec["doi"])
+        dois.update(["10.1101/2021.11.09.467890", "10.1038/s41587-020-00793-4", "10.1126/science.aaw2900"])
+    except Exception: # noqa: BLE001
+        pass
+    # anti-vector seroprevalence provenance (serosurveys)
+    try:
+        sp = yaml.safe_load(resource("configs/seroprevalence.yaml").read_text(encoding="utf-8"))
+        for _rec in (sp.get("serotypes") or {}).values():
+            dois.update(_rec.get("dois", []) or [])
+    except FileNotFoundError:
+        pass
+    # anti-PEG serosurvey provenance
+    try:
+        ap = yaml.safe_load(resource("configs/antipeg.yaml").read_text(encoding="utf-8"))
+        dois.update((ap.get("prevalence") or {}).get("dois", []) or [])
+    except FileNotFoundError:
+        pass
+    # route/immune-privilege modifier provenance
+    from pen_stack.planner.immune_profile import ROUTE_MODIFIER_DOI
+    dois.add(ROUTE_MODIFIER_DOI)
+    gsh = yaml.safe_load(resource("configs/gsh_validated_heldout.yaml").read_text(encoding="utf-8"))["gsh"]
+    for g in gsh:
+        if g.get("doi"):
+            dois.add(g["doi"])
+    import csv
+    with open(resource("data/writer_panel.csv"), encoding="utf-8") as f:
+        for row in csv.DictReader(f):
+            if row.get("doi"):
+                dois.add(row["doi"])
+    # rule provenance DOIs
+    from pen_stack.rules import load_ruleset
+    for r in load_ruleset().rules:
+        dois.update(r.provenance.get("doi", []) or [])
+    # biosecurity-standards alignment provenance (IBBIS Common Mechanism + SecureDNA)
+    try:
+        from pen_stack.safety.standards import COMMON_MECHANISM, SECUREDNA
+        dois.add(COMMON_MECHANISM["citation_doi"])
+        dois.add("10.48550/arXiv." + SECUREDNA["citation_arxiv"])
+    except Exception: # noqa: BLE001
+        pass
+    return frozenset(dois)
+
+
+def citations_grounded(dois: list[str]) -> dict:
+    """Hallucinated-citation guard: every cited DOI must be in the curated set. Returns the verdict + any
+    ungrounded DOIs (which would be a hallucination and are rejected)."""
+    curated = curated_dois()
+    ungrounded = [d for d in dois if d not in curated]
+    return {"all_grounded": not ungrounded, "ungrounded": ungrounded, "n_checked": len(dois)}
+
+
+def cited_rationale(design: dict) -> dict:
+    """A short, literature-cited mechanistic 'why' for a design, with citations DRAWN FROM the curated
+    world-model (so they resolve by construction). Numbers are tool-sourced; the prose is presentation only."""
+    from pen_stack.graph import build_graph
+    from pen_stack.verify import verify
+    g = build_graph()
+    v = verify(design)
+    fam = design.get("writer_family")
+    veh = design.get("delivery_vehicle")
+    cites: list[dict] = []
+    wnode = g.nodes.get(f"writer:{fam}")
+    if wnode:
+        for d in wnode.props.get("dois", [])[:1]:
+            cites.append({"doi": d, "claim": f"{fam} mechanism / characterisation", "source": "world-model writer"})
+    vnode = g.nodes.get(f"vehicle:{veh}")
+    if vnode:
+        for d in vnode.props.get("dois", [])[:1]:
+            cites.append({"doi": d, "claim": f"{veh} delivery properties", "source": "world-model vehicle"})
+    form = wnode.props.get("output_form") if wnode else None
+    verdict = "legal" if v.legal else "illegal"
+    rationale = (f"{fam} ({form}-form) installs a {design.get('cargo_bp')} bp cargo via {veh}; the rule-grounded "
+                 f"verifier judges this {verdict}"
+                 + (f" (violated: {', '.join(x['rule_id'] for x in v.violations)})" if not v.legal else "")
+                 + (f"; calibrated confidence {v.confidence}" if v.confidence is not None else
+                    "; confidence abstained (unscored)") + ".")
+    guard = citations_grounded([c["doi"] for c in cites])
+    return {"design": {k: val for k, val in design.items() if not str(k).startswith("_")},
+            "rationale": rationale, "citations": cites, "n_citations": len(cites),
+            "citations_grounded": guard["all_grounded"], "ungrounded_citations": guard["ungrounded"],
+            "no_fabrication": v.no_fabrication and guard["all_grounded"],
+            "note": "citations are drawn from the curated world-model (resolve by construction); numbers are "
+                    "verifier-sourced; the prose is a presentation layer (no fabricated quantity)."}
+
+
+# --------------------------------------------------------------------------------------------------
+# Scoped generalisation: grounded-or-refused.
+# --------------------------------------------------------------------------------------------------
+# adjacent genetic-engineering tasks that MAP to an existing grounded capability (answerable);
+# anything else is refused with a scope statement.
+_GROUNDED_TASKS = {
+    "delivery_selection": "maps to the delivery rules (cargo-form + capacity + integration)",
+    "write_type_legality": "maps to the write-type router + verifier",
+    "off_target_screen": "maps to the bridge off-target engine (a screen, not a per-site calculator)",
+    "writer_variant_critique": "maps to the writer-verification branch (score/critique, never invent)",
+}
+
+
+def generalise(task: str, payload: dict | None = None) -> dict:
+    """Answer an adjacent genetic-engineering task ONLY if it maps to a grounded capability; otherwise REFUSE
+    with a scope statement (Principle 4: grounded-or-refused, never faked)."""
+    payload = payload or {}
+    if task not in _GROUNDED_TASKS:
+        return {"task": task, "grounded": False, "refused": True,
+                "scope_statement": f"'{task}' has no grounding in PEN-STACK; refused rather than faked. "
+                                   f"Grounded tasks: {sorted(_GROUNDED_TASKS)}.",
+                "no_fabrication": True}
+    result: dict = {"task": task, "grounded": True, "refused": False,
+                    "grounding": _GROUNDED_TASKS[task], "no_fabrication": True}
+    if task in ("delivery_selection", "write_type_legality") and payload:
+        from pen_stack.verify import verify
+        v = verify(payload)
+        result["verdict"] = {"legal": v.legal, "confidence": v.confidence,
+                             "violations": [x["rule_id"] for x in v.violations]}
+    return result