seqforge 2026.7.1__py3-none-any.whl

seqforge/kb/loader.py

@@ -0,0 +1,152 @@
+"""Discover and load KB ``spec.yaml`` files, validating each against the :class:`Spec` schema."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from .schema import Spec
+
+SPECS_DIR = Path(__file__).parent / "specs"
+
+
+def list_spec_ids() -> list[str]:
+    """Return the ids of every technology directory that ships a ``spec.yaml``."""
+    if not SPECS_DIR.is_dir():
+        return []
+    return sorted(p.name for p in SPECS_DIR.iterdir() if (p / "spec.yaml").is_file())
+
+
+def load_spec(tech_id: str) -> Spec:
+    """Load and validate one technology's ``spec.yaml``."""
+    path = SPECS_DIR / tech_id / "spec.yaml"
+    if not path.is_file():
+        raise FileNotFoundError(f"no KB spec for {tech_id!r} at {path}")
+    data = yaml.safe_load(path.read_text())
+    return Spec.model_validate(data)
+
+
+def load_all_specs() -> dict[str, Spec]:
+    """Load and validate every KB spec (the deterministic core of ``kb lint``)."""
+    return {tech_id: load_spec(tech_id) for tech_id in list_spec_ids()}
+
+
+def runnable_spec_ids() -> list[str]:
+    """Ids of specs that compile to a recipe — leaves and runnable families, not abstract nodes.
+
+    An abstract family node declares no ``backend``: it classifies during descent but is never scored,
+    composed, or params-gated. Tests and tools over "every chemistry" collect from here (derived from
+    the KB, not hand-maintained) so a family node never masquerades as a runnable one.
+    """
+    return [tech_id for tech_id in list_spec_ids() if load_spec(tech_id).backend is not None]
+
+
+@dataclass(frozen=True)
+class KbTree:
+    """The KB as a parent/child forest.
+
+    A **family** node narrows to its children; a **leaf** is a concrete, runnable chemistry. Siblings
+    (same parent) are confusable-by-construction, decided by the parent's ``children_decided_by`` — so
+    the resolver reads sibling relationships off the tree instead of a hand-declared ``confusable_with``
+    clique. ``children`` is ``node id -> sorted child ids``.
+    """
+
+    specs: dict[str, Spec]
+    children: dict[str, list[str]]
+
+    def children_of(self, tech_id: str) -> list[str]:
+        return list(self.children.get(tech_id, []))
+
+    def is_family(self, tech_id: str) -> bool:
+        return bool(self.children.get(tech_id))
+
+    def parent_of(self, tech_id: str) -> str | None:
+        return self.specs[tech_id].parent
+
+    def siblings_of(self, tech_id: str) -> list[str]:
+        """Other children of this node's parent (empty for a root)."""
+        parent = self.specs[tech_id].parent
+        if parent is None:
+            return []
+        return [c for c in self.children.get(parent, []) if c != tech_id]
+
+    def ancestors_of(self, tech_id: str) -> list[str]:
+        """The parent chain from this node up to (and including) its root, nearest first."""
+        out: list[str] = []
+        seen: set[str] = set()
+        cur = self.specs[tech_id].parent
+        while cur is not None and cur not in seen:
+            out.append(cur)
+            seen.add(cur)
+            cur = self.specs[cur].parent if cur in self.specs else None
+        return out
+
+    def runnable_descendants_of(self, tech_id: str) -> list[str]:
+        """Every leaf / runnable family at or below this node (what descent may terminate on)."""
+        out: list[str] = []
+        stack = [tech_id]
+        seen: set[str] = set()
+        while stack:
+            node = stack.pop()
+            if node in seen:
+                continue
+            seen.add(node)
+            if self.specs[node].backend is not None:
+                out.append(node)
+            stack.extend(self.children.get(node, []))
+        return sorted(out)
+
+    def leaves(self) -> list[str]:
+        """Ids with no children — the concrete, compilable chemistries."""
+        return sorted(i for i in self.specs if not self.children.get(i))
+
+
+def build_tree(specs: dict[str, Spec]) -> KbTree:
+    """Build and VALIDATE the KB forest; raise ``ValueError`` on a malformed tree.
+
+    Checks: every ``parent`` resolves; no cycles; ``node_kind`` agrees with having children; every
+    abstract family (a family with no backend) has at least one runnable descendant, so descent from it
+    can always terminate at something that compiles.
+    """
+    children: dict[str, list[str]] = {}
+    for tech_id, spec in specs.items():
+        parent = spec.parent
+        if parent is None:
+            continue
+        if parent == tech_id:
+            raise ValueError(f"{tech_id!r}: a node cannot be its own parent")
+        if parent not in specs:
+            raise ValueError(f"{tech_id!r}: parent {parent!r} is not a known spec")
+        children.setdefault(parent, []).append(tech_id)
+    for parent in children:
+        children[parent] = sorted(children[parent])
+
+    for tech_id in specs:  # no parent cycles: every chain must terminate at a root
+        seen: set[str] = set()
+        cur: str | None = tech_id
+        while cur is not None:
+            if cur in seen:
+                raise ValueError(f"parent cycle through {tech_id!r}")
+            seen.add(cur)
+            cur = specs[cur].parent
+
+    tree = KbTree(specs=specs, children=children)
+    for tech_id, spec in specs.items():
+        has_children = bool(children.get(tech_id))
+        if has_children and spec.node_kind != "family":
+            raise ValueError(f"{tech_id!r} has children but is not declared node_kind: family")
+        if spec.node_kind == "family" and not has_children:
+            raise ValueError(f"{tech_id!r} is declared a family but has no children")
+        if spec.node_kind == "family" and spec.backend is None:
+            if not tree.runnable_descendants_of(tech_id):
+                raise ValueError(
+                    f"abstract family {tech_id!r} has no runnable descendant to compile"
+                )
+    return tree
+
+
+def load_tree() -> KbTree:
+    """Load every spec and build the validated KB tree."""
+    return build_tree(load_all_specs())

seqforge/kb/roundtrip.py

@@ -0,0 +1,112 @@
+"""``kb roundtrip`` — the self-test: spec -> synth FASTQ -> probe -> recover; assert == declared.
+
+Generic over any spec: for every declared read it checks that the probe recovers the declared fixed
+length, that barcode windows recur (low distinct-ratio), and that UMI windows are ~unique (high
+distinct-ratio). Uses a temp directory; touches no real data.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from ..probe import probe_file
+from ..probe.signals import window_distinct_ratio
+from .anchor import resolve_windows
+from .generate import generate_reads, write_fastq_gz
+from .loader import load_spec
+from .schema import Read
+
+
+def _write_fastq_gz(path: Path, seqs: list[str]) -> None:
+    write_fastq_gz(path, seqs)
+
+
+def _anchored_distinct_ratio(seqs: list[str], read: Read, element_name: str) -> float | None:
+    """``distinct/total`` of a FLOATING element, sliced at each read's phase-detected frame.
+
+    A fixed element has a constant window :func:`window_distinct_ratio` can slice; an anchored one does
+    not (the diversity insert staggers it per read), so recover its frame first. This is what makes the
+    round-trip actually verify anchoring: if the resolver could not recover the staggered cell-label
+    blocks, their slices would not recur and ``barcode_recurs`` would go red.
+    """
+    slices = [
+        s[a:b]
+        for s in seqs
+        if (w := resolve_windows(s, read)) is not None and element_name in w
+        for a, b in (w[element_name],)
+        if s[a:b]
+    ]
+    if not slices:
+        return None
+    return len(set(slices)) / len(slices)
+
+
+def run_roundtrip(tech_id: str, *, n: int = 2000, seed: int = 0) -> dict[str, Any]:
+    """Round-trip one technology and return ``{tech, passed, checks:[...]}``."""
+    spec = load_spec(tech_id)
+    reads = generate_reads(spec, n=n, seed=seed)
+    checks: list[dict[str, Any]] = []
+
+    with tempfile.TemporaryDirectory() as td:
+        for read in spec.reads:
+            seqs = reads[read.id]
+            path = Path(td) / f"{read.id}.fastq.gz"
+            _write_fastq_gz(path, seqs)
+            obs = probe_file(path)
+
+            if read.min_len is not None and read.min_len == read.max_len:
+                checks.append(
+                    {
+                        "read": read.id,
+                        "check": "length",
+                        "ok": obs.read_length.mode == read.min_len,
+                        "declared": read.min_len,
+                        "recovered": obs.read_length.mode,
+                    }
+                )
+            # an open-ended cDNA/gDNA read must probe back as variable-length (non-vacuous for the
+            # no-barcode bulk branch, whose only structural claim is "two variable cDNA reads").
+            has_open_cdna = any(
+                el.type in ("cdna", "gdna") and el.end is None for el in read.elements
+            )
+            if has_open_cdna and read.min_len != read.max_len:
+                checks.append(
+                    {
+                        "read": read.id,
+                        "check": "cdna_variable",
+                        "ok": obs.read_length.n_distinct > 1,
+                        "n_distinct": obs.read_length.n_distinct,
+                    }
+                )
+            for el in read.elements:
+                if el.start is not None and el.end is not None:
+                    ratio = window_distinct_ratio(seqs, el.start, el.end)
+                elif el.anchor is not None:
+                    # a floating element: recover its per-read frame rather than skipping it (pre-#43
+                    # every anchored element was skipped, so the round-trip proved nothing about them).
+                    ratio = _anchored_distinct_ratio(seqs, read, el.name)
+                else:
+                    continue  # a variable-length insert with no anchor (the VB itself): no window to
+                    # check — its recovery is proven by the downstream anchored elements resolving.
+                if el.type == "barcode" and el.onlist:
+                    checks.append(
+                        {
+                            "read": read.id,
+                            "check": f"barcode_recurs:{el.name}",
+                            "ok": ratio is not None and ratio < 0.5,
+                            "ratio": ratio,
+                        }
+                    )
+                elif el.type == "umi":
+                    checks.append(
+                        {
+                            "read": read.id,
+                            "check": f"umi_unique:{el.name}",
+                            "ok": ratio is not None and ratio > 0.7,
+                            "ratio": ratio,
+                        }
+                    )
+
+    return {"tech": tech_id, "passed": all(c["ok"] for c in checks), "checks": checks}

seqforge/kb/schema.py

@@ -0,0 +1,422 @@
+"""The KB ``spec.yaml`` schema — machine-checkable, closed-vocabulary, self-validating.
+
+One directory per technology: ``kb/specs/<tech>/{spec.yaml, README.md}``. ``spec.yaml`` declares the
+read layout (element coordinates), onlist references, a detection ``signature`` (requires / supports /
+excludes), a ``backend`` param template, and a ``confusable_with`` list. Every model forbids extra
+keys, so a typo fails validation exactly where the DSL is executed. The signature test vocabulary is
+*exactly* the scorer's evaluator set.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+ElementType = Literal[
+    "barcode", "umi", "cdna", "gdna", "linker", "poly_a", "poly_t", "fixed", "index", "diversity"
+]
+# ``diversity`` = a variable-length insert of random bases at a read's 5' end (BD Rhapsody Enhanced's
+# 0-3 bp diversity/phasing insert). It carries no barcode/UMI value — its ONLY effect is to STAGGER
+# every downstream element by its per-read length, which is why it is modelled as a first-class element
+# (``min_len``/``max_len``): the generator draws a per-read length for it and the anchored resolver
+# recovers the frame the stagger created (see ``kb/anchor.py``). It is not a linker/fixed (no literal
+# sequence) and not a counted feature, so ``compose`` skips it and it maps to a ``linker`` manifest role.
+Mechanism = Literal["none", "onlist", "metadata", "alignment", "user"]
+Decidable = Literal["reads", "onlist", "metadata", "alignment", "user"]
+Orientation = Literal["forward", "revcomp", "either"]
+SeqspecRegion = Literal[
+    "barcode",
+    "umi",
+    "cdna",
+    "gdna",
+    "index5",
+    "index7",
+    "linker",
+    "poly_A",
+    "poly_t",
+    "custom_primer",
+]
+
+_ONLIST_TOKEN = re.compile(r"^\{onlist:([A-Za-z0-9._-]+)\}$")
+_ANY_BRACE = re.compile(r"\{[^}]*\}")
+
+
+class _Forbid(BaseModel):
+    """Base that forbids unknown keys, so the closed vocabulary is enforced where it is executed."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class Anchor(_Forbid):
+    """Locate a variable-length / floating element (e.g. inDrop's post-W1 barcode)."""
+
+    relative_to: Literal["read_start", "read_end", "element"] = "read_start"
+    ref_element: str | None = None
+    ref_side: Literal["start", "end"] = "end"
+    offset: int = 0
+    motif: str | None = None
+    max_mismatch: int = 0
+
+
+class Element(_Forbid):
+    """One element of a read. 0-based half-open ``[start, end)``; ``end=None`` => open-ended (cDNA)."""
+
+    type: ElementType
+    name: str
+    start: int | None = None
+    end: int | None = None
+    min_len: int | None = None
+    max_len: int | None = None
+    anchor: Anchor | None = None
+    sequence: str | None = None
+    onlist: str | None = None
+    seqspec_region_type: SeqspecRegion
+
+    @model_validator(mode="after")
+    def _addressable(self) -> Element:
+        fixed = self.start is not None and self.end is not None
+        opened = self.start is not None and self.end is None
+        varlen = self.min_len is not None or self.max_len is not None
+        anchored = self.anchor is not None
+        if self.type in ("linker", "fixed") and self.sequence is None:
+            raise ValueError(f"element {self.name!r}: linker/fixed needs a literal `sequence`")
+        if self.type in ("cdna", "gdna"):
+            return self  # open-ended is legal
+        if not (fixed or opened or anchored or varlen):
+            raise ValueError(f"element {self.name!r}: give [start,end), an anchor, or min/max_len")
+        return self
+
+
+class Read(_Forbid):
+    """A read (== one FASTQ). ``id`` is a ROLE label (R1/R2/bc/cdna), never a filename claim."""
+
+    id: str
+    seqspec_read_id: str
+    file_hint: str | None = None
+    strand: Literal["pos", "neg"] = "pos"
+    min_len: int | None = None
+    max_len: int | None = None
+    elements: list[Element]
+
+
+class OnlistRef(_Forbid):
+    """Alias -> pooch-registry name. URL/sha256/length/orientation live in the registry, never here."""
+
+    registry: str
+    role: Literal["cell_barcode", "sample_index", "feature", "atac_barcode"]
+    expected_orientation: Orientation = "forward"
+
+
+# ---- signature tests: a CLOSED set == the scorer's evaluators ----
+class _Seg(_Forbid):
+    """A test addressed to a segment by element name XOR (start, end)."""
+
+    read: str
+    element: str | None = None
+    start: int | None = None
+    end: int | None = None
+
+    @model_validator(mode="after")
+    def _one_address(self) -> _Seg:
+        by_name = self.element is not None
+        by_coord = self.start is not None and self.end is not None
+        if by_name == by_coord:
+            raise ValueError("address a segment by element name XOR (start, end)")
+        return self
+
+
+class ReadCount(_Forbid):
+    test: Literal["read_count"]
+    roles: int  # biological + barcode ROLE count, never raw file count
+
+
+class SegmentLength(_Forbid):
+    test: Literal["segment_length"]
+    read: str
+    length: int
+    tolerance: int = 0
+    #: Over-length escape. A read whose mode is ``>= over_length_min`` PASSES regardless of ``length``
+    #: — an insert-bearing / over-sequenced barcode read (e.g. a 10x R1 sequenced to 150 bp: CB+UMI in
+    #: bp0-28, the rest junk). Keep it strictly above ``length`` so a canonical read is never
+    #: "over-length" and the exact-length gate still separates near-neighbours (v2's 26 vs v3's 28).
+    over_length_min: int | None = None
+
+
+class HasSegment(_Seg):
+    test: Literal["has_segment"]
+    kind: Literal["constant", "random", "polyT", "polyA"]
+
+
+class DistinctRatio(_Seg):
+    test: Literal["distinct_ratio"]
+    expect: Literal["low", "high"]  # SUPPORTS-only; depth-dependent, never a gate
+
+
+class OnlistHitRate(_Seg):
+    test: Literal["onlist_hit_rate"]
+    onlist: str
+    orientation: Orientation = "either"
+    min: float
+
+
+class MotifPresent(_Forbid):
+    test: Literal["motif_present"]
+    read: str
+    motif: str
+    where: Literal["read_start", "read_end", "anywhere", "window"] = "anywhere"
+    search_start: int | None = None
+    search_end: int | None = None
+    max_mismatch: int = 1
+    min_rate: float = 0.5
+
+
+class BaseComposition(_Seg):
+    test: Literal["base_composition"]
+    base: Literal["A", "C", "G", "T", "N"]
+    min_fraction: float
+
+
+class HeaderIndex(_Forbid):
+    test: Literal["header_index"]
+    present: bool
+
+
+Test = Annotated[
+    ReadCount
+    | SegmentLength
+    | HasSegment
+    | DistinctRatio
+    | OnlistHitRate
+    | MotifPresent
+    | BaseComposition
+    | HeaderIndex,
+    Field(discriminator="test"),
+]
+
+
+class Support(_Forbid):
+    when: Test
+    weight: float = 1.0
+
+
+class Signature(_Forbid):
+    requires: list[Test]  # hard AND-gates (no distinct_ratio here — it's depth-dependent)
+    supports: list[Support]  # additive evidence (onlist + distinct_ratio live here)
+    excludes: list[Test]  # anti-gates: any pass => disqualify
+
+
+KB_PARSE_KEYS: frozenset[str] = frozenset(
+    {
+        "soloType",
+        "soloCBstart",
+        "soloCBlen",
+        "soloUMIstart",
+        "soloUMIlen",
+        "soloCBwhitelist",
+        "soloCBposition",
+        "soloUMIposition",
+        "soloStrand",
+        "soloAdapterSequence",
+        "soloBarcodeReadLength",
+    }
+)
+"""Every key the KB may declare. Each says how to **parse** reads, and each is decided by bytes.
+
+The line is parse vs. count. What to COUNT — ``soloFeatures``, ``quantMode`` — is *intent*: it belongs
+to the processing manifest, where a user may instruct it and a gate may check it. ``soloFeatures``
+sat here because this is where the aligner's flags live, and it cost a measured **40.7 % of a nuclear
+library**: 10x 3' v3.1 chemistry is byte-identical for cells and nuclei, so counting was never a
+chemistry property at all.
+
+The disjointness of this set from the instructable surface is what makes "a user instruction
+contradicts the observed bytes" **structurally inexpressible** rather than merely deprioritized — the
+user has no vocabulary in which to say it. That is the strongest form of that guarantee available, and it is why
+moving a key across this line has to be an explicit, gated act.
+"""
+
+
+class Backend(_Forbid):
+    """A data template mapping to a workflow module. Only ``{onlist:<alias>}`` interpolation is legal."""
+
+    module: str
+    params: dict[str, str | int | float | list[str]]
+
+    @model_validator(mode="after")
+    def _only_parse_keys(self) -> Backend:
+        """A count/reference/runtime knob may not be declared here.
+
+        ``params`` is a ``dict``, so ``extra="forbid"`` cannot reach inside it — hence an explicit
+        validator. It fires in ``load_spec``, in ``kb lint``, and in every test that loads a spec,
+        which is what makes the parse/count line a property of the DSL rather than a convention.
+        """
+        stray = sorted(set(self.params) - KB_PARSE_KEYS)
+        if stray:
+            raise ValueError(
+                f"backend.params declares non-parse key(s) {stray}: backend.params says how to "
+                f"PARSE reads (byte-decided); what to COUNT belongs in the processing manifest, "
+                f"where a user may instruct it. Known parse keys: {sorted(KB_PARSE_KEYS)}"
+            )
+        return self
+
+    def check_tokens(self, onlist_aliases: set[str]) -> None:
+        """Reject any interpolation token that is not a declared ``{onlist:<alias>}``."""
+        for value in self._strings():
+            for match in _ANY_BRACE.finditer(value):
+                token = _ONLIST_TOKEN.match(match.group(0))
+                if token is None:
+                    raise ValueError(
+                        f"illegal template expression {match.group(0)!r} "
+                        "(only {onlist:<alias>} is allowed)"
+                    )
+                if token.group(1) not in onlist_aliases:
+                    raise ValueError(f"unknown onlist alias {token.group(1)!r}")
+
+    def _strings(self) -> list[str]:
+        out: list[str] = []
+        for value in self.params.values():
+            if isinstance(value, str):
+                out.append(value)
+            elif isinstance(value, list):
+                out.extend(v for v in value if isinstance(v, str))
+        return out
+
+
+class Confusable(_Forbid):
+    id: str
+    relationship: Literal["processing_equivalent", "processing_divergent"]
+    distinguishable_by: list[Mechanism]
+    note: str = ""
+
+    @model_validator(mode="after")
+    def _shape(self) -> Confusable:
+        if self.relationship == "processing_divergent" and self.distinguishable_by == ["none"]:
+            raise ValueError("a processing_divergent pair cannot be distinguishable_by [none]")
+        return self
+
+
+class Identity(_Forbid):
+    id: str
+    version: str
+    name: str
+    aliases: list[str] = Field(default_factory=list)
+    assay_ontology: list[str] = Field(default_factory=list)
+    modality: Literal["rna", "atac", "multi"] = "rna"
+
+
+class Spec(_Forbid):
+    """A complete, self-validating technology specification (one node in the KB tree)."""
+
+    schema_version: int
+    identity: Identity
+    reads: list[Read]
+    onlists: dict[str, OnlistRef]
+    signature: Signature
+    #: The runnable STARsolo/STAR template. ``None`` on an ABSTRACT family node — a classifier that
+    #: narrows to its children but has no single recipe (``10x-3p-gex`` parses v2 and v3 differently).
+    #: A leaf, and a runnable family like ``bulk``, always declare one.
+    backend: Backend | None = None
+    #: The family id this node descends from; ``None`` at a root. Siblings (same parent) are
+    #: confusable-by-construction, decided by the parent's ``children_decided_by`` — which is why a
+    #: sibling clique of ``processing_divergent`` ``confusable_with`` edges collapses to one ``parent``.
+    parent: str | None = None
+    node_kind: Literal["family", "leaf"] = "leaf"
+    #: How a FAMILY node's children are told apart (``onlist`` / ``metadata`` / ``alignment``). Empty on
+    #: a leaf. Replaces the per-sibling ``distinguishable_by`` for the divergent-tie question.
+    children_decided_by: list[Mechanism] = Field(default_factory=list)
+    confusable_with: list[Confusable] = Field(default_factory=list)
+
+    def require_backend(self) -> Backend:
+        """The runnable backend, or a clear error if this is an abstract family node.
+
+        Only leaves and runnable families compile; descent always resolves to one of those, so every
+        compose/params/policy site is entitled to a backend. This turns the ``Backend | None`` into a
+        checked ``Backend`` at exactly those call sites.
+        """
+        if self.backend is None:
+            raise ValueError(
+                f"{self.identity.id!r} is an abstract family node with no runnable backend; "
+                "only leaves and runnable families compile"
+            )
+        return self.backend
+
+    @property
+    def decidable_by(self) -> list[Decidable]:
+        """How this technology can be separated from the ones it is confusable with. **Derived.**
+
+        This was a hand-typed field on every spec, and two of them carried the comment "CI-computed
+        union over the divergent confusables". No CI computed it. Nothing read it either — `escalate`
+        builds a Question's ``decidable_by`` from ``confusable_with[].distinguishable_by``, inline,
+        which is precisely the union the comment described. So the field was a claim about behaviour
+        that caused no behaviour: a comment with a list's syntax, free to drift from the thing it
+        claimed to summarize, with nothing to notice.
+
+        That is the exact shape of `RegistryEntry.fetchable` before it was derived, and of
+        `required_config` before that. Deriving it is the only fix that stays fixed.
+
+        ``processing_equivalent`` twins are excluded on purpose: §12 says two entries with identical
+        ``backend.params`` are declared equivalent and recorded together, so there is nothing to
+        decide between them and no mechanism that could.
+        """
+        out: set[Decidable] = set()
+        for c in self.confusable_with:
+            if c.relationship == "processing_divergent":
+                out.update(m for m in c.distinguishable_by if m != "none")
+        return sorted(out)  # type: ignore[arg-type]
+
+    @model_validator(mode="after")
+    def _node_shape(self) -> Spec:
+        """A leaf must be runnable; ``children_decided_by`` is a family-only knob."""
+        if self.node_kind == "leaf":
+            if self.backend is None:
+                raise ValueError(
+                    f"{self.identity.id!r}: a leaf node must declare a runnable backend"
+                )
+            if self.children_decided_by:
+                raise ValueError(
+                    f"{self.identity.id!r}: children_decided_by is only meaningful on a family node"
+                )
+        return self
+
+    @model_validator(mode="after")
+    def _cross_refs(self) -> Spec:
+        aliases = set(self.onlists)
+        read_ids = {r.id for r in self.reads}
+        elements_by_read = {r.id: {e.name for e in r.elements} for r in self.reads}
+
+        # every onlist alias referenced by an element must be declared
+        for read in self.reads:
+            for el in read.elements:
+                if el.onlist and el.onlist not in aliases:
+                    raise ValueError(f"element {el.name!r}: unknown onlist {el.onlist!r}")
+                if el.anchor and el.anchor.ref_element:
+                    if el.anchor.ref_element not in elements_by_read[read.id]:
+                        raise ValueError(
+                            f"element {el.name!r}: anchor ref_element "
+                            f"{el.anchor.ref_element!r} not in read {read.id!r}"
+                        )
+
+        # every signature test must reference a declared read (and element/onlist)
+        tests: list[Test] = [
+            *self.signature.requires,
+            *self.signature.excludes,
+            *(s.when for s in self.signature.supports),
+        ]
+        for t in tests:
+            read = getattr(t, "read", None)
+            if read is not None and read not in read_ids:
+                raise ValueError(f"signature test references unknown read {read!r}")
+            element = getattr(t, "element", None)
+            if element is not None and read is not None:
+                if element not in elements_by_read.get(read, set()):
+                    raise ValueError(
+                        f"signature test references unknown element {element!r} in read {read!r}"
+                    )
+            onlist = getattr(t, "onlist", None)
+            if onlist is not None and onlist not in aliases:
+                raise ValueError(f"signature test references unknown onlist {onlist!r}")
+
+        if self.backend is not None:
+            self.backend.check_tokens(aliases)
+        return self