pen-stack 0.1.0__py3-none-any.whl

pen_stack/verify/proof.py

@@ -0,0 +1,206 @@
+"""Repair-oriented proof object for verify().
+
+``verify(design)`` already returns legality, a calibrated confidence and a biosecurity verdict as separate
+fields. ``verify_proof(design)`` repackages that into a machine-readable proof an agent can repair a design
+from: three SEPARATELY-REPORTED axes (legality, confidence, biosecurity), each carrying a status, the rule or
+signature that fired, the supporting evidence, and a repair hint. The single collapsed verdict is always
+``None`` (the axes are never fused), per the verification-service invariant.
+
+Repair hints are actionable for legality (a structured field edit that an agent, or ``repair_from_proof``, can
+apply and re-verify) and for the confidence abstention (which scores to supply). Biosecurity repair hints are
+deliberately NON-ACTIONABLE for a hazard: a refused or escalated design is acknowledged and routed to human
+biosafety review, never auto-repaired and never given instructions toward the hazard. Generation may be
+intractable; verification, and repairing a failed-on-legality design, is tractable, which is the point.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from pen_stack.planner.delivery_vehicles import names as _vehicle_names
+from pen_stack.planner.delivery_vehicles import vehicle as _vehicle
+from pen_stack.rules import Design
+from pen_stack.verify.schema import Verdict
+from pen_stack.verify.service import verify
+
+AXES = ("legality", "confidence", "biosecurity")
+
+
+class AxisProof(BaseModel):
+    axis: str # one of AXES
+    status: str # pass | fail | abstain | refuse | escalate | flag | deferred
+    ok: bool # True when this axis does not block (pass/flag/clear; abstain is ok-but-uncertain for confidence)
+    violated: list[dict[str, Any]] = Field(default_factory=list) # the rule(s)/signature(s) that fired
+    evidence: dict[str, Any] = Field(default_factory=dict)
+    repair_hint: dict[str, Any] | None = None # {text, repair?: {field, set_to}} | None
+
+
+class Proof(BaseModel):
+    design: dict[str, Any]
+    write_type: str
+    axes: list[AxisProof]
+    collapsed: None = None # the three axes are NEVER fused into one verdict
+    passable: bool # legality passes AND biosecurity does not refuse/escalate (confidence may abstain)
+    no_fabrication: bool = True
+    provenance: dict[str, Any] = Field(default_factory=dict)
+
+    def axis(self, name: str) -> AxisProof:
+        return next(a for a in self.axes if a.axis == name)
+
+
+def _pick_vehicle(cargo_bp: int | None, form: str | None, non_integrating: bool) -> str | None:
+    """Smallest-capacity vehicle that carries ``form``, fits ``cargo_bp``, and respects an integration goal.
+    Deterministic; used to turn a legality violation into a concrete repair."""
+    best: tuple[str, float] | None = None
+    for name in _vehicle_names():
+        rec = _vehicle(name) or {}
+        forms = rec.get("compatible_cargo_form") or []
+        if form and form not in forms:
+            continue
+        if non_integrating and rec.get("integrating"):
+            continue
+        cap = rec.get("cargo_capacity_bp")
+        if cargo_bp is not None and cap is not None and cap < cargo_bp:
+            continue
+        score = float(cap) if cap is not None else float("inf")
+        if best is None or score < best[1]:
+            best = (name, score)
+    return best[0] if best else None
+
+
+def _repair_for_violation(d: Design, rule_id: str) -> dict[str, Any] | None:
+    """A structured, applyable repair for a repairable legality violation, or None if not auto-repairable."""
+    form = d.writer_output_form or ("DNA" if d.write_type in ("insertion", "replacement", "landing_pad") else None)
+    if rule_id in ("payload.cargo_within_capacity", "delivery.cargo_form_compatible"):
+        veh = _pick_vehicle(d.cargo_bp, form, non_integrating=bool(d.no_integration))
+        if veh and veh != d.delivery_vehicle:
+            why = ("cargo exceeds the vehicle packaging capacity" if "capacity" in rule_id
+                   else "the cargo form is not compatible with the vehicle")
+            return {"text": f"{why}; switch to a vehicle that fits ({veh}).",
+                    "repair": {"field": "delivery_vehicle", "set_to": veh}}
+    if rule_id == "delivery.no_integration_constraint":
+        veh = _pick_vehicle(d.cargo_bp, form, non_integrating=True)
+        if veh and veh != d.delivery_vehicle:
+            return {"text": f"the goal forbids integration but the vehicle integrates; switch to {veh}.",
+                    "repair": {"field": "delivery_vehicle", "set_to": veh}}
+    if rule_id == "reachability.target_element_available":
+        return {"text": "the writer cannot reach the target as specified; declare a pre-installed landing pad "
+                        "(installed_att) or choose a writer family whose target element is present.",
+                "repair": {"field": "installed_att", "set_to": True}}
+    if rule_id == "compliance.germline_prohibition":
+        return {"text": "this is a heritable / germline edit, which is out of scope for this somatic-editing "
+                        "tool and is broadly prohibited (international moratorium); restrict to SOMATIC editing - "
+                        "move to ex vivo (in_vivo = false) and/or a somatic cell type (e.g. hepatocytes / HepG2, "
+                        "HSPCs), and drop any germline/heritable intent. (Not auto-repairable: a germline edit is "
+                        "a change of intent, not a field fix.)",
+                "repair": None}
+    return None
+
+
+_SAFETY_REFUSED_SOURCE = "safety_gate(refused)"  # the exact provenance.source verify.service sets on early-return
+
+
+def _legality_axis(d: Design, v: Verdict) -> AxisProof:
+    if v.provenance.get("source") == _SAFETY_REFUSED_SOURCE:
+        # biosecurity refused BEFORE the rules engine ran (verify.service short-circuits on refuse), legality
+        # was never evaluated, so no rule fired and there is nothing to cite. Reporting "fail" here would
+        # fabricate a legality verdict for an axis that never ran. State: unknown, not itself blocking
+        # (biosecurity already blocks `passable`), mirrors the "abstaining is a deferral, not a block" convention
+        # already used by the confidence axis.
+        return AxisProof(axis="legality", status="not_evaluated", ok=True,
+                         evidence={"reason": "biosecurity refused this design before legality was evaluated"},
+                         repair_hint={"text": "legality was not evaluated, biosecurity refused this design "
+                                              "first. Legality can only be checked once the biosecurity concern "
+                                              "is resolved (route to institutional biosafety / IBC review).",
+                                      "repair": None})
+    if v.deferred:
+        return AxisProof(axis="legality", status="deferred", ok=False,
+                         evidence={"reason": v.routing.get("reason", "unsupported write type")},
+                         repair_hint={"text": "the write type is not yet supported; route to a supported type."})
+    if v.legal:
+        return AxisProof(axis="legality", status="pass", ok=True,
+                         evidence={"rules_version": v.provenance.get("rules_version")})
+    first = v.violations[0] if v.violations else None
+    hint = _repair_for_violation(d, first["rule_id"]) if first else None
+    return AxisProof(axis="legality", status="fail", ok=False,
+                     violated=[{"rule_id": x["rule_id"], "reason": x["reason"], "citation": x.get("citation", [])}
+                               for x in v.violations],
+                     evidence={"n_violations": len(v.violations)}, repair_hint=hint)
+
+
+def _confidence_axis(v: Verdict) -> AxisProof:
+    if v.provenance.get("source") == _SAFETY_REFUSED_SOURCE:
+        # same short-circuit: confidence was never computed. The "uncalibrated" repair hint below would be
+        # ACTIVELY MISLEADING here, supplying the soft scores would not help, since the block happens before
+        # they would ever be read.
+        return AxisProof(axis="confidence", status="not_evaluated", ok=True,
+                         evidence={"confidence": None, "interval": None,
+                                   "reason": "biosecurity refused this design before confidence was evaluated"},
+                         repair_hint={"text": "confidence was not evaluated, biosecurity refused this design "
+                                              "before reaching the confidence check.", "repair": None})
+    if v.confidence is None:
+        return AxisProof(axis="confidence", status="abstain", ok=True, # abstaining is a deferral, not a block
+                         evidence={"confidence": None, "interval": None},
+                         repair_hint={"text": "confidence is uncalibrated for this design; supply the soft "
+                                              "per-axis scores (safety, p_durable, writer_activity) to calibrate."})
+    return AxisProof(axis="confidence", status="pass", ok=True,
+                     evidence={"confidence": v.confidence, "interval": v.interval,
+                               "epistemic_status": v.epistemic_status})
+
+
+def _biosecurity_axis(v: Verdict) -> AxisProof:
+    s = v.safety
+    if s is None:
+        return AxisProof(axis="biosecurity", status="pass", ok=True, evidence={"decision": "clear"})
+    blocked = s.decision in ("refuse", "escalate")
+    # Carry the same detail Guardian's own /api/safety view shows (which signature, and for a
+    # sequence-domain hit, which Pfam accession + bit score) -- Design Studio's Proof was previously
+    # stripping this down to a bare signature id with no reason/citation/evidence.
+    sigs = [{"signature": h.provenance.get("signature_id"), "kind": h.kind, "severity": h.severity,
+             "reason": h.detail, "citation": [c for c in [h.provenance.get("control_ref")] if c],
+             **({"pfam_accession": h.evidence.get("pfam_accession"), "bit_score": h.evidence.get("bit_score")}
+                if h.kind == "sequence_homology" else {})}
+            for h in (s.hits or [])]
+    # repair hints for a hazard are deliberately NON-actionable: acknowledge and route to human review.
+    hint = None
+    if blocked:
+        hint = {"text": "this design matches a controlled-hazard signature; it is not auto-repairable. "
+                        "Route to institutional biosafety / IBC review. (No actionable repair is provided.)",
+                "repair": None}
+    return AxisProof(axis="biosecurity", status=s.decision, ok=not blocked,
+                     violated=sigs, evidence={"decision": s.decision, "reason": s.reason}, repair_hint=hint)
+
+
+def verify_proof(design: Design | dict, question: str | None = None, *, actor: str = "anonymous") -> Proof:
+    """Verify a design and return the per-axis proof object. The three axes are reported separately and the
+    collapsed verdict is always None. ``passable`` is True when legality passes and biosecurity does not
+    refuse/escalate (an abstaining confidence axis does not block)."""
+    d = Design(**dict(design)) if isinstance(design, dict) else design
+    v = verify(design, question=question, actor=actor)
+    axes = [_legality_axis(d, v), _confidence_axis(v), _biosecurity_axis(v)]
+    legality_ok = axes[0].ok
+    biosec_ok = axes[2].ok
+    return Proof(design=d.model_dump(exclude_none=True), write_type=d.write_type, axes=axes,
+                 passable=bool(legality_ok and biosec_ok),
+                 provenance={"source": "verify_proof", "rules_version": v.provenance.get("rules_version")})
+
+
+def repair_from_proof(design: Design | dict, proof: Proof) -> Design:
+    """Apply the structured repairs carried by the proof's axes (legality first) and return the repaired
+    Design. Uses ONLY the proof object, never re-inspecting the engine, so it demonstrates the proof is
+    agent-repairable. Biosecurity hazards are never auto-repaired (their repair is None)."""
+    d = Design(**dict(design)) if isinstance(design, dict) else Design(**design.model_dump())
+    patch: dict[str, Any] = {}
+    for ax in proof.axes:
+        hint = ax.repair_hint
+        if not hint:
+            continue
+        rep = hint.get("repair")
+        if rep and rep.get("field") is not None:
+            patch[rep["field"]] = rep["set_to"]
+    if not patch:
+        return d
+    data = d.model_dump()
+    data.update(patch)
+    return Design(**data)

pen_stack/verify/schema.py

@@ -0,0 +1,53 @@
+"""The Verdict object returned by the verification service.
+
+Carries legality + the named rejections + a calibrated confidence + an epistemic status + scope flags, with
+legality and confidence kept as separate fields (never collapsed). Serializable for REST/MCP.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from pen_stack.safety.policy import SafetyVerdict
+
+
+class Verdict(BaseModel):
+    """Frozen: the verification result is immutable once returned, so legality, the named violations, the
+    calibrated confidence, and the nested (also-frozen) safety verdict cannot be rewritten after the fact.
+    Build a changed verdict with `model_copy(update=...)` if a transform genuinely needs one."""
+    model_config = ConfigDict(frozen=True)
+
+    legal: bool | None # True/False; None when the write type is deferred
+    deferred: bool = False
+    write_type: str
+    routing: dict[str, Any] = Field(default_factory=dict)
+    rule_results: list[dict] = Field(default_factory=list)
+    violations: list[dict] = Field(default_factory=list) # named hard-rule rejections + citation
+    soft_flags: list[dict] = Field(default_factory=list) # soft penalties raised
+    scope_flags: list[dict] = Field(default_factory=list) # known-unknowns + rule scope flags
+    confidence: float | None = None # calibrated confidence on the SOFT components (distinct axis)
+    interval: list[float] | None = None
+    epistemic_status: str = "not-computable"
+    provenance: dict[str, Any] = Field(default_factory=dict)
+    no_fabrication: bool = True
+    writer_critique: dict[str, Any] | None = None # critique of a generated candidate writer
+                                                     # (pass/flag + reasons); NEVER a claim that it works
+    delivery_profile: dict[str, Any] | None = None # documented ordinal immune/safety/efficacy
+                                                     # priors for the chosen vehicle (NEVER a predicted magnitude)
+    immune_profile: dict[str, Any] | None = None # per-axis immune-risk vector (genotox/CD8/
+                                                     # innate/NAb/anti-PEG), each w/ own uncertainty + validation
+                                                     # label; collapsed_score is None (never fused); magnitude KU
+    safety: SafetyVerdict | None = None # the Guardian: biosecurity/dual-use screen
+                                                     # (clear/flag/refuse/escalate); a refused design is NOT
+                                                     # evaluated further; orthogonal to immune_profile
+
+    def summary(self) -> str:
+        if self.safety is not None and self.safety.decision == "refuse":
+            return f"REFUSED (safety): {self.safety.reason}"
+        if self.deferred:
+            return f"DEFERRED ({self.write_type}): {self.routing.get('reason', 'unsupported write type')}"
+        verdict = "LEGAL" if self.legal else "ILLEGAL"
+        conf = f"conf={self.confidence}" if self.confidence is not None else "conf=n/a (abstained)"
+        why = "" if self.legal else " | " + "; ".join(v["rule_id"] for v in self.violations)
+        return f"{verdict} [{self.epistemic_status}, {conf}]{why}"

pen_stack/verify/service.py

@@ -0,0 +1,191 @@
+"""The verification service, `verify(design) -> Verdict`.
+
+The first-class "for the AI" surface: submit a proposed genomic write, get back a structured verdict,
+legality (from the rule solver), the named reason + citation for any rejection, a calibrated confidence
+on the *soft* components (from the L4 trust layer), an epistemic status, and any out-of-scope flags.
+Thin orchestration over existing layers; it generates **no new numbers** (no-fabrication holds: legality is
+rule-deterministic, confidence comes from the calibrated tool, scope from the registry).
+
+Legality and confidence are DISTINCT axes (Principle 2) and are never collapsed: a design can be
+legal-but-low-confidence or illegal-with-certainty. The Verdict carries both, separately.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pen_stack.rules import Design
+from pen_stack.rules.loader import RULES_VERSION
+from pen_stack.verify.schema import Verdict
+
+
+def _plan_confidence(design: Design) -> dict:
+    """Calibrated plan confidence on the SOFT components, only when the design carries the per-axis scores
+    (safety / p_durable / writer_activity). Otherwise None (abstain), never fabricated."""
+    extra = design.model_extra or {}
+    keys = ("safety", "p_durable", "writer_activity")
+    if not all(k in extra and extra[k] is not None for k in keys):
+        return {"confidence": None, "interval": None}
+    import pandas as pd
+
+    from pen_stack.planner.optimize import attach_uncertainty
+    row = pd.DataFrame([{"chrom": design.chrom or "chr?", "bin": 0,
+                         "safety": float(extra["safety"]), "p_durable": float(extra["p_durable"]),
+                         "writer_activity": float(extra["writer_activity"]), "score": 0.0}])
+    intent = design.edit_intent or "safe_harbour_insertion"
+    out = attach_uncertainty(row, intent, ood_factor=float(extra.get("ood_factor", 1.0)))
+    r = out.iloc[0]
+    return {"confidence": float(r["confidence"]), "interval": [float(r["score_lo"]), float(r["score_hi"])]}
+
+
+def verify(design: Design | dict, question: str | None = None, *, actor: str = "anonymous") -> Verdict:
+    """Verify a proposed write. ``design`` may be a Design or a plain dict (e.g. from REST/MCP JSON).
+
+    The Guardian: a biosecurity / dual-use safety gate runs FIRST. A design that matches a high-severity
+    hazard signature is REFUSED and returned un-evaluated (not scored further); every call is logged to the
+    tamper-evident audit trail. The safety verdict is orthogonal to the immune profile and is attached to
+    every Verdict. ``actor`` is recorded in the audit log."""
+    if isinstance(design, dict):
+        d = dict(design)
+        question = question or d.pop("question", None)
+        screen_payload = dict(d)
+        design = Design(**d)
+    else:
+        screen_payload = {**design.model_dump(exclude_none=False), **(design.model_extra or {})}
+
+    # The safety gate is the first thing every caller inherits.
+    from pen_stack.safety.gate import safety_gate
+    safety = safety_gate(screen_payload, actor=actor)
+    if safety.decision == "refuse":
+        return Verdict(
+            legal=None, deferred=False, write_type=design.write_type, routing={},
+            rule_results=[], violations=[], soft_flags=[],
+            scope_flags=[{"kind": "safety_refused", "reason": safety.reason,
+                          "signatures": [h.provenance.get("signature_id") for h in safety.hits]}],
+            confidence=None, interval=None, epistemic_status="refused",
+            provenance={"rules_version": RULES_VERSION, "source": "safety_gate(refused)"},
+            no_fabrication=True, safety=safety)
+
+    from pen_stack.agent.epistemic import classify
+    from pen_stack.planner.router import route_and_evaluate
+
+    routed = route_and_evaluate(design)
+    routing = routed["routing"]
+
+    # scope: out-of-scope question (known-unknowns) + rule scope_flags
+    scope_flags: list[dict[str, Any]] = []
+    oos_hit = False
+    if question:
+        from pen_stack.agent.scope import match_scope
+        m = match_scope(question)
+        if m:
+            oos_hit = True
+            scope_flags.append({"kind": "known_unknown", "id": m["id"], "reason": m["deferral"]})
+
+    if routed["deferred"]:
+        verdict = classify(grounded=False, out_of_scope=True)
+        return Verdict(
+            legal=None, deferred=True, write_type=design.write_type, routing=routing,
+            rule_results=[], violations=[], soft_flags=[],
+            scope_flags=scope_flags + [{"kind": "unsupported_write_type", "reason": routing["reason"]}],
+            confidence=None, interval=None, epistemic_status=verdict.status,
+            provenance={"rules_version": RULES_VERSION, "source": "router(deferred)"}, no_fabrication=True,
+            safety=safety)
+
+    results = routed["rule_results"]
+    violations = [r for r in results if r["kind"] == "hard_reject" and r["status"] == "violate"]
+    soft = [r for r in results if r["kind"] == "soft_penalty" and r["status"] == "flag"]
+    rule_scope = [{"kind": "rule_scope", "rule_id": r["rule_id"], "reason": r["reason"]}
+                  for r in results if r["kind"] == "scope_flag" and r["status"] == "scope"]
+    scope_flags += rule_scope
+
+    # Chromosome validation + gene/chromosome concordance + chromosome-context advisory. The free-text
+    # chrom field does not move the scored locus (scoring is indexed by the gene's resolved coordinates), so a
+    # mismatch / invalid value / chromosome-context note is surfaced as a scope flag, never silently ignored.
+    from pen_stack.planner.chromosome import chromosome_concordance, chromosome_context
+    conc = chromosome_concordance(design.gene, getattr(design, "chrom", None))
+    if conc["status"] in ("invalid", "mismatch", "unverifiable"):
+        scope_flags.append({"kind": f"chromosome_{conc['status']}", "reason": conc["message"],
+                            "entered": conc["entered"], "gene_chrom": conc["gene_chrom"]})
+    ctx = chromosome_context(getattr(design, "chrom", None))
+    if ctx:
+        scope_flags.append({"kind": "chromosome_context", "chrom": ctx["chrom"], "reason": ctx["note"]})
+
+    pc = _plan_confidence(design)
+    # A design with no calibrated confidence (the soft-axis scores were absent, so _plan_confidence abstained)
+    # must NOT read as grounded-confident: a missing confidence is an abstention, not a high-trust result.
+    verdict = classify(grounded=True, confidence=pc["confidence"],
+                       abstained=pc["confidence"] is None, out_of_scope=oos_hit)
+
+    # If the design carries a GENERATED candidate writer sequence, critique it (fold / active
+    # site / deliverability / reachability), never a claim that it works. Adds a scope flag, never confidence.
+    writer_critique = None
+    cand_seq = (design.model_extra or {}).get("writer_candidate_seq")
+    if cand_seq:
+        from pen_stack.atlas.writer_verify import critique_candidate
+        writer_critique = critique_candidate(
+            cand_seq, writer_family=design.writer_family or "bridge_IS110",
+            delivery_vehicle=design.delivery_vehicle, no_integration=design.no_integration,
+            site_seq=design.site_seq)
+        scope_flags.append({"kind": "writer_candidate_critique", "pass": writer_critique["pass"],
+                            "flags": writer_critique["flags"],
+                            "reason": "generated writer is critiqued, never claimed to work"})
+
+    # If the design names a delivery vehicle, surface its DOCUMENTED ordinal immune/safety/
+    # efficacy priors (with the standing "magnitude is a known-unknown" scope flag). This never adds confidence
+    # and never predicts a magnitude, it exposes the curated qualitative tradeoff so safety can be weighed.
+    delivery_profile = None
+    if design.delivery_vehicle:
+        from pen_stack.planner.delivery_immunology import safety_efficacy_profile
+        delivery_profile = safety_efficacy_profile(design.delivery_vehicle)
+        if delivery_profile and delivery_profile.get("tradeoff"):
+            scope_flags.append({"kind": "delivery_immune_profile",
+                                "vehicle": delivery_profile["vehicle"],
+                                "tradeoff": delivery_profile["tradeoff"],
+                                "magnitude_id": delivery_profile["magnitude_scope_flag"]["id"],
+                                "reason": "documented ordinal immune/safety priors surfaced; the in-vivo immune "
+                                          "MAGNITUDE remains a known-unknown (not predicted)"})
+
+    # If a cargo SEQUENCE is supplied, compute its innate-sensing load from sequence
+    # (CpG/TLR9 for DNA, U/dsRNA for mRNA). Surfaced as a scope flag; the realized innate RESPONSE magnitude
+    # is a known-unknown. Cargo form = the writer output form, else the vehicle's first compatible form.
+    if design.cargo_seq:
+        form = design.writer_output_form
+        if not form and design.delivery_vehicle:
+            from pen_stack.planner.delivery_vehicles import vehicle as _veh
+            forms = (_veh(design.delivery_vehicle) or {}).get("compatible_cargo_form") or []
+            form = forms[0] if forms else None
+        if form:
+            from pen_stack.planner.innate_sensing import innate_sensing
+            inr = innate_sensing(design.cargo_seq, form)
+            if inr.available:
+                scope_flags.append({"kind": "cargo_innate_sensing", "cargo_form": form,
+                                    "innate_score": inr.value["innate_score"], "pathway": inr.value["pathway"],
+                                    "reason": "computed sequence-intrinsic innate-sensing load; the realized "
+                                              "in-vivo innate RESPONSE magnitude is a known-unknown"})
+                if delivery_profile is not None:
+                    delivery_profile = dict(delivery_profile)
+                    delivery_profile["cargo_innate"] = inr.value
+
+    # The unified per-axis immune-risk profile (genotox / CD8 epitope / innate / pre-existing
+    # NAb / anti-PEG), each with its own uncertainty + validation label; collapsed_score is None
+    # (never fused into one number); the in-vivo magnitude + patient titer stay known-unknowns.
+    immune_profile = None
+    if design.delivery_vehicle:
+        from pen_stack.planner.immune_profile import immune_profile as _immune_profile
+        extra = design.model_extra or {}
+        immune_profile = _immune_profile({
+            "delivery_vehicle": design.delivery_vehicle, "serotype": extra.get("serotype"),
+            "cargo_seq": design.cargo_seq, "writer_output_form": design.writer_output_form,
+            "pegylated": extra.get("pegylated")})
+
+    return Verdict(
+        legal=routed["legal"], deferred=False, write_type=design.write_type, routing=routing,
+        rule_results=results,
+        violations=[{"rule_id": v["rule_id"], "reason": v["reason"], "citation": v.get("citation", [])}
+                    for v in violations],
+        soft_flags=[{"rule_id": s["rule_id"], "reason": s["reason"], "value": s.get("value")} for s in soft],
+        scope_flags=scope_flags,
+        confidence=pc["confidence"], interval=pc["interval"], epistemic_status=verdict.status,
+        provenance={"rules_version": RULES_VERSION, "source": "rules.solver + L4(uncertainty/scope/epistemic)"},
+        no_fabrication=True, writer_critique=writer_critique, delivery_profile=delivery_profile,
+        immune_profile=immune_profile, safety=safety)

pen_stack/web/__init__.py

@@ -0,0 +1,18 @@
+"""PEN-STACK Web Platform, the human surface.
+
+A grounded co-scientist chat + every engine feature behind one typed gateway, with provenance-first UX. The LLM narrates
+and routes; the engine sources every number. Submodules:
+
+* ``tools``, the deterministic engine tool-runner (parse a goal, run verify/safety/immune/scope, return a
+  grounded dossier) and the grounding allow-list.
+* ``llm``, the grounded co-scientist (Ollama → Nemotron → deterministic) with the grounding-guard hard gate.
+* ``server``, the FastAPI gateway (mounts the engine surface + ``/chat``); needs the ``server`` extra.
+
+``server`` is imported lazily (it requires FastAPI) so ``import pen_stack.web`` works on a bare install.
+"""
+from __future__ import annotations
+
+from pen_stack.web.llm import grounded_reply
+from pen_stack.web.tools import extract_grounded_numbers, parse_goal, run_tools
+
+__all__ = ["grounded_reply", "run_tools", "parse_goal", "extract_grounded_numbers"]

pen_stack/web/guide.py

@@ -0,0 +1,110 @@
+"""Metric interpretation + PEN-STACK capability facts (the explain/meta lanes).
+
+Two grounded sources the hybrid co-scientist narrates over WITHOUT fabricating:
+  * `metric_guide()`, curated interpretation cards (configs/metric_guide.yaml): what each engine number means,
+    its scale/direction, reference bands, how it is computed, validation status. Used to EXPLAIN a value.
+  * `pen_stack_facts()`, capability facts assembled from LIVE engine data (writer atlas coverage, the delivery
+    palette, the immune axes, the known-unknowns), so "how many enzymes / vectors / axes, how accurate" is
+    answered from the system itself, not invented.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+
+
+@lru_cache(maxsize=1)
+def metric_guide() -> dict:
+    return yaml.safe_load(resource("configs/metric_guide.yaml").read_text(encoding="utf-8"))
+
+
+def guide_for(metric: str) -> dict | None:
+    """The interpretation card for a metric name (immune axis / verdict field)."""
+    return (metric_guide().get("metrics") or {}).get(metric)
+
+
+def enrich_axes(axes: dict) -> dict:
+    """Attach the interpretation card (meaning/scale/bands/computed/validation/reference) to each immune axis."""
+    out = {}
+    for name, a in (axes or {}).items():
+        g = guide_for(name)
+        out[name] = {**a, "guide": g} if g else a
+    return out
+
+
+@lru_cache(maxsize=1)
+def pen_stack_facts() -> dict:
+    """GROUNDED facts about what PEN-STACK covers + how it computes, assembled from live engine data, never
+    hand-typed counts. Answers the 'meta' lane ('how many enzymes/vectors/axes, how is X computed, how accurate')."""
+    facts: dict = {"disclaimer": (metric_guide() or {}).get("disclaimer")}
+
+    # writer atlas coverage (enzymes / families), from the committed atlas
+    try:
+        import pandas as pd
+
+        from pen_stack import __file__ as _pkg
+        from pathlib import Path
+        atlas = pd.read_parquet(Path(_pkg).resolve().parents[0] / "atlas" / "atlas.parquet")
+        facts["writers"] = {
+            "systems": int(len(atlas)),
+            "families": sorted(atlas["family"].astype(str).unique().tolist()),
+            "n_families": int(atlas["family"].nunique()),
+            "measured": int((atlas["confidence"] == "measured").sum()) if "confidence" in atlas.columns else None,
+            "note": "writer = genome-writing enzyme system (integrases, recombinases, nucleases, transposases) on "
+                    "common measured axes (cargo capacity, programmability, DSB-freeness, human-cell activity, "
+                    "deliverability).",
+        }
+    except Exception:
+        facts["writers"] = {"note": "writer atlas requires the committed atlas.parquet"}
+
+    # delivery palette (vectors)
+    try:
+        from pen_stack.planner.delivery_vehicles import names as _vnames
+        from pen_stack.planner.delivery_vehicles import vehicle as _veh
+        vs = _vnames()
+        viral = [v for v in vs if (_veh(v) or {}).get("class", "").lower().startswith("vir")
+                 or any(k in v.lower() for k in ("aav", "lenti", "adeno", "hsv", "virus"))]
+        facts["delivery"] = {
+            "n_vehicles": len(vs), "vehicles": list(vs),
+            "viral_like": viral, "nonviral_like": [v for v in vs if v not in viral],
+            "note": "each vehicle carries documented cargo capacity, integration status, cargo-form compatibility "
+                    "(DNA/mRNA/RNP) and an ordinal immune/safety prior; the planner picks compatible vehicles.",
+        }
+    except Exception:
+        facts["delivery"] = {"note": "delivery palette in configs/delivery_vehicles.yaml"}
+
+    # immune-risk axes (how immunogenicity is computed) + their guides
+    axes = ["genotoxicity", "cd8_epitope", "innate", "preexisting_nab", "anti_peg"]
+    facts["immunogenicity"] = {
+        "n_axes": len(axes), "axes": axes,
+        "never_collapsed": "the per-axis profile is never fused into one score (collapsed_score is None), the "
+                           "axes measure different mechanisms on different evidence.",
+        "how": {a: (guide_for(a) or {}).get("computed") for a in axes},
+        "validation": {a: (guide_for(a) or {}).get("validation") for a in axes},
+    }
+
+    # accuracy and grounding posture + the known-unknowns
+    try:
+        from pen_stack.agent.scope import load_registry
+        kus = [{"id": e["id"], "title": e["title"]} for e in load_registry()]
+    except Exception:
+        kus = []
+    facts["accuracy"] = {
+        "posture": "every number is a tool-computed proxy with a stated scope; proxies are labelled "
+                   "'mechanistic/population proxy, NOT outcome-validated'; the engine ABSTAINS or flags "
+                   "out-of-scope rather than guess; nothing is fabricated.",
+        "known_unknowns": kus,
+        "what_is_NOT_predicted": "functional titer / % of normal, in-vivo response magnitude, long-term clinical "
+                                 "durability, phenotype, these are measured clinical endpoints, never predicted.",
+    }
+
+    # live foundation-model oracles (which execute live + their latency class)
+    try:
+        from pen_stack.oracles.status import summary as _orsum
+        facts["foundation_models"] = _orsum()
+    except Exception:
+        facts["foundation_models"] = {"note": "oracle execution map in configs/oracles/execution.yaml"}
+    return facts