pen-stack 0.1.0__py3-none-any.whl

pen_stack/rules/evaluators.py

@@ -0,0 +1,318 @@
+"""Rule evaluators, the bridge from rules-as-data to the existing validated code.
+
+Each evaluator runs ONE rule against a ``Design`` and returns a ``RuleResult``. Crucially, evaluators
+**delegate to the functions that already implement the logic** (``planner.target_site``, ``bridge.fold_qc``,
+``planner.delivery_constraints``, ``planner.multiplex``, and the delivery-vehicle table), so lifting the
+rules into data changes no decision (the parity test proves it). An evaluator whose required inputs are
+absent returns ``not_applicable`` (never a spurious violate), so a partial design is still checkable.
+
+Evaluators are registered by name; a rule's ``evaluator`` field names the function. To add a rule you add a
+YAML record + (if new) one evaluator here, never scattered ``if`` checks in the planner.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+
+from pen_stack.rules.schema import Design, Rule, RuleResult
+
+_REGISTRY: dict[str, Callable[[Design, Rule], RuleResult]] = {}
+
+
+def evaluator(name: str):
+    def deco(fn):
+        _REGISTRY[name] = fn
+        return fn
+    return deco
+
+
+def get_evaluator(name: str) -> Callable[[Design, Rule], RuleResult]:
+    if name not in _REGISTRY:
+        raise KeyError(f"no rule evaluator registered as {name!r}")
+    return _REGISTRY[name]
+
+
+def registered_evaluators() -> set[str]:
+    """Names of every registered evaluator (used by the rule-spec export to confirm each rule is executable)."""
+    return set(_REGISTRY)
+
+
+def _result(rule: Rule, status: str, reason: str, value=None) -> RuleResult:
+    return RuleResult(rule_id=rule.id, kind=rule.kind, category=rule.category, status=status,
+                      reason=reason, citation=list(rule.provenance.get("doi", [])), value=value)
+
+
+def _na(rule: Rule, why: str) -> RuleResult:
+    return _result(rule, "not_applicable", f"not applicable: {why}")
+
+
+# writer output form (what the vehicle must carry) when the design does not state it explicitly.
+_WRITER_FORM = {"bridge_is110": "DNA", "seek_is1111": "DNA", "cast_vk": "DNA",
+                "serine_integrase": "DNA", "pe_integrase": "DNA",
+                "cas9": "RNP", "cas12a": "RNP"}
+
+
+def writer_output_form(design: Design) -> str | None:
+    if design.writer_output_form:
+        return design.writer_output_form
+    return _WRITER_FORM.get(str(design.writer_family or "").lower())
+
+
+# reachability / target-site (delegates to planner.target_site, the hard filter)
+@evaluator("reachability_target_site")
+def reachability_target_site(design: Design, rule: Rule) -> RuleResult:
+    if not design.writer_family or not design.site_seq:
+        return _na(rule, "no writer_family + site_seq")
+    from pen_stack.planner.target_site import target_site_available
+    v = target_site_available(design.writer_family, design.site_seq, installed_att=design.installed_att)
+    if not v.get("checked", True):
+        return _na(rule, v.get("reason", "family has no target-site rule"))
+    return _result(rule, "pass" if v["available"] else "violate", v["reason"])
+
+
+# fold legality (delegates to bridge.fold_qc cross-loop screen, soft penalty / flag)
+@evaluator("fold_cross_loop")
+def fold_cross_loop(design: Design, rule: Rule) -> RuleResult:
+    if not design.target_guide or not design.donor_guide:
+        return _na(rule, "no bridge-RNA target_guide + donor_guide")
+    from pen_stack.bridge.fold_qc import cross_loop_risk
+    thr = float(rule.param.get("cross_loop_threshold", 0.6))
+    xl = cross_loop_risk(design.target_guide, design.donor_guide)
+    worst = max(xl.values())
+    flagged = [k for k, val in xl.items() if val >= thr]
+    if flagged:
+        return _result(rule, "flag", f"cross-loop complementarity {flagged} >= {thr} "
+                       "(self/TBL-DBL recombination risk)", value=round(worst, 3))
+    return _result(rule, "pass", f"cross-loop complementarity below {thr}", value=round(worst, 3))
+
+
+# payload capacity (cargo_bp <= vehicle capacity, hard reject) + split-AAV penalty (soft)
+@evaluator("payload_capacity")
+def payload_capacity(design: Design, rule: Rule) -> RuleResult:
+    if design.cargo_bp is None or not design.delivery_vehicle:
+        return _na(rule, "no cargo_bp + delivery_vehicle")
+    from pen_stack.planner.delivery_vehicles import vehicle
+    veh = vehicle(design.delivery_vehicle)
+    if veh is None:
+        return _na(rule, f"unknown vehicle {design.delivery_vehicle!r}")
+    cap = veh.get("cargo_capacity_bp")
+    if cap is None:
+        return _na(rule, "vehicle has no capacity (e.g. physical delivery)")
+    if design.cargo_bp > cap:
+        return _result(rule, "violate", f"cargo {design.cargo_bp} bp exceeds {design.delivery_vehicle} "
+                       f"capacity {cap} bp", value=design.cargo_bp)
+    return _result(rule, "pass", f"cargo {design.cargo_bp} bp within {design.delivery_vehicle} "
+                   f"capacity {cap} bp", value=design.cargo_bp)
+
+
+@evaluator("split_aav_penalty")
+def split_aav_penalty(design: Design, rule: Rule) -> RuleResult:
+    if design.cargo_bp is None or not design.delivery_vehicle:
+        return _na(rule, "no cargo_bp + delivery_vehicle")
+    v = str(design.delivery_vehicle).lower()
+    single_cap = int(rule.param.get("single_aav_cap_bp", 4700))
+    if "aav" in v and design.cargo_bp > single_cap:
+        return _result(rule, "flag", f"cargo {design.cargo_bp} bp needs split/dual AAV "
+                       "(efficiency drops sharply)", value=design.cargo_bp)
+    return _result(rule, "pass", "no split-AAV efficiency penalty")
+
+
+# delivery compatibility (writer output-form <-> vehicle; integration constraint, hard reject)
+# write types that install a DNA DONOR cassette (need the donor delivered AS DNA, independent of the writer form)
+_DNA_CASSETTE_WRITES = {"insertion", "replacement", "landing_pad", "landing_pad_install"}
+
+
+@evaluator("delivery_cargo_form")
+def delivery_cargo_form(design: Design, rule: Rule) -> RuleResult:
+    if not design.delivery_vehicle:
+        return _na(rule, "no delivery_vehicle")
+    from pen_stack.planner.delivery_vehicles import vehicle
+    veh = vehicle(design.delivery_vehicle)
+    if veh is None:
+        return _na(rule, f"unknown vehicle {design.delivery_vehicle!r}")
+    forms = veh.get("compatible_cargo_form", [])
+    form = writer_output_form(design)
+    # (1) DNA-donor-cassette install <-> vehicle form. A genomic insertion/replacement/landing-pad by a DNA-writing
+    # system (integrase / recombinase / bridge) installs a DNA donor cassette; an mRNA/RNP-only vehicle (e.g.
+    # LNP-mRNA) cannot deliver a DNA donor for STABLE integration. Fires for DNA-form OR unspecified writers (the
+    # report's gap: "insertion via LNP-mRNA" with no writer named). Skipped for an RNP editor whose RNP delivery is
+    # itself valid, that case is governed by the writer-form check below.
+    if (str(design.write_type or "").lower() in _DNA_CASSETTE_WRITES and (design.cargo_bp or 0) > 0
+            and "DNA" not in forms and form in (None, "DNA")):
+        return _result(rule, "violate", f"a genomic {design.write_type} installs a DNA donor cassette "
+                       f"({design.cargo_bp} bp), but {design.delivery_vehicle} carries {forms}, mRNA is transient "
+                       "and cannot deliver a DNA donor for stable integration; use a DNA-capable vehicle "
+                       "(AAV / lentivirus / electroporation)")
+    # (2) writer output-form <-> vehicle. The writer machinery must itself be deliverable by the vehicle.
+    if form is None:
+        return _na(rule, "no writer output-form to check (and no DNA-cassette conflict)")
+    if form not in forms:
+        return _result(rule, "violate", f"{design.writer_family} delivers {form}, but "
+                       f"{design.delivery_vehicle} carries {forms}")
+    return _result(rule, "pass", f"{form} payload compatible with {design.delivery_vehicle}")
+
+
+@evaluator("delivery_no_integration")
+def delivery_no_integration(design: Design, rule: Rule) -> RuleResult:
+    if not design.delivery_vehicle:
+        return _na(rule, "no delivery_vehicle")
+    if not design.no_integration:
+        return _result(rule, "pass", "no non-integration constraint declared")
+    from pen_stack.planner.delivery_vehicles import vehicle
+    veh = vehicle(design.delivery_vehicle)
+    if veh is None:
+        return _na(rule, f"unknown vehicle {design.delivery_vehicle!r}")
+    if veh.get("integrating"):
+        return _result(rule, "violate", f"goal forbids integration but {design.delivery_vehicle} integrates")
+    return _result(rule, "pass", f"{design.delivery_vehicle} is non-integrating, as required")
+
+
+@evaluator("delivery_aav_packaging")
+def delivery_aav_packaging(design: Design, rule: Rule) -> RuleResult:
+    """Delivery-oracle packaging-margin check: AAV packaging EFFICIENCY drops sharply as the cargo approaches the
+    capsid limit (a computable property of cargo_bp vs the vehicle capacity), even when still under capacity.
+    Soft flag when within the margin; not a titre predictor."""
+    if design.cargo_bp is None or not design.delivery_vehicle:
+        return _na(rule, "no cargo_bp + delivery_vehicle")
+    v = str(design.delivery_vehicle).lower()
+    if "aav" not in v:
+        return _result(rule, "pass", "not an AAV vehicle; packaging-margin check n/a")
+    from pen_stack.planner.delivery_vehicles import vehicle
+    veh = vehicle(design.delivery_vehicle) or {}
+    cap = veh.get("cargo_capacity_bp")
+    if not cap:
+        return _na(rule, "vehicle has no capacity")
+    margin = float(rule.param.get("margin_frac", 0.9)) # within 90-100% of capacity -> efficiency penalty
+    frac = design.cargo_bp / cap
+    if frac >= margin:
+        return _result(rule, "flag", f"cargo {design.cargo_bp} bp is {frac:.0%} of {design.delivery_vehicle} "
+                       f"capacity {cap} bp (packaging efficiency / titre drops near the limit)",
+                       value=round(frac, 3))
+    return _result(rule, "pass", f"cargo {frac:.0%} of capacity (comfortable packaging margin)",
+                   value=round(frac, 3))
+
+
+@evaluator("delivery_sequence_constraints")
+def delivery_sequence_constraints(design: Design, rule: Rule) -> RuleResult:
+    if not design.cargo_seq or not design.delivery_vehicle:
+        return _na(rule, "no cargo_seq + delivery_vehicle")
+    from pen_stack.planner.delivery_constraints import scan_delivery
+    from pen_stack.planner.delivery_vehicles import vehicle
+    veh = vehicle(design.delivery_vehicle) or {}
+    key = veh.get("constraint_key", design.delivery_vehicle)
+    r = scan_delivery(design.cargo_seq, key)
+    if r["flags"]:
+        return _result(rule, "flag", "; ".join(f["detail"] for f in r["flags"]),
+                       value=r["delivery_constraint_risk"])
+    return _result(rule, "pass", "no vehicle-specific sequence flags", value=r["delivery_constraint_risk"])
+
+
+@evaluator("delivery_immunogenicity_scope")
+def delivery_immunogenicity_scope(design: Design, rule: Rule) -> RuleResult:
+    if not design.delivery_vehicle:
+        return _na(rule, "no delivery_vehicle")
+    return _result(rule, "scope", "immunogenicity MAGNITUDE and precise in-vivo tropism are not modeled "
+                   "(declared out of scope, never predicted)")
+
+
+# compliance / scope-of-use legality: heritable human germline editing is out of scope + prohibited
+# A term in declared free text counts only if it is NOT inside a NEGATED span, so a somatic design that says
+# "no germline transmission", "not heritable", "somatic, not germline", or "NOT for reproduction or implantation"
+# (a distributed negation over a list) does not false-fire on the negated word. A negator opens a span that runs
+# across list connectors (or / and / ,) until a clause break (. ; but however yet) or ~60 chars.
+_NEGATOR = re.compile(r"\b(not|non|no|never|without|isn'?t|aren'?t|rather than|as opposed to)\b")
+_CLAUSE_BREAK = re.compile(r"[;.]|\bbut\b|\bhowever\b|\byet\b|\bexcept\b")
+
+
+def _negated_spans(text: str) -> list[tuple[int, int]]:
+    spans = []
+    for m in _NEGATOR.finditer(text):
+        rest = text[m.end():m.end() + 60]
+        brk = _CLAUSE_BREAK.search(rest)
+        spans.append((m.start(), m.end() + (brk.start() if brk else len(rest))))
+    return spans
+
+
+def _intent_present(term: str, text: str, spans: list[tuple[int, int]]) -> bool:
+    t = str(term or "").strip().lower()
+    if not t:
+        return False
+    idx = text.find(t)
+    while idx != -1:
+        if not any(s <= idx < e for s, e in spans):
+            return True  # a non-negated occurrence
+        idx = text.find(t, idx + 1)
+    return False
+
+
+@evaluator("germline_prohibition")
+def germline_prohibition(design: Design, rule: Rule) -> RuleResult:
+    """Hard legality reject for a heritable / germline edit. Fires on (a) a reproductive germline TARGET cell
+    (embryo/zygote/oocyte/sperm/gamete - structured, unconditional), (b) a declared REPRODUCTIVE-USE intent
+    (gametes / assisted reproduction / implantation / 'for reproduction'), (c) a declared HERITABLE intent
+    (germline / heritable / transmitted to offspring), or (d) a germline-COMPETENT cell type (hESC/iPSC) in a
+    heritable context (in vivo, or a reproductive/heritable intent). The free-text intent matches are NEGATION-
+    aware, so a SOMATIC design that explicitly says 'somatic, not germline' / 'no germline transmission' / 'not
+    heritable' is NOT false-flagged, and an ex-vivo somatic use of a germline-competent research line stays in
+    scope. The screen reads the declared design artifact only (not any free-text justification)."""
+    extra = design.model_extra or {}
+
+    def _norm(x) -> str:
+        return str(x or "").strip().lower()
+
+    text = " ".join(_norm(x) for x in (design.edit_intent, extra.get("cargo_function"),
+                                       extra.get("goal_function"), extra.get("function_annotation"),
+                                       extra.get("notes")) if x)
+    ct = _norm(design.cell_type)
+    in_vivo = bool(extra.get("in_vivo")) and _norm(extra.get("in_vivo")) not in ("false", "0", "no")
+    p = rule.param
+
+    spans = _negated_spans(text)
+    repro_ct = [c for c in p.get("germline_cell_types", []) if _norm(c) in ct]
+    competent_ct = [c for c in p.get("germline_competent_cell_types", []) if _norm(c) in ct]
+    repro_intent = [t for t in p.get("reproductive_intent_terms", []) if _intent_present(_norm(t), text, spans)]
+    heritable = [t for t in p.get("heritable_terms", []) if _intent_present(_norm(t), text, spans)]
+
+    triggers = []
+    if repro_ct:
+        triggers.append(f"a reproductive germline target cell ('{repro_ct[0]}')")
+    if repro_intent:
+        triggers.append(f"a declared reproductive-use intent ('{repro_intent[0]}')")
+    if heritable:
+        triggers.append(f"a declared heritable/germline-editing intent ('{heritable[0]}')")
+    if competent_ct and (in_vivo or repro_intent or heritable):
+        ctx = "in vivo" if in_vivo else (repro_intent or heritable)[0]
+        triggers.append(f"a germline-competent cell type ('{competent_ct[0]}') edited in a heritable context "
+                        f"('{ctx}')")
+    if triggers:
+        # de-duplicate while preserving order, then report
+        seen, uniq = set(), []
+        for t in triggers:
+            if t not in seen:
+                seen.add(t)
+                uniq.append(t)
+        return _result(rule, "violate",
+                       "heritable human germline editing is out of scope for this somatic tool and is broadly "
+                       "prohibited (international moratorium): " + "; ".join(uniq)
+                       + ". Restrict to somatic editing (ex vivo, or a somatic cell type / somatic context).")
+    note = ""
+    if competent_ct:
+        note = (f" (cell type '{competent_ct[0]}' is germline-competent; somatic/ex-vivo editing of it is in "
+                "scope, but an in-vivo or reproductive heritable edit would not be)")
+    return _result(rule, "pass", "no heritable/germline-editing intent or germline target declared" + note)
+
+
+# multiplex translocation (delegates to planner.multiplex, soft penalty)
+@evaluator("multiplex_translocation")
+def multiplex_translocation(design: Design, rule: Rule) -> RuleResult:
+    if not design.edits or len(design.edits) < 2:
+        return _na(rule, "fewer than 2 edits")
+    from pen_stack.planner.multiplex import translocation_risk
+    r = translocation_risk(design.edits)
+    risk = r.get("translocation_risk", 0.0)
+    thr = float(rule.param.get("risk_threshold", 0.2))
+    if risk >= thr:
+        return _result(rule, "flag", f"pairwise translocation risk {risk} >= {thr} "
+                       "(concurrent DSBs may mis-join)", value=risk)
+    return _result(rule, "pass", f"translocation risk {risk} < {thr} "
+                   "(DSB-free writers carry ~zero by construction)", value=risk)

pen_stack/rules/loader.py

@@ -0,0 +1,31 @@
+"""Load the rule base from configs/rules/*.yaml into a validated Ruleset."""
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+import yaml
+
+from pen_stack._resources import resource
+from pen_stack.rules.schema import Rule, Ruleset
+
+RULES_VERSION = "1.0"
+_CATEGORIES = ("reachability", "fold", "payload", "multiplex", "delivery", "compliance")
+
+
+@lru_cache(maxsize=1)
+def load_ruleset(rules_dir: str | None = None) -> Ruleset:
+    base = Path(rules_dir) if rules_dir else resource("configs/rules")
+    rules: list[Rule] = []
+    for cat in _CATEGORIES:
+        f = base / f"{cat}.yaml"
+        if not f.exists():
+            continue
+        data = yaml.safe_load(f.read_text(encoding="utf-8")) or {}
+        for rec in data.get("rules", []):
+            rules.append(Rule(**rec))
+    ids = [r.id for r in rules]
+    dupes = {i for i in ids if ids.count(i) > 1}
+    if dupes:
+        raise ValueError(f"duplicate rule ids: {sorted(dupes)}")
+    return Ruleset(version=RULES_VERSION, rules=rules)

pen_stack/rules/schema.py

@@ -0,0 +1,99 @@
+"""Rule / Design / Verdict schema, the laws of genome writing as data.
+
+A *rule is data, not code* (Principle 1): every constraint is a versioned record with an id, a kind
+(`hard_reject` | `soft_penalty` | `scope_flag`), the mechanism it encodes, a controlling parameter, a
+provenance/citation, a test reference, and the name of the registered *evaluator* that executes it. Code
+executes rules; it does not contain them. The evaluators (``pen_stack/rules/evaluators.py``) wrap the
+EXISTING validated functions (target_site, fold_qc, delivery, multiplex), so relocation changes nothing about
+the decisions, only makes them enumerable, queryable, and citation-backed (proven by the parity test).
+
+Legality and confidence are different axes (Principle 2): ``legal`` = every applicable hard rule passes;
+confidence is the calibrated trust attached separately by the verifier. Never collapse.
+"""
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+RuleKind = Literal["hard_reject", "soft_penalty", "scope_flag"]
+RuleStatus = Literal["pass", "violate", "flag", "scope", "not_applicable"]
+RuleCategory = Literal["reachability", "fold", "payload", "multiplex", "delivery", "compliance"]
+
+
+class Rule(BaseModel):
+    """A single law of genome writing, expressed as data. Frozen: the pinned, citation-backed rules are
+    immutable once loaded, so a law cannot be silently edited at runtime."""
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    kind: RuleKind
+    category: RuleCategory
+    mechanism: str # one-line statement of what physical fact it encodes
+    evaluator: str # registered evaluator fn name (rules/evaluators.py)
+    param: dict[str, Any] = Field(default_factory=dict)
+    provenance: dict[str, Any] = Field(default_factory=dict) # {doi: [...], note: ...}
+    test_ref: str | None = None
+    scope: str | None = None # limit (e.g. "screen, not activity guarantee")
+
+
+class Ruleset(BaseModel):
+    version: str
+    rules: list[Rule]
+
+    def by_category(self, category: str) -> list[Rule]:
+        return [r for r in self.rules if r.category == category]
+
+    def get(self, rule_id: str) -> Rule | None:
+        return next((r for r in self.rules if r.id == rule_id), None)
+
+
+class Design(BaseModel):
+    """A proposed genomic write submitted for verification. Permissive: evaluators that lack their inputs
+    return ``not_applicable`` rather than failing, so a partial design is still checkable.
+
+    Biosecurity screening. The safety gate reads hazard content ONLY from these declared fields:
+    ``cargo_function``, ``function_annotation``, ``goal_function``, ``source_taxon``, ``organism``,
+    ``host_taxon``, ``cargo_seq``, ``cargo_sequence`` (text) and ``function_tags``, ``pfam_domains``,
+    ``annotations`` (lists). Of these, only ``cargo_seq`` is a formal field here; the rest are passed as extra
+    keys (``model_config`` allows extra) and are screened all the same. Content placed in ``edit_intent`` or
+    any other free-text/framing field is deliberately NOT screened, framing is stripped before screening so a
+    hazardous design cannot be re-labelled "defensive" to pass. Consequently a verdict with
+    ``declared_signal=False`` means "no screenable content was declared, so nothing was screened", which is NOT
+    the same as "screened and found safe". Put hazard-relevant content in the fields above."""
+    write_type: str = "insertion"
+    gene: str | None = None
+    chrom: str | None = None
+    site_seq: str | None = None # sequence window at the target site (reachability)
+    writer_family: str | None = None
+    writer_output_form: Literal["DNA", "mRNA", "RNP"] | None = None
+    installed_att: bool = False # a pre-installed landing pad declared
+    cargo_bp: int | None = None
+    cargo_seq: str | None = None
+    delivery_vehicle: str | None = None
+    cell_type: str | None = None
+    edit_intent: str | None = None
+    no_integration: bool = False # goal forbids genomic integration
+    target_guide: str | None = None # bridge-RNA target-binding loop (fold)
+    donor_guide: str | None = None # bridge-RNA donor-binding loop (fold)
+    edits: list[dict] = Field(default_factory=list) # multi-edit plan (multiplex)
+
+    model_config = {"extra": "allow"} # forward-compatible with new dimensions
+
+
+class RuleResult(BaseModel):
+    """Frozen: a rule's outcome cannot be edited after evaluation, so `status`/`kind` (and therefore
+    `is_blocking`) cannot be flipped to turn a violation into a pass downstream."""
+    model_config = ConfigDict(frozen=True)
+
+    rule_id: str
+    kind: RuleKind
+    category: RuleCategory
+    status: RuleStatus
+    reason: str
+    citation: list[str] = Field(default_factory=list)
+    value: Any = None # optional numeric (penalty/score), provenance-tagged
+
+    @property
+    def is_blocking(self) -> bool:
+        return self.kind == "hard_reject" and self.status == "violate"

pen_stack/rules/solver.py

@@ -0,0 +1,43 @@
+"""The rule solver, evaluate a design against the rule base.
+
+``evaluate(design, ruleset) -> [RuleResult]`` runs each rule's registered evaluator, deterministically and
+ordered, returning a per-rule verdict with reason + citation. ``legal = every APPLICABLE hard_reject rule
+passes``, a not-applicable hard rule (its inputs absent) never blocks. Legality and confidence are kept
+separate: this module decides *legality* only; the verifier attaches calibrated confidence on top.
+"""
+from __future__ import annotations
+
+from pen_stack.rules.evaluators import get_evaluator
+from pen_stack.rules.loader import load_ruleset
+from pen_stack.rules.schema import Design, RuleResult, Ruleset
+
+
+def evaluate(design: Design, ruleset: Ruleset | None = None) -> list[RuleResult]:
+    rs = ruleset or load_ruleset()
+    results: list[RuleResult] = []
+    for rule in rs.rules:
+        fn = get_evaluator(rule.evaluator)
+        results.append(fn(design, rule))
+    return results
+
+
+def is_legal(results: list[RuleResult]) -> bool:
+    """Legal = no applicable hard_reject rule is violated."""
+    return not any(r.is_blocking for r in results)
+
+
+def legality_report(design: Design, ruleset: Ruleset | None = None) -> dict:
+    """Structured legality summary: legal bool + violations (named, with reason+citation) + flags + scope."""
+    results = evaluate(design, ruleset)
+    violations = [r for r in results if r.is_blocking]
+    flags = [r for r in results if r.kind == "soft_penalty" and r.status == "flag"]
+    scope = [r for r in results if r.kind == "scope_flag" and r.status == "scope"]
+    return {
+        "legal": is_legal(results),
+        "n_rules_evaluated": len(results),
+        "n_applicable": sum(1 for r in results if r.status != "not_applicable"),
+        "violations": [{"rule_id": r.rule_id, "reason": r.reason, "citation": r.citation} for r in violations],
+        "soft_flags": [{"rule_id": r.rule_id, "reason": r.reason, "value": r.value} for r in flags],
+        "scope_flags": [{"rule_id": r.rule_id, "reason": r.reason} for r in scope],
+        "rule_results": [r.model_dump() for r in results],
+    }

pen_stack/rules/spec.py

@@ -0,0 +1,78 @@
+"""Published, machine-readable rule spec.
+
+Exports the genome-writing rule base (``configs/rules/*.yaml``) as a single citable, machine-readable document:
+every rule with its id, kind, category, mechanism, the named evaluator that executes it, its parameters, its
+provenance (DOI or note), a test reference, and its scope limit. The spec is a faithful export of the live
+ruleset, not a second copy of the logic: ``spec_parity`` proves the exported records round-trip to the exact
+``Ruleset`` the solver loads (0 mismatches), every rule names a registered evaluator (so the spec is
+executable), and every rule carries a DOI or an explicit note. This is what makes the rules externally
+readable and citable without changing any decision.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pen_stack.rules.evaluators import registered_evaluators
+from pen_stack.rules.loader import RULES_VERSION, load_ruleset
+from pen_stack.rules.schema import Rule
+
+_FIELDS = ("id", "kind", "category", "mechanism", "evaluator", "param", "provenance", "test_ref", "scope")
+
+
+def export_spec() -> dict[str, Any]:
+    """Return the machine-readable rule spec: a version, the category list, and one record per rule with its
+    full provenance, the executing evaluator, and whether it carries a citation."""
+    rs = load_ruleset()
+    registered = registered_evaluators()
+    rules: list[dict[str, Any]] = []
+    for r in rs.rules:
+        prov = r.provenance or {}
+        doi = list(prov.get("doi", []) or [])
+        rules.append({
+            "id": r.id, "kind": r.kind, "category": r.category, "mechanism": r.mechanism,
+            "evaluator": r.evaluator, "param": r.param, "provenance": prov,
+            "citation": doi, "note": prov.get("note"), "test_ref": r.test_ref, "scope": r.scope,
+            "evaluator_registered": r.evaluator in registered,
+            "has_citation": bool(doi or prov.get("note")),
+        })
+    return {
+        "spec": "PEN-STACK genome-writing rule base",
+        "version": rs.version,
+        "n_rules": len(rules),
+        "categories": sorted({r["category"] for r in rules}),
+        "kinds": sorted({r["kind"] for r in rules}),
+        "note": "A rule is data, not code: each record names the evaluator that executes it against a Design. "
+                "Relocating the rules into this spec changes no decision (proven by the parity tests).",
+        "rules": rules,
+    }
+
+
+def spec_parity() -> dict[str, Any]:
+    """The exported spec faithfully reproduces the live ruleset. Checks (a) every exported record
+    round-trips to the identical ``Rule`` the solver loaded (0 mismatches), (b) every rule names a registered
+    evaluator, and (c) every rule carries a DOI or a note."""
+    spec = export_spec()
+    live = load_ruleset().rules
+    reload = [Rule(**{k: rec[k] for k in _FIELDS}) for rec in spec["rules"]]
+    mismatches = sorted({a.id for a, b in zip(live, reload, strict=True) if a != b}
+                        | ({r.id for r in live} ^ {r.id for r in reload}))
+    return {
+        "n_rules": spec["n_rules"],
+        "round_trip_mismatches": mismatches,
+        "parity_0_mismatch": len(mismatches) == 0,
+        "all_evaluators_registered": all(r["evaluator_registered"] for r in spec["rules"]),
+        "uncited_rules": [r["id"] for r in spec["rules"] if not r["has_citation"]],
+        "all_rules_cited": all(r["has_citation"] for r in spec["rules"]),
+        "rules_version": RULES_VERSION,
+    }
+
+
+def write_spec(path: str = "benchmarks/verify/rule_spec.json") -> str:
+    """Write the machine-readable spec to ``path`` (committed artifact). Returns the path."""
+    import os
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(export_spec(), fh, indent=2)
+        fh.write("\n")
+    return path

pen_stack/safety/__init__.py

@@ -0,0 +1,21 @@
+"""pen_stack.safety, the Guardian.
+
+A defensive biosecurity / dual-use screening gate that every design submitted to `verify()` passes before it
+is evaluated, scored, generated, or exported. It answers a question orthogonal to the immunology subsystem:
+not "will the patient react?" but "is this design itself hazardous / dual-use?". A design that
+matches a select-agent, pandemic-pathogen, or controlled-toxin signature is refused or escalated, by
+construction; legitimate therapeutic designs pass untouched. It is a safeguard, not a guarantee, and not a
+substitute for institutional biosafety review.
+"""
+from __future__ import annotations
+
+from pen_stack.safety.audit import audit_log, verify_chain
+from pen_stack.safety.gate import safety_gate
+from pen_stack.safety.policy import SafetyVerdict, decide
+from pen_stack.safety.registry import HazardRegistry
+from pen_stack.safety.screen import ScreenHit, screen_design
+
+__all__ = [
+    "safety_gate", "SafetyVerdict", "screen_design", "ScreenHit", "decide",
+    "HazardRegistry", "audit_log", "verify_chain",
+]