seqforge 2026.7.1__py3-none-any.whl

seqforge/io/taxonomy.py

@@ -0,0 +1,194 @@
+"""Organism name -> NCBI taxid, with a round-trip verifier. **No model is involved, deliberately.**
+
+This is the one gap in "the organism must come from the paper" that survived every audit, and the
+shape of it is worth stating because it looks like a job for a language model and is not:
+
+    harvest extracts   experiment.organism = "Caenorhabditis elegans"   (a str, with a verified span)
+    fill_manifest wants experiment.organism_taxid = 6239                (an int)
+    and nothing joined them, so the taxid had to be retyped by hand.
+
+The model already does its job here — it *finds* the organism in the prose, span-verified. What was
+missing is a converter, and a converter is a lookup table. A model asked for the taxid directly would
+be asked to *recall* one, and a model confusing 6239 (C. elegans) with 6238 (C. briggsae) produces a
+number that is well-formed, plausible, and wrong in a way nothing downstream can see: a worm dataset
+aligned to a different worm maps at a rate that looks merely mediocre. That is the failure class this
+project exists to prevent, so: **the LLM finds, code resolves.**
+
+**The verifier is a round trip, and it is what makes this safe.** Resolve the name to a taxid, then
+fetch that taxid back and confirm it answers to the name we started from (scientific name, synonym, or
+common name). A wrong lookup does not survive it. Note this would make even a *model-proposed* taxid
+safe — the criterion is "cheaply verifiable", not "hard to hardcode" — but a table is simpler and free,
+so there is no reason to reach for one.
+
+Two things this module refuses to do:
+
+- **Guess a rank.** `Saccharomyces cerevisiae` resolves to 4932 (the species). The sacCer3 fixtures use
+  559292 (strain S288C). Both are correct answers to different questions, and NCBI's search returns the
+  species — so when a caller wants the strain, they say so. Silently promoting or demoting a rank is
+  the kind of helpfulness that ends up in a corpus.
+- **Reach the network without saying so.** The seed table below covers what we ship fixtures for. A
+  name outside it needs one E-utilities call, and offline that is a refusal with an actionable remedy,
+  never a guess.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..workspace import cache_dir
+from .remote import _MAX_RETRIES, _RETRY_STATUS, retry_delay
+
+_EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+
+#: Names we resolve without a network call. **Every entry was verified against NCBI E-utilities on
+#: 2026-07-15 by the round trip this module implements** — none is remembered.
+#:
+#: This is a cache, not a curation: it exists so the common path is offline and instant, not to decide
+#: which organisms are worth supporting (that would be a policy hiding in a dict). Anything else does
+#: one lookup. Keys are lowercased.
+_SEED: dict[str, int] = {
+    "caenorhabditis elegans": 6239,
+    "c. elegans": 6239,
+    "homo sapiens": 9606,
+    "human": 9606,
+    "mus musculus": 10090,
+    "mouse": 10090,
+    "saccharomyces cerevisiae": 4932,
+    "saccharomyces cerevisiae s288c": 559292,
+    "danio rerio": 7955,
+    "drosophila melanogaster": 7227,
+}
+
+
+class TaxonomyUnavailable(RuntimeError):
+    """A name could not be resolved (unknown, offline, or the round trip failed)."""
+
+
+@dataclass(frozen=True)
+class Taxon:
+    """A resolved organism: the taxid, plus what NCBI says it is."""
+
+    taxid: int
+    scientific_name: str
+    rank: str = ""
+    names: tuple[str, ...] = ()
+
+    def answers_to(self, name: str) -> bool:
+        """Does this taxon go by ``name``? The round-trip check's actual question."""
+        wanted = _normalize(name)
+        return wanted in {_normalize(n) for n in (self.scientific_name, *self.names)}
+
+
+def _normalize(name: str) -> str:
+    """Casefold and collapse whitespace. Nothing cleverer: this is a key, not a parser."""
+    return re.sub(r"\s+", " ", name).strip().lower()
+
+
+def _with_api_key(url: str) -> str:
+    """Append ``api_key`` to a eutils URL when the environment sets ``NCBI_API_KEY`` (lifts the keyless
+    3 req/sec cap to 10). Only eutils URLs — the key is NCBI's and belongs on no other host (#9)."""
+    key = os.environ.get("NCBI_API_KEY")
+    if not key or not url.startswith(_EUTILS):
+        return url
+    sep = "&" if "?" in url else "?"
+    return f"{url}{sep}api_key={urllib.parse.quote(key)}"
+
+
+def _get(url: str, *, timeout: float) -> str:
+    # Mirror `remote._get`: a transient status (429 rate-limit, a 5xx blip) backs off and retries
+    # rather than aborting the lookup. taxonomy uses urllib, so a non-2xx arrives as an HTTPError.
+    full = _with_api_key(url)
+    attempt = 0
+    while True:  # exits only by return (2xx) or raise (terminal status / exhausted budget)
+        try:
+            with urllib.request.urlopen(full, timeout=timeout) as fh:  # noqa: S310 - pinned NCBI host
+                return str(fh.read().decode())
+        except urllib.error.HTTPError as exc:
+            if exc.code in _RETRY_STATUS and attempt < _MAX_RETRIES:
+                time.sleep(retry_delay(exc.headers.get("Retry-After"), attempt))
+                attempt += 1
+                continue
+            raise
+
+
+def fetch_taxon(taxid: int, *, timeout: float = 20.0) -> Taxon:
+    """What NCBI says taxid ``taxid`` is. The second half of the round trip."""
+    xml = _get(f"{_EUTILS}/efetch.fcgi?db=taxonomy&id={taxid}&retmode=xml", timeout=timeout)
+    sci = re.search(r"<ScientificName>(.*?)</ScientificName>", xml)
+    if not sci:
+        raise TaxonomyUnavailable(f"NCBI returned no scientific name for taxid {taxid}")
+    rank = re.search(r"<Rank>(.*?)</Rank>", xml)
+    names = tuple(
+        re.findall(r"<Synonym>(.*?)</Synonym>", xml)
+        + re.findall(r"<GenbankCommonName>(.*?)</GenbankCommonName>", xml)
+        + re.findall(r"<CommonName>(.*?)</CommonName>", xml)
+    )
+    return Taxon(
+        taxid=int(taxid),
+        scientific_name=sci.group(1),
+        rank=rank.group(1) if rank else "",
+        names=names,
+    )
+
+
+def resolve(name: str, *, offline: bool = False, timeout: float = 20.0, verify: bool = True) -> int:
+    """``"Caenorhabditis elegans"`` -> ``6239``. Raises rather than guessing.
+
+    ``verify`` runs the round trip: the taxid is fetched back and must answer to ``name``. It is on by
+    default and should stay on — a lookup that returns the wrong taxid is otherwise undetectable, and
+    the whole reason this is code instead of a model is that we can check it.
+    """
+    key = _normalize(name)
+    if key in _SEED:
+        return _SEED[key]
+    if offline:
+        raise TaxonomyUnavailable(
+            f"cannot resolve organism {name!r} offline. Pass the NCBI taxid directly "
+            f"(`--organism <taxid>`), or run with network access."
+        )
+    term = urllib.parse.quote(name)
+    try:
+        payload = json.loads(
+            _get(f"{_EUTILS}/esearch.fcgi?db=taxonomy&term={term}&retmode=json", timeout=timeout)
+        )
+        ids = payload["esearchresult"]["idlist"]
+    except Exception as exc:  # network, JSON, or shape - all mean "we do not know"
+        raise TaxonomyUnavailable(f"NCBI taxonomy lookup for {name!r} failed: {exc}") from exc
+    if not ids:
+        raise TaxonomyUnavailable(
+            f"NCBI taxonomy has no match for organism {name!r}. Check the spelling, or pass the "
+            f"taxid directly with `--organism <taxid>`."
+        )
+    if len(ids) > 1:
+        raise TaxonomyUnavailable(
+            f"organism {name!r} is ambiguous: NCBI returns taxids {ids}. Pass the one you mean with "
+            f"`--organism <taxid>` — picking for you is exactly the guess this refuses to make."
+        )
+    taxid = int(ids[0])
+    if verify:
+        taxon = fetch_taxon(taxid, timeout=timeout)
+        if not taxon.answers_to(name):
+            raise TaxonomyUnavailable(
+                f"round trip failed: {name!r} resolved to taxid {taxid}, but NCBI says that is "
+                f"{taxon.scientific_name!r} (rank {taxon.rank}). Refusing — a wrong organism aligns "
+                f"at a rate that merely looks mediocre, and nothing downstream would object."
+            )
+    return taxid
+
+
+def seed_names() -> dict[str, int]:
+    """The offline table, for tests and `io taxon list`."""
+    return dict(_SEED)
+
+
+#: Where a resolved lookup is cached under a workspace, so a second run is offline and instant.
+def cache_path(workspace: str | Path) -> Path:
+    return cache_dir(workspace) / "taxonomy.json"

seqforge/kb/__init__.py

@@ -0,0 +1,62 @@
+"""``kb`` — the executable, self-testing knowledge base.
+
+One directory per technology under ``specs/`` (``spec.yaml`` + ``README.md``). Each spec validates
+against :class:`~seqforge.kb.schema.Spec`, generates its own synthetic fixtures, and round-trips
+through the probe. ``KB_VERSION`` (CalVer) is folded into dataset-level cache keys.
+"""
+
+from __future__ import annotations
+
+from .generate import build_pools, generate_reads
+from .loader import (
+    KbTree,
+    build_tree,
+    list_spec_ids,
+    load_all_specs,
+    load_spec,
+    load_tree,
+    runnable_spec_ids,
+)
+from .roundtrip import run_roundtrip
+from .schema import Spec
+
+#: CalVer YYYY.M.PATCH; bump when spec semantics change. Folded into dataset candidate cache keys.
+#: 2026.7.3 — 10x 3' v2/v3/v3.1 accept an OVER-LENGTH barcode read (R1 max_len null +
+#: segment_length over_length_min 100) and add soloBarcodeReadLength:0; v2<->v3 and v2<->v3.1 declared
+#: processing_divergent (whitelist-decided) for the over-length case length can no longer separate.
+#: (over_length_min is 100, not 40, so a 60-94 bp cDNA/split-pool read is not mistaken for an
+#: over-sequenced barcode read -> the rung-0-2 separability guard stays green without over-declaring.)
+#: 2026.7.2 — bulk-rnaseq-pe <-> splitseq declared processing_divergent, distinguishable_by onlist.
+#: Found by the new rung-0-2 separability guard on its first run: the generic paired-end fallback
+#: accepts SPLiT-seq's cdna+bc pair on geometry alone and had declared nothing.
+#: 2026.7.1 — the parse/count line: soloFeatures / quantMode / outSAMtype left backend.params,
+#: which now declares ONLY byte-decided parse keys. Also adds the 10x-3p-gex-v3.1 benign twin.
+#: 2026.7.4 — added the bd-rhapsody-wta spec (BD Rhapsody WTA, original fixed-offset cell-label bead:
+#: CB_UMI_Complex, three 97 x 9 bp CLS whitelists SHIPPED, two fixed linkers). bulk-rnaseq-pe <->
+#: bd-rhapsody-wta declared processing_divergent, distinguishable_by onlist (same rung-0-2 collision
+#: SPLiT-seq has with the generic paired-end fallback).
+#: 2026.7.5 — the KB became a TREE: added the abstract family node 10x-3p-gex (node_kind: family, no
+#: backend, children_decided_by: [onlist]) that recognizes v2/v3/v3.1 and rejects bulk; the three 10x
+#: leaves gained parent: 10x-3p-gex and dropped their divergent-sibling confusable_with cliques (the
+#: shared parent now implies them); v3<->v3.1 processing_equivalent edges kept. Descent narrows to a
+#: length-feasible pool before scoring, so adding the Nth 10x chemistry is one parent link, not a clique.
+#: 2026.7.6 — first ANCHORED chemistry: the bd-rhapsody-wta-enhanced family + leaves -96 / -v2 for the
+#: BD Rhapsody Enhanced bead (variable 0-3 bp diversity insert). New `diversity` element type + per-
+#: element anchors; the family recognizes the GTGA/GACA frame by motif; leaves split on onlist (97 vs
+#: 384 CLS pools, disjoint). Ships bd-rhapsody-cls{1,2,3}-384; -96 reuses the original bead's lists.
+KB_VERSION = "2026.7.6"
+
+__all__ = [
+    "KB_VERSION",
+    "Spec",
+    "KbTree",
+    "load_spec",
+    "load_all_specs",
+    "load_tree",
+    "build_tree",
+    "list_spec_ids",
+    "runnable_spec_ids",
+    "generate_reads",
+    "build_pools",
+    "run_roundtrip",
+]

seqforge/kb/anchor.py

@@ -0,0 +1,169 @@
+"""Per-read window resolution for **anchored / variable-position** elements (design §2.1, §9/§10).
+
+Most chemistries put every element at a fixed ``[start, end)`` and the scorer slices a constant column.
+A few do not: BD Rhapsody's *Enhanced* bead prepends a **variable 0-3 bp diversity insert** to Read 1,
+so every cell-label block downstream **staggers** by a per-read amount and no single column holds a
+barcode. STARsolo handles this with an *adapter anchor* (find the ``GTGA…GACA`` linker frame, read the
+barcodes relative to it); this module is seqforge's byte-side twin of that idea.
+
+``resolve_windows(seq, read)`` locates each element's ``[start, end)`` **in one read** by
+**phase detection**: the only unknowns are the lengths of the variable-length elements (the insert),
+so enumerate their candidate lengths, walk the element chain for each, and keep the phase whose
+``linker``/``fixed`` elements Hamming-match their declared ``sequence`` (substitutions only, exactly
+the error model rhapsodist uses across its 0-3 bp offset scan). A read whose frame cannot be found
+(a cDNA read, a garbage read) returns ``None`` and simply does not contribute — never a wrong slice.
+
+This lives in ``kb`` (not ``resolve`` or ``probe``) on purpose: it is pure layout logic over a
+``kb.schema.Read`` and a string, and both ``kb.roundtrip`` (which cannot import ``resolve`` — that is a
+cycle) and ``resolve.window`` need it.
+"""
+
+from __future__ import annotations
+
+from itertools import product
+
+from .schema import Element, Read
+
+#: Substitutions tolerated when Hamming-matching a linker whose element declares no ``anchor``
+#: ``max_mismatch``. One per short linker absorbs ordinary sequencing error without letting a wrong
+#: frame match (two independent linkers must BOTH match at the right spacing to lock a phase).
+_DEFAULT_LINKER_MAX_MISMATCH = 1
+
+
+def has_anchored_elements(read: Read) -> bool:
+    """True iff any element on this read floats (declares an ``anchor``) — the resolver's trigger."""
+    return any(el.anchor is not None for el in read.elements)
+
+
+def _fixed_width(el: Element) -> int | None:
+    """The element's width when it is known up front; ``None`` for a variable-length / open element."""
+    if el.start is not None and el.end is not None:
+        return el.end - el.start
+    if el.sequence is not None:
+        return len(el.sequence)
+    if el.min_len is not None and el.min_len == el.max_len:
+        return el.min_len
+    return None
+
+
+def _variable_elements(read: Read) -> list[Element]:
+    """Elements whose length is an unknown to solve — a declared ``[min_len, max_len]`` with min<max.
+
+    These are the phase's degrees of freedom (BD Enhanced has exactly one: the 0-3 bp insert). An
+    open-ended cDNA/gDNA tail is NOT one of these — it has no upstream effect on the barcode frame, so
+    it is resolved last, running to the end of the read.
+    """
+    out: list[Element] = []
+    for el in read.elements:
+        if el.type in ("cdna", "gdna") and el.end is None:
+            continue
+        if el.min_len is not None and el.max_len is not None and el.min_len < el.max_len:
+            out.append(el)
+    return out
+
+
+def _candidate_assignments(read: Read, *, cap: int = 256) -> list[dict[str, int]]:
+    """Every combination of lengths for the variable elements, as ``{element_name: length}``.
+
+    Capped so a pathological spec cannot make resolution exponential; BD Enhanced yields 4 candidates
+    (insert length 0-3). Returns ``[{}]`` (the single empty assignment) when nothing is variable, so a
+    purely motif-anchored fixed-width chemistry still resolves.
+    """
+    variable = _variable_elements(read)
+    if not variable:
+        return [{}]
+    ranges = [range(el.min_len or 0, (el.max_len or 0) + 1) for el in variable]
+    names = [el.name for el in variable]
+    combos = list(product(*ranges))
+    if len(combos) > cap:
+        combos = combos[:cap]
+    return [dict(zip(names, lengths, strict=True)) for lengths in combos]
+
+
+def _anchor_start(el: Element, windows: dict[str, tuple[int, int]], prev_end: int) -> int:
+    """Where this element begins, from its ``anchor`` (falling back to the previous element's end).
+
+    The chain BD Enhanced declares is sequential — each element anchored to the previous element's
+    ``end`` with ``offset 0`` — so resolving in element order means every ``ref_element`` is already
+    placed, and this reduces to a cumulative walk. Honouring the anchor rather than assuming adjacency
+    keeps a non-zero ``offset`` or a ``read_start``-relative element correct too.
+    """
+    a = el.anchor
+    if a is None:
+        return el.start if el.start is not None else prev_end
+    if a.relative_to == "element" and a.ref_element and a.ref_element in windows:
+        ref = windows[a.ref_element]
+        base = ref[0] if a.ref_side == "start" else ref[1]
+        return base + a.offset
+    if a.relative_to == "read_start":
+        return a.offset
+    # read_end, or an unresolved ref: fall back to the running position (the chain never needs this).
+    return prev_end + a.offset
+
+
+def _resolve_for_assignment(
+    seq: str, read: Read, assignment: dict[str, int]
+) -> tuple[dict[str, tuple[int, int]], int, bool] | None:
+    """Place every element for one candidate length assignment.
+
+    Returns ``(windows, linker_mismatches, all_linkers_matched)`` or ``None`` if the layout does not
+    fit the read (a window runs off the 3' end). ``linker_mismatches`` is the total Hamming distance
+    across all ``linker``/``fixed`` elements — the smaller, the better the frame fits.
+    """
+    windows: dict[str, tuple[int, int]] = {}
+    pos = 0
+    mismatches = 0
+    all_matched = True
+    n = len(seq)
+    elements = read.elements
+    for i, el in enumerate(elements):
+        start = _anchor_start(el, windows, pos)
+        width = assignment.get(el.name)
+        if width is None:
+            width = _fixed_width(el)
+        if width is None:
+            # open-ended element (cDNA tail): runs to the end of the read; must be terminal.
+            if i != len(elements) - 1:
+                return None
+            end = n
+        else:
+            end = start + width
+        if start < 0 or end > n:
+            return None  # this phase pushes an element off the read
+        windows[el.name] = (start, end)
+        if el.sequence is not None:  # a linker/fixed element anchors the frame
+            tol = el.anchor.max_mismatch if el.anchor is not None else _DEFAULT_LINKER_MAX_MISMATCH
+            d = _hamming(seq[start:end], el.sequence)
+            mismatches += d
+            if d > tol:
+                all_matched = False
+        pos = end
+    return windows, mismatches, all_matched
+
+
+def resolve_windows(seq: str, read: Read) -> dict[str, tuple[int, int]] | None:
+    """Locate each element's ``[start, end)`` in ``seq`` by phase detection; ``None`` if not found.
+
+    Picks the candidate phase whose linker/fixed elements all Hamming-match their declared sequence
+    (ties broken by fewest total mismatches). Requires at least one linker to anchor on — with none,
+    the frame is unobservable and the read is left unresolved rather than sliced arbitrarily.
+    """
+    if not any(el.sequence is not None for el in read.elements):
+        return None
+    best: tuple[int, dict[str, tuple[int, int]]] | None = None
+    for assignment in _candidate_assignments(read):
+        resolved = _resolve_for_assignment(seq, read, assignment)
+        if resolved is None:
+            continue
+        windows, mismatches, all_matched = resolved
+        if not all_matched:
+            continue
+        if best is None or mismatches < best[0]:
+            best = (mismatches, windows)
+    return best[1] if best is not None else None
+
+
+def _hamming(a: str, b: str) -> int:
+    """Substitution distance over the compared length; length mismatch counts as all-different tail."""
+    d = sum(1 for x, y in zip(a, b, strict=False) if x != y)  # short-zip: tail counted below
+    return d + abs(len(a) - len(b))

seqforge/kb/generate.py

@@ -0,0 +1,147 @@
+"""Synthetic FASTQ generation derived PURELY from ``spec.reads`` (round-trip).
+
+The generator never reads ``signature`` or ``backend`` — that is what makes the round-trip
+(``spec -> synth -> probe -> recover; assert recovered == declared``) a real test rather than a
+tautology. Barcodes with an onlist are drawn from a fixed synthetic cell pool reused across reads so
+the recurrence signal (low distinct-ratio) is realistic; UMIs are fresh-random (high distinct-ratio).
+"""
+
+from __future__ import annotations
+
+import gzip
+import random
+from pathlib import Path
+
+from .schema import Element, Spec
+
+_BASES = "ACGT"
+
+
+def write_fastq_gz(path: Path, seqs: list[str], *, prefix: str = "SIM") -> None:
+    """Write a REPRODUCIBLE ``.fastq.gz``: same reads in, same bytes out, hence the same sha256.
+
+    ``gzip.open(path, "wt")`` stamps the current mtime into the gzip header (and embeds the source
+    filename), so regenerating identical reads a second later produces different bytes. Everything
+    downstream is content-addressed by file sha256, so a wall-clock-dependent header silently
+    changes the dataset id — two runs over the same synthetic input never share a cache entry, and
+    "deterministic in (spec, seed)" quietly stops being true at the byte level where it is claimed.
+    ``mtime=0`` + ``filename=""`` make the output a pure function of the reads.
+
+    One writer, because this was duplicated at three sites and each carried the same latent bug.
+    """
+    payload = "".join(
+        f"@{prefix}:{i}\n{s}\n+\n{'I' * len(s)}\n" for i, s in enumerate(seqs)
+    ).encode()
+    with open(path, "wb") as raw, gzip.GzipFile(filename="", mode="wb", fileobj=raw, mtime=0) as gz:
+        gz.write(payload)
+
+
+def _rand(rng: random.Random, n: int) -> str:
+    return "".join(rng.choice(_BASES) for _ in range(n))
+
+
+def _fixed_length(el: Element) -> int | None:
+    """The element's constant width (pool-barcode width), or ``None`` if it has none.
+
+    A variable-length element (``min_len < max_len``) has no single width — this returns ``min_len`` as
+    the pool width for a barcode that happens to be variable, but the per-read *generated* length comes
+    from :func:`_draw_length`, which is what actually creates the diversity-insert stagger.
+    """
+    if el.start is not None and el.end is not None:
+        return el.end - el.start
+    if el.min_len is not None:
+        return el.min_len
+    return None
+
+
+def _draw_length(el: Element, rng: random.Random) -> int | None:
+    """The length to GENERATE for one read: fixed when the element is fixed, drawn when it floats.
+
+    A ``[min_len, max_len]`` with ``min < max`` (BD Rhapsody Enhanced's 0-3 bp diversity insert) draws
+    a per-read length so downstream elements shift — the stagger the anchored resolver must recover.
+    Collapsing it to a constant (the pre-#43 behaviour) made the round-trip verify nothing about
+    anchoring: every synthetic read had the same offsets a fixed-window slice would have found anyway.
+    """
+    if el.start is not None and el.end is not None:
+        return el.end - el.start
+    if el.min_len is not None and el.max_len is not None and el.min_len != el.max_len:
+        return rng.randint(el.min_len, el.max_len)
+    if el.min_len is not None:
+        return el.min_len
+    return None
+
+
+def build_pools(spec: Spec, *, seed: int = 0, pool_size: int = 64) -> dict[str, list[str]]:
+    """Build the synthetic barcode pool backing each onlist *alias*, keyed by ``Element.onlist``.
+
+    Deterministic in ``(seed, pool_size)`` and independent of read generation, so a test can
+    reconstruct the exact whitelist the reads will be drawn from (to register it as a synthetic
+    onlist for the resolver). ``pool_size`` distinct barcodes drive the low-distinct-ratio recurrence
+    signal; keep it well below the read count.
+    """
+    rng = random.Random(seed)
+    pools: dict[str, list[str]] = {}
+    for read in spec.reads:
+        for el in read.elements:
+            if el.onlist and el.onlist not in pools:
+                length = _fixed_length(el) or 16
+                pools[el.onlist] = [_rand(rng, length) for _ in range(pool_size)]
+    return pools
+
+
+def generate_reads(
+    spec: Spec,
+    *,
+    n: int = 2000,
+    seed: int = 0,
+    pool_size: int = 64,
+    cdna_min: int = 60,
+    cdna_max: int = 91,
+    pools: dict[str, list[str]] | None = None,
+) -> dict[str, list[str]]:
+    """Generate ``n`` synthetic reads per declared read, keyed by ``Read.id``.
+
+    ``pool_size`` sets how many distinct barcodes back each onlist (drives the recurrence signal);
+    keep it well below ``n`` so the cell-barcode distinct-ratio lands in-band. Pass ``pools`` (from
+    :func:`build_pools` with the same ``seed``/``pool_size``) to reuse a known whitelist.
+    """
+    if pools is None:
+        pools = build_pools(spec, seed=seed, pool_size=pool_size)
+    rng = random.Random(seed + 1)  # a stream distinct from pool construction, still deterministic
+    result: dict[str, list[str]] = {}
+    for read in spec.reads:
+        seqs: list[str] = []
+        for _ in range(n):
+            seqs.append(
+                "".join(_gen_element(el, rng, pools, cdna_min, cdna_max) for el in read.elements)
+            )
+        result[read.id] = seqs
+    return result
+
+
+def _gen_element(
+    el: Element,
+    rng: random.Random,
+    pools: dict[str, list[str]],
+    cdna_min: int,
+    cdna_max: int,
+) -> str:
+    if el.type in ("linker", "fixed"):
+        return el.sequence or ""
+    if el.type == "diversity":
+        # a variable 5' insert of random bases -> the per-read stagger; length drawn in [min,max]
+        return _rand(rng, _draw_length(el, rng) or 0)
+    length = _draw_length(el, rng)
+    if el.type == "barcode":
+        return rng.choice(pools[el.onlist]) if el.onlist else _rand(rng, length or 8)
+    if el.type == "umi":
+        return _rand(rng, length or 10)
+    if el.type in ("cdna", "gdna"):
+        return _rand(rng, length or rng.randint(cdna_min, cdna_max))
+    if el.type == "poly_t":
+        return "T" * (length or 10)
+    if el.type == "poly_a":
+        return "A" * (length or 10)
+    if el.type == "index":
+        return _rand(rng, length or 8)
+    return _rand(rng, length or 1)