seqforge 2026.7.1__py3-none-any.whl

seqforge/probe/signals.py

@@ -0,0 +1,250 @@
+"""Tier A structural signals — computed from a bounded sample, with no KB and no role assignment.
+
+Every function here reports *structure* (composition, segmentation, recurrence, header grammar,
+integrity). None of it assigns a role — ``constant`` is "a constant span", never "the TSO". That
+interpretation is the resolver's job.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Literal
+
+from ..models.observation import (
+    ConstantSegment,
+    CycleComposition,
+    HomopolymerSegment,
+    RandomSegment,
+    ReadLengthProfile,
+    ReadNameGrammar,
+    Segment,
+    WindowDistinctRatio,
+)
+
+_BASE_IDX = {"A": 0, "C": 1, "G": 2, "T": 3}
+_PURE_THRESHOLD = 0.9  # a cycle whose dominant base fraction >= this is "constant sequence"
+_HOMOPOLYMER_MIN = (
+    4  # a run of >= this many identical dominant bases is a homopolymer, not a linker
+)
+_SRA_HEADER = re.compile(r"^[SED]RR\d+\.\d+")
+_ILLUMINA_INDEX = re.compile(r"[ /]([ACGTN]{6,})(?:\+([ACGTN]{6,}))?\s*$")
+
+
+def per_cycle_composition(seqs: list[str]) -> list[CycleComposition]:
+    """Fraction of A/C/G/T/N at each 0-based cycle, over reads long enough to reach that cycle."""
+    if not seqs:
+        return []
+    max_len = max(len(s) for s in seqs)
+    counts = [[0, 0, 0, 0, 0] for _ in range(max_len)]
+    denom = [0] * max_len
+    for s in seqs:
+        for i, ch in enumerate(s):
+            counts[i][_BASE_IDX.get(ch, 4)] += 1  # non-ACGT (incl. N) -> the N bucket
+            denom[i] += 1
+    out: list[CycleComposition] = []
+    for i in range(max_len):
+        d = denom[i] or 1
+        c = counts[i]
+        out.append(
+            CycleComposition(cycle=i, a=c[0] / d, c=c[1] / d, g=c[2] / d, t=c[3] / d, n=c[4] / d)
+        )
+    return out
+
+
+def _dominant(comp: CycleComposition) -> tuple[str, float]:
+    """Return the dominant ACGT base and its fraction for one cycle."""
+    pairs = (("A", comp.a), ("C", comp.c), ("G", comp.g), ("T", comp.t))
+    base, frac = max(pairs, key=lambda p: p[1])
+    return base, frac
+
+
+def _entropy_bits(comp: CycleComposition) -> float:
+    """Shannon entropy (bits) of the ACGT distribution at one cycle; ~2.0 for uniform."""
+    total = comp.a + comp.c + comp.g + comp.t
+    if total <= 0:
+        return 0.0
+    bits = 0.0
+    for p in (comp.a, comp.c, comp.g, comp.t):
+        q = p / total
+        if q > 0:
+            bits -= q * math.log2(q)
+    return bits
+
+
+def segment(comps: list[CycleComposition]) -> list[Segment]:
+    """Merge cycles into constant / homopolymer / random segments (structural, role-free).
+
+    A cycle whose dominant base fraction >= ``_PURE_THRESHOLD`` is "constant sequence". Within a run
+    of pure cycles, a run of the same dominant base (>= ``_HOMOPOLYMER_MIN``) is a homopolymer (polyT
+    capture / polyA tail); a stretch of varying pure bases is a linker/adapter/TSO (constant).
+    Everything else is random (CB/UMI/cDNA candidate). Index == cycle by construction.
+    """
+    if not comps:
+        return []
+    labels: list[tuple[str, str, float]] = []  # (kind, dominant_base, purity) per cycle
+    for comp in comps:
+        base, frac = _dominant(comp)
+        labels.append(("pure", base, frac) if frac >= _PURE_THRESHOLD else ("random", base, frac))
+
+    segments: list[Segment] = []
+    i = 0
+    n = len(labels)
+    while i < n:
+        kind = labels[i][0]
+        j = i + 1
+        while j < n and labels[j][0] == kind:
+            j += 1
+        if kind == "random":
+            mean_bits = sum(_entropy_bits(comps[k]) for k in range(i, j)) / (j - i)
+            segments.append(RandomSegment(start=i, end=j, mean_entropy_bits=mean_bits))
+        else:
+            segments.extend(_split_pure_run(labels, i, j))
+        i = j
+    return segments
+
+
+def _split_pure_run(labels: list[tuple[str, str, float]], lo: int, hi: int) -> list[Segment]:
+    """Split a run of pure cycles ``[lo, hi)`` into homopolymer + constant (linker) segments."""
+    out: list[Segment] = []
+    const_start: int | None = None
+
+    def flush_constant(end: int) -> None:
+        nonlocal const_start
+        if const_start is None:
+            return
+        bases = [labels[k][1] for k in range(const_start, end)]
+        purity = sum(labels[k][2] for k in range(const_start, end)) / (end - const_start)
+        out.append(
+            ConstantSegment(start=const_start, end=end, consensus="".join(bases), purity=purity)
+        )
+        const_start = None
+
+    k = lo
+    while k < hi:
+        base = labels[k][1]
+        r = k + 1
+        while r < hi and labels[r][1] == base:
+            r += 1
+        if r - k >= _HOMOPOLYMER_MIN:
+            flush_constant(k)
+            out.append(
+                HomopolymerSegment(
+                    base=base,  # type: ignore[arg-type]  # single ACGT char
+                    start=k,
+                    end=r,
+                    mean_run=float(r - k),
+                )
+            )
+        elif const_start is None:
+            const_start = k
+        k = r
+    flush_constant(hi)
+    return out
+
+
+def read_length_profile(seqs: list[str]) -> ReadLengthProfile:
+    """Mode, distinct-count, min/max, and (only when variable) percentiles of read length."""
+    lengths = sorted(len(s) for s in seqs)
+    if not lengths:
+        return ReadLengthProfile(mode=0, n_distinct=1, min_len=0, max_len=0)
+    freq: dict[int, int] = {}
+    for length in lengths:
+        freq[length] = freq.get(length, 0) + 1
+    mode = max(freq, key=lambda k: freq[k])
+    n_distinct = len(freq)
+    percentiles = None
+    if n_distinct > 1:
+        percentiles = {
+            "p1": lengths[max(0, (len(lengths) * 1) // 100 - 1)],
+            "p50": lengths[len(lengths) // 2],
+            "p99": lengths[min(len(lengths) - 1, (len(lengths) * 99) // 100)],
+        }
+    return ReadLengthProfile(
+        mode=mode,
+        n_distinct=n_distinct,
+        min_len=lengths[0],
+        max_len=lengths[-1],
+        percentiles=percentiles,
+    )
+
+
+def window_distinct_ratio(seqs: list[str], start: int, end: int) -> float | None:
+    """distinct/total over an explicit ``[start, end)`` window (role-conditioned; used by resolve)."""
+    window = [s[start:end] for s in seqs if len(s) >= end]
+    if not window:
+        return None
+    return len(set(window)) / len(window)
+
+
+def distinct_ratios(seqs: list[str], segments: list[Segment]) -> list[WindowDistinctRatio]:
+    """distinct/total over each random segment (candidate CB/UMI/cDNA window). Supports-only signal."""
+    out: list[WindowDistinctRatio] = []
+    for seg in segments:
+        if not isinstance(seg, RandomSegment):
+            continue
+        window = [s[seg.start : seg.end] for s in seqs if len(s) >= seg.end]
+        if not window:
+            continue
+        ratio = len(set(window)) / len(window)
+        out.append(
+            WindowDistinctRatio(
+                start=seg.start, end=seg.end, distinct_ratio=ratio, n_sampled=len(window)
+            )
+        )
+    return out
+
+
+def parse_read_name(name: str | None) -> ReadNameGrammar:
+    """Parse an Illumina header; detect SRA-normalized headers (the index has been stripped)."""
+    if not name:
+        return ReadNameGrammar(parsed=False)
+    if _SRA_HEADER.match(name):
+        return ReadNameGrammar(parsed=False, sra_normalized=True)
+    fields = name.split(":")
+    if len(fields) >= 7:
+        index_match = _ILLUMINA_INDEX.search(name)
+        index = index_match.group(1) if index_match else None
+        lane: int | None
+        tile: int | None
+        try:
+            lane = int(fields[3])
+            tile = int(fields[4])
+        except ValueError:
+            lane = None
+            tile = None
+        return ReadNameGrammar(
+            parsed=True,
+            instrument=fields[0],
+            run=fields[1],
+            flowcell=fields[2],
+            lane=lane,
+            tile=tile,
+            index=index,
+        )
+    return ReadNameGrammar(parsed=False)
+
+
+def quality_encoding(
+    min_ord: int | None, max_ord: int | None
+) -> Literal["phred33", "phred64", "unknown"]:
+    """Infer the Phred offset from the observed quality-char ordinal range."""
+    if min_ord is None or max_ord is None:
+        return "unknown"
+    if min_ord < 64:
+        return "phred33"
+    if max_ord > 74:
+        return "phred64"
+    return "unknown"
+
+
+def n_rate(seqs: list[str]) -> float:
+    """Fraction of non-ACGT (N) bases across the sample."""
+    total = 0
+    n_count = 0
+    for s in seqs:
+        total += len(s)
+        for ch in s:
+            if ch not in _BASE_IDX:
+                n_count += 1
+    return (n_count / total) if total else 0.0

seqforge/probe/streaming.py

@@ -0,0 +1,118 @@
+"""Bounded FASTQ streaming — the bounded-read invariant made mechanical.
+
+Decompress a gzip FASTQ incrementally and stop at whichever budget trips first: ``max_reads`` records
+or ``max_bytes`` *decompressed* bytes. There is no random-access seek plan and no whole-file
+decompression; a code path that can touch a whole multi-GB FASTQ is a bug.
+"""
+
+from __future__ import annotations
+
+import gzip
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import IO
+
+
+@dataclass
+class StreamSample:
+    """A bounded sample of a FASTQ, plus the byte/record accounting that proves it stayed in budget."""
+
+    seqs: list[str] = field(default_factory=list)
+    first_name: str | None = None
+    qual_min_ord: int | None = None
+    qual_max_ord: int | None = None
+    n_reads: int = 0
+    decompressed_bytes: int = 0
+    compressed_bytes: int = 0
+    truncated: bool = False
+    ok: bool = True
+    budget_exhausted: bool = False
+
+
+def sample_fastq_stream(fileobj: IO[bytes], max_reads: int, max_bytes: int) -> StreamSample:
+    """Read at most ``max_reads`` records / ``max_bytes`` decompressed bytes from a gzip FASTQ stream.
+
+    Source-agnostic: ``fileobj`` is any binary reader positioned at the gzip magic — a local file
+    (:func:`sample_fastq_gz`) or an in-memory range-read *prefix* (``io.remote.probe_remote``). A prefix
+    that ends mid-member is the normal remote case, and it is handled by the same path as a truncated
+    upload: the cut is caught and the trailing partial record dropped. ``compressed_bytes`` is the
+    reader's final position; the caller owns opening and closing ``fileobj``.
+
+    Parameters
+    ----------
+    fileobj
+        A binary stream of gzip-compressed FASTQ bytes (a whole file, or a bounded head prefix).
+    max_reads
+        Hard cap on records read.
+    max_bytes
+        Hard cap on *decompressed* bytes read. Whichever cap trips first stops the stream.
+
+    Returns
+    -------
+    StreamSample
+        The sampled sequences and the byte/record accounting. ``truncated`` is set if the gzip
+        stream ends mid-member before either budget or a clean EOF; ``ok`` is False on a
+        gzip/format error.
+    """
+    sample = StreamSample()
+    try:
+        with gzip.GzipFile(fileobj=fileobj) as gz:
+            line_iter = iter(gz)
+            while sample.n_reads < max_reads and sample.decompressed_bytes < max_bytes:
+                try:
+                    header = next(line_iter, None)
+                    if header is None:  # clean EOF, fewer reads than the budget
+                        break
+                    seq = next(line_iter, None)
+                    plus = next(line_iter, None)
+                    qual = next(line_iter, None)
+                except (EOFError, gzip.BadGzipFile, OSError):
+                    # gzip stream cut mid-member (truncated upload, or a bounded range-read prefix).
+                    sample.truncated = True
+                    break
+                if seq is None or plus is None or qual is None:
+                    # a partial final record => the stream was cut mid-record.
+                    sample.truncated = True
+                    break
+
+                name = header.decode("ascii", "replace").rstrip("\n")
+                seq_s = seq.decode("ascii", "replace").rstrip("\n")
+                qual_s = qual.decode("ascii", "replace").rstrip("\n")
+
+                if sample.first_name is None:
+                    sample.first_name = name.lstrip("@")
+                sample.seqs.append(seq_s)
+                _update_qual_ords(sample, qual_s)
+                sample.n_reads += 1
+                sample.decompressed_bytes += len(header) + len(seq) + len(plus) + len(qual)
+    except (gzip.BadGzipFile, OSError):
+        sample.ok = False
+    finally:
+        sample.compressed_bytes = fileobj.tell()
+
+    sample.budget_exhausted = sample.n_reads >= max_reads or sample.decompressed_bytes >= max_bytes
+    return sample
+
+
+def sample_fastq_gz(path: str | Path, max_reads: int, max_bytes: int) -> StreamSample:
+    """Read a bounded head of a LOCAL gzip FASTQ. Thin wrapper over :func:`sample_fastq_stream`.
+
+    Opens the file, hands the reader to the source-agnostic sampler, and closes it. ``gzip.GzipFile``
+    does not close a ``fileobj`` it was handed, so the ``tell()`` inside the sampler runs before this
+    ``close()``.
+    """
+    raw = open(path, "rb")  # noqa: SIM115 - closed explicitly in finally
+    try:
+        return sample_fastq_stream(raw, max_reads, max_bytes)
+    finally:
+        raw.close()
+
+
+def _update_qual_ords(sample: StreamSample, qual: str) -> None:
+    """Track the min/max quality-char ordinal (used to infer the Phred offset)."""
+    if not qual:
+        return
+    ords = [ord(c) for c in qual]
+    lo, hi = min(ords), max(ords)
+    sample.qual_min_ord = lo if sample.qual_min_ord is None else min(sample.qual_min_ord, lo)
+    sample.qual_max_ord = hi if sample.qual_max_ord is None else max(sample.qual_max_ord, hi)

seqforge/project.py

@@ -0,0 +1,177 @@
+"""Project-level views over a multi-assay compile: the flat ``sample_metadata.tsv`` and ``project.yaml``.
+
+A large project splits into **assays**, one :class:`~seqforge.models.dataset.DatasetManifest` each.
+Those manifests are the source of truth; this module unions them back into the "one study" views a
+human reads — a flat table with one row per sample across every assay, and a small index mapping each
+assay to its subdir / chemistry / sample count. Both are **derived** from the manifests (so they cannot
+drift from them) and **deterministic** (sorted rows and columns), so regenerating is a no-op.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .models.dataset import DatasetManifest
+from .workspace import state_dir
+
+#: Common BioSample attributes, ordered for readability. Any *other* resolved attribute follows,
+#: sorted — the column set is the union of what actually resolved, never a hand-fixed schema.
+_PREFERRED_ATTRS: tuple[str, ...] = (
+    "strain",
+    "genotype",
+    "age",
+    "dev_stage",
+    "sex",
+    "tissue",
+    "cell_type",
+    "cell_line",
+    "treatment",
+    "source_name",
+    "disease",
+)
+
+_LEADING: tuple[str, ...] = ("sample_id", "accession", "assay", "organism")
+_TRAILING: tuple[str, ...] = ("n_files", "files")
+
+#: The project-level file names, written at the top of ``seqforge/`` (never inside an assay subdir).
+SAMPLE_METADATA_TSV = "sample_metadata.tsv"
+PROJECT_YAML = "project.yaml"
+
+
+def sample_metadata_table(
+    manifests: list[DatasetManifest],
+) -> tuple[list[str], list[dict[str, str]]]:
+    """One row per sample across every manifest. Returns ``(columns, rows)``, both deterministic.
+
+    Columns: ``sample_id, accession, assay, organism``, then every resolved BioSample attribute
+    (common ones first, the rest sorted), then ``n_files, files``. An empty cell means the attribute
+    did not resolve for that sample — absence, honestly, rather than a guessed value.
+    """
+    rows: list[dict[str, str]] = []
+    seen_attrs: set[str] = set()
+    for manifest in manifests:
+        chemistry = manifest.library.chemistry.value[0]
+        organism = str(manifest.experiment.organism.value)
+        for sample in manifest.experiment.samples:
+            attrs = {key: ev.value for key, ev in sample.attributes.items()}
+            seen_attrs.update(attrs)
+            rows.append(
+                {
+                    "sample_id": sample.sample_id,
+                    "accession": sample.accession or "",
+                    "assay": chemistry,
+                    "organism": organism,
+                    "n_files": str(len(sample.file_uris)),
+                    "files": ";".join(sorted(Path(uri).name for uri in sample.file_uris)),
+                    **attrs,
+                }
+            )
+    attr_cols = [a for a in _PREFERRED_ATTRS if a in seen_attrs]
+    attr_cols += sorted(seen_attrs - set(_PREFERRED_ATTRS))
+    columns = [*_LEADING, *attr_cols, *_TRAILING]
+    rows.sort(key=lambda r: (r["assay"], r["sample_id"]))
+    return columns, rows
+
+
+def format_tsv(columns: list[str], rows: list[dict[str, str]]) -> str:
+    """Render ``(columns, rows)`` as a TSV string (trailing newline). Tabs/newlines in a value are
+    squashed to spaces so a stray attribute value can never break the table's shape."""
+
+    def cell(value: str) -> str:
+        return " ".join(str(value).split())
+
+    lines = ["\t".join(columns)]
+    lines += ["\t".join(cell(r.get(c, "")) for c in columns) for r in rows]
+    return "\n".join(lines) + "\n"
+
+
+def project_index(assays: list[dict[str, Any]]) -> dict[str, Any]:
+    """The ``project.yaml`` payload: the assays (sorted by chemistry) plus project-wide counts.
+
+    Each assay entry names its chemistry, its subdir (``None`` for a single-assay flat project), its
+    sample count, and its manifest / pipeline paths — enough to discover every per-assay output.
+    """
+    entries = sorted(assays, key=lambda a: str(a.get("chemistry", "")))
+    return {
+        "n_assays": len(entries),
+        "n_samples": sum(int(a.get("n_samples", 0)) for a in entries),
+        "assays": entries,
+    }
+
+
+def discover_assays(workspace: str | Path) -> list[tuple[str | None, Path]]:
+    """``(subdir, manifest_path)`` for each assay under ``seqforge/``.
+
+    A top-level ``manifest.yaml`` is a single, flat assay (subdir ``None``); otherwise every
+    ``seqforge/<assay>/manifest.yaml`` is one assay. Sorted, so the result is deterministic.
+    """
+    root = state_dir(workspace)
+    top = root / "manifest.yaml"
+    if top.is_file():
+        return [(None, top)]
+    if not root.is_dir():
+        return []
+    found = [
+        (child.name, child / "manifest.yaml")
+        for child in root.iterdir()
+        if child.is_dir() and (child / "manifest.yaml").is_file()
+    ]
+    return sorted(found, key=lambda pair: pair[0] or "")
+
+
+def _relative_to(path: Any, workspace: str | Path) -> Any:
+    """A path made relative to ``workspace`` when it is under it, else left untouched (None passes).
+
+    Keeps ``project.yaml`` machine-independent: a workspace's absolute location must not leak into an
+    index that is content-addressed reproducible and re-generatable anywhere the outputs are copied.
+    """
+    if not path:
+        return path
+    try:
+        return str(Path(path).resolve().relative_to(Path(workspace).resolve()))
+    except ValueError:
+        return path
+
+
+def write_project_views(workspace: str | Path, assays: list[dict[str, Any]]) -> tuple[Path, Path]:
+    """Write ``sample_metadata.tsv`` + ``project.yaml`` at the project top and return their paths.
+
+    ``assays`` is one dict per assay carrying at least ``chemistry``, ``subdir``, ``n_samples`` and a
+    ``manifest`` path (optionally ``pipeline``/``snakefile``); the manifests are loaded to build the
+    flat table. Written even for a single-assay project — the "one study" view is always useful. Paths
+    in ``project.yaml`` are stored relative to ``workspace`` so the index is portable.
+    """
+    root = state_dir(workspace)
+    root.mkdir(parents=True, exist_ok=True)
+    manifests = [
+        DatasetManifest.model_validate(yaml.safe_load(Path(a["manifest"]).read_text()))
+        for a in assays
+    ]
+    columns, rows = sample_metadata_table(manifests)
+    tsv_path = root / SAMPLE_METADATA_TSV
+    tsv_path.write_text(format_tsv(columns, rows))
+
+    portable = [
+        {
+            k: (_relative_to(v, workspace) if k in ("manifest", "snakefile", "pipeline") else v)
+            for k, v in a.items()
+        }
+        for a in assays
+    ]
+    yaml_path = root / PROJECT_YAML
+    yaml_path.write_text(yaml.safe_dump(project_index(portable), sort_keys=True))
+    return tsv_path, yaml_path
+
+
+__all__ = [
+    "SAMPLE_METADATA_TSV",
+    "PROJECT_YAML",
+    "sample_metadata_table",
+    "format_tsv",
+    "project_index",
+    "discover_assays",
+    "write_project_views",
+]

seqforge/resolve/__init__.py

@@ -0,0 +1,98 @@
+"""``resolve`` — the scoring engine: bytes + KB (+ optional hypothesis) -> a ranked, escalated verdict.
+
+Deterministic and LLM-free. Signature-test evaluators score a JSON-safe evidence matrix
+``M[role][file]``; a cardinality-normalized joint role-assignment picks the best injective
+files->roles map per technology; escalation turns the ranked candidates into exactly one of
+``Decision`` / ``Conflict`` / ``Question`` / ``Blocker`` with rung provenance. Every artifact is
+content-addressed under ``.seqforge/``. The only interpretive input is a span-verified
+``hypothesis`` that steers control flow — it never enters the matrix (§3.4).
+"""
+
+from __future__ import annotations
+
+#: CalVer YYYY.M.PATCH; bumped when scoring/assignment/escalation semantics change. Folded into the
+#: dataset cache key so a resolver change invalidates stale candidates.
+#: 2026.7.1 — `resolve_runs`: files are grouped into runs and each run is assigned on its own
+#: bytes. A dataset resolved as one library dropped every file but one pair per role.
+#: 2026.7.2 — over-length onlist admission: a barcode read over-sequenced into the length dead zone
+#: (canonical < mode < over_length_min) is admitted when its barcode prefix hits the whitelist, so a
+#: previously-forbidden over-sequenced read now resolves to its chemistry (#7).
+#: 2026.7.3 — over-length admission uses a FLOOR-ANCHORED bar, not the support `min`: admission asks
+#: "barcode vs cDNA" (chance ≈ whitelist floor), not "confident barcode" (0.6). A real over-sequenced
+#: barcode read with ordinary sequencing error hit below 0.6 on exact match and fell to bulk (#7,
+#: GSE126954 SRX5411291); the floor-anchored bar admits it while still rejecting a same-length cDNA.
+#: 2026.7.4 — multi-lane surplus absorption: a run sequenced across N lanes holds N files per role, but
+#: the injective assignment fills each role once; the surplus same-length lane files are now absorbed
+#: into their role (was NO_VALID_ROLE_ASSIGNMENT), so a multi-lane 10x dataset resolves (GSE208154).
+#: 2026.7.5 — surplus absorption matches by READ DESIGNATION (R1/R2/…) + length, not de-laned filename.
+#: One accession sequenced across several flowcells carries a different flowcell id per file, so the
+#: lanes of one read de-laned to different names and the cross-flowcell surplus stayed unassigned;
+#: matching on the designation the sequencer wrote fuses them (GSE208154 is 2 flowcells x 8 lanes x
+#: {R1,R2,I1} per run, which 2026.7.4's de-lane equality could not absorb across the flowcell boundary).
+#: 2026.7.6 — role assignment optimizes (coverage, score) lexicographically, not score alone: a file
+#: eligible for exactly one role claims it before a multi-role file can. GSE208154's real cDNA reads
+#: have low-diversity 5′ ends, so a 28 bp barcode read out-scored the 91 bp cDNA read for the cDNA role;
+#: score-max then took a barcode file for cDNA and orphaned every cDNA-length file (absorption could not
+#: recover — the cDNA rep was itself a barcode read). The 91 bp reads are forbidden for the barcode role
+#: (dead zone), so cDNA is their only home; coverage now seats them there. No-op for one-file-per-role
+#: runs (injectivity already forces the map), so the other 12 worm datasets are unaffected.
+#: 2026.7.7 — hierarchical descent: resolve_dataset scores a length-FEASIBLE pool (drawn from runnable
+#: specs via the scorer's own read-length gate) instead of a flat loop over the whole KB; escalate still
+#: receives the full KB. Provably winner-invariant — a length-infeasible spec would have scored
+#: forbidden — so the winner equals a flat full scan; this only narrows which specs are scored as the KB
+#: grows, and reads sibling confusability off the tree instead of hand-declared cliques.
+#: 2026.7.8 — family-level chemistry authority: a WITHIN-family asserted-vs-observed geometry difference
+#: (asserted v2, observed v3 — both 10x-3p-gex leaves) is no longer a blocking conflict. A paper names
+#: the assay family reliably and the leaf vaguely; the bytes decide the leaf, so the disagreement is
+#: recorded as a `resolved` conflict (auditable, non-blocking) instead of exit 4. A CROSS-family
+#: difference still blocks. Auto-resolves GSE229022 ("10x 3' v2/v3" in prose, byte-provably v3).
+#: 2026.7.9 — cross-family honesty made symmetric: a BULK chemistry asserted but a barcoded single-cell
+#: library observed now surfaces a conflict (exit 4), the mirror of single-cell-asserted-but-bulk-observed
+#: (which already did). Both directions of a wrong data-vs-paper pairing are now caught, not just one.
+#: 2026.7.10 — BD Rhapsody Enhanced beads: anchored barcode elements are located by their adjacent
+#: anchor sequence before the onlist window is read, so an Enhanced (diversity-spacer) library scores its
+#: CLS whitelists at the right offset instead of missing them at a fixed one (#53).
+#: 2026.7.11 — barcode-role seating + barcode-absent refusal (F1): the barcode role may only seat on a
+#: read that clears the onlist bar when some read does (no equal-length swap onto a cDNA mate), and a
+#: barcoded winner with NO whitelist-hitting read now refuses (BARCODE_READ_ABSENT) instead of composing
+#: a pipeline STARsolo would run to an empty matrix.
+#: 2026.7.12 — barcode-absent refusal keys on ALL valid candidates, not just the top: an over-length
+#: v2/v3 tie where v2 edges v3 on score (top=v2, 737K misses) while v3's 3M list hits must NOT refuse —
+#: the data is barcoded and resolves to v3. Only a dataset where no barcoded leaf hits is barcode-absent
+#: (PRJNA658829 SRR12575567 was false-blocked before this).
+RESOLVE_VERSION = "2026.7.12"
+
+from .cache import Cache, dataset_id  # noqa: E402
+from .engine import (  # noqa: E402
+    Hypothesis,
+    MultiRunOutput,
+    ResolveOutput,
+    RunResolution,
+    exit_code_for,
+    resolve_dataset,
+    resolve_runs,
+    role_of_sha_for,
+)
+from .group import group_runs, run_key  # noqa: E402
+from .scoring import Cell, TechEvaluation, build_tech_evaluation  # noqa: E402
+from .window import WindowProbe  # noqa: E402
+
+__all__ = [
+    "RESOLVE_VERSION",
+    "resolve_dataset",
+    "resolve_runs",
+    "ResolveOutput",
+    "MultiRunOutput",
+    "RunResolution",
+    "role_of_sha_for",
+    "group_runs",
+    "run_key",
+    "Hypothesis",
+    "exit_code_for",
+    "build_tech_evaluation",
+    "TechEvaluation",
+    "Cell",
+    "WindowProbe",
+    "Cache",
+    "dataset_id",
+]