seqforge 2026.7.1__py3-none-any.whl

seqforge/kb/specs/10x-3p-gex/spec.yaml

@@ -0,0 +1,62 @@
+schema_version: 1
+
+# An ABSTRACT FAMILY NODE, not a runnable chemistry. It has no `backend`: v2 and v3 parse reads
+# differently (10 vs 12 bp UMI, different whitelists), so there is no single recipe to compile — descent
+# always resolves to a leaf child. Its job is threefold: (1) group v2/v3/v3.1 so their pairwise
+# `processing_divergent` confusable edges collapse to one `parent` link; (2) carry `children_decided_by`
+# so the divergent-tie question knows the whitelist separates them; (3) be the family a prose/metadata
+# prior names ("10x 3' gene expression") when it orders the descent. It is NEVER scored as a candidate
+# (the scorer skips backend-less nodes) and is validated by the recognition self-test, not `kb roundtrip`.
+
+identity:
+  id: 10x-3p-gex
+  version: family
+  name: "10x Chromium Single Cell 3' Gene Expression (family)"
+  aliases: ["10x 3'", "10x 3-prime", "Chromium 3' GEX", "10x Chromium 3' GEX", "SC3P", "single cell 3-prime gene expression"]
+  assay_ontology: ["EFO:0009922"]        # 10x 3' GEX (the assay the whole family instantiates)
+  modality: rna
+
+node_kind: family
+# The children (v2 / v3 / v3.1) share 16 bp CB geometry and are told apart ONLY by their whitelist —
+# so a divergent tie among them is decidable_by onlist, sourced here instead of a per-sibling edge.
+children_decided_by: [onlist]
+
+reads:
+  # The loose 10x 3' barcode read: 16 bp CB + a 10-12 bp UMI (26-28 bp total), covering v2 (26) and
+  # v3/v3.1 (28). min/max_len 26..28 is what keeps the family SEPARABLE from bulk: a long cDNA read
+  # (>= 40 bp) fails this gate, so the family never claims bulk/SPLiT-seq data.
+  - id: R1
+    seqspec_read_id: R1
+    file_hint: "_R1_"
+    strand: pos
+    min_len: 26
+    max_len: 28
+    elements:
+      - {type: barcode, name: CB,  start: 0,  end: 16, seqspec_region_type: barcode}
+      - {type: umi,     name: UMI, start: 16, end: 28, seqspec_region_type: umi}
+  - id: R2
+    seqspec_read_id: R2
+    file_hint: "_R2_"
+    strand: pos
+    min_len: 25
+    max_len: null
+    elements:
+      - {type: cdna, name: cdna, start: 0, end: null, seqspec_region_type: cdna}
+
+onlists: {}
+
+signature:
+  # Coarse recognition only — enough to admit any 10x 3' child at rungs 0-2 and to reject bulk (whose
+  # R1 is a long cDNA, not a 16 bp CB in a 26-28 bp read). NO exact segment_length: 26 and 28 both pass.
+  requires:
+    - {test: read_count, roles: 2}
+    - {test: has_segment, read: R1, start: 0, end: 16, kind: random}
+  supports:
+    - when: {test: distinct_ratio, read: R1, start: 0, end: 16, expect: low}
+      weight: 2.0                # the CB recurs across reads
+    - when: {test: distinct_ratio, read: R2, start: 0, end: 20, expect: high}
+      weight: 1.0                # cDNA is diverse
+  excludes: []
+
+# no backend: abstract classifier. no parent: a root family.
+confusable_with: []

seqforge/kb/specs/10x-3p-gex-v2/README.md

@@ -0,0 +1,41 @@
+# 10x Chromium Single Cell 3' Gene Expression v2
+
+Droplet single-cell RNA-seq — the generation before v3. Every droplet holds one gel bead, which tags
+all of a cell's transcripts with the same **cell barcode** and each individual mRNA molecule with a
+unique **UMI**. That lets you count molecules per gene per cell.
+
+## How it's read
+
+Two reads come off the sequencer:
+
+| read | length | what it holds |
+| --- | --- | --- |
+| **R1** | 26 bp | a 16 bp **cell barcode** + a 10 bp **UMI** |
+| **R2** | open-ended | the **cDNA** (the transcript itself), read sense to the mRNA |
+
+The cell barcode is drawn from 10x's published `737K-august-2016` list (~737,000 barcodes).
+
+## How seqforge tells v2 apart from v3
+
+The only difference visible in the reads is **R1 length**: v2 is 16 + **10** = **26 bp**; v3 is
+16 + **12** = **28 bp**. That 2 bp gap is decisive on its own, so seqforge separates v2 from v3 by
+read geometry alone — before it ever consults a barcode list. The two are never confused. (Their
+whitelists differ too — `737K-august-2016` vs `3M-february-2018` — but length settles it first.)
+
+If a paper or database says "v2" while the reads are actually 28 bp, seqforge does **not** quietly
+pick one. It surfaces the disagreement (metadata says 26 bp, the bytes say 28 bp) and hands it to a
+human — the bytes decide what the data is.
+
+## Gotchas
+
+- **The barcode read can go missing on SRA.** `fasterq-dump` without `--include-technical` drops R1
+  entirely; seqforge blocks rather than guessing which file is which. Re-fetch with
+  `--include-technical`, or pull the submitter's original files.
+- SRA rewrites read-name headers, so seqforge never trusts them when grouping files into samples.
+
+## References
+
+Read structure cross-checked against
+**[scg_lib_structs — 10x Chromium 3'](https://teichlab.github.io/scg_lib_structs/methods_html/10xChromium3.html)**
+(Teichmann Lab, CC-BY), which lays out the v2–v4 kits side by side. The exact, machine-readable
+definition seqforge uses lives in this entry's `spec.yaml`.

seqforge/kb/specs/10x-3p-gex-v2/spec.yaml

@@ -0,0 +1,83 @@
+schema_version: 1
+
+identity:
+  id: 10x-3p-gex-v2
+  version: "2"
+  name: "10x Chromium Single Cell 3' Gene Expression v2"
+  aliases: ["10x 3' v2", "Chromium 3' v2", "SC3Pv2", "single cell 3-prime v2"]
+  assay_ontology: ["EFO:0009899"]        # 10x 3' v2 — verified against live EFO (EBI OLS), not memory
+  modality: rna
+
+reads:
+  # R1 = the technical/barcode read. 26 bp = 16 CB + 10 UMI (the 2 bp shorter UMI vs v3's 28 bp).
+  # For a CANONICAL read the segment_length gate below separates v2 from v3 by that 26-vs-28. But
+  # max_len is null (an over-sequenced R1 is still v2), and when both accept an over-length read on
+  # geometry, the WHITELIST decides instead (v2 = 737K-august-2016) — see confusable_with.
+  - id: R1
+    seqspec_read_id: R1
+    file_hint: "_R1_"
+    strand: pos
+    min_len: 26
+    max_len: null
+    elements:
+      - {type: barcode, name: CB,  start: 0,  end: 16, onlist: cb_whitelist, seqspec_region_type: barcode}
+      - {type: umi,     name: UMI, start: 16, end: 26,                       seqspec_region_type: umi}
+  - id: R2
+    seqspec_read_id: R2
+    file_hint: "_R2_"
+    strand: pos
+    min_len: 25
+    max_len: null
+    elements:
+      - {type: cdna, name: cdna, start: 0, end: null, seqspec_region_type: cdna}
+
+onlists:
+  cb_whitelist:
+    registry: 737K-august-2016           # ~737,280 x 16 bp, forward orientation (v2 whitelist)
+    role: cell_barcode
+    expected_orientation: forward
+
+signature:
+  requires:                              # length separates v2 (26) from v3 (28) for canonical reads
+    - {test: read_count, roles: 2}
+    # length 26 exact for canonical reads; over_length_min 100 admits a full-length over-sequenced R1
+    # without loosening 26-vs-28 (a 28 bp read is < 100 -> not over-length -> still FAILs v2's exact
+    # 26), and a 60-94 bp cDNA/split-pool read stays exact-checked and rejected.
+    - {test: segment_length, read: R1, length: 26, tolerance: 0, over_length_min: 100}
+    - {test: has_segment, read: R1, start: 0,  end: 16, kind: random}
+    - {test: has_segment, read: R1, start: 16, end: 26, kind: random}
+  supports:
+    - when: {test: onlist_hit_rate, read: R1, start: 0, end: 16, onlist: cb_whitelist, orientation: forward, min: 0.6}
+      weight: 5.0
+    - when: {test: distinct_ratio, read: R1, start: 0,  end: 16, expect: low}
+      weight: 2.0
+    - when: {test: distinct_ratio, read: R1, start: 16, end: 26, expect: high}
+      weight: 1.0
+    - when: {test: distinct_ratio, read: R2, start: 0, end: 20, expect: high}
+      weight: 1.0               # cDNA is diverse -> the biological role is scored, not left at 0
+  excludes: []
+
+backend:
+  module: map/starsolo
+  params:
+    soloType: CB_UMI_Simple
+    soloCBstart: 1
+    soloCBlen: 16
+    soloUMIstart: 17
+    soloUMIlen: 10                        # 10 bp UMI (vs v3's 12) -> 26 bp R1
+    soloCBwhitelist: "{onlist:cb_whitelist}"
+    soloStrand: Forward
+    # 0 disables STARsolo's barcode-read-length check (default 1 FATALs on an over-length barcode
+    # read); CB/UMI still read from the fixed offsets above.
+    soloBarcodeReadLength: 0
+    # soloFeatures is NOT here, and that is the point. It says what to COUNT, and 10x 3' v3.1
+    # chemistry is byte-identical for cells and nuclei — what differs is the RNA population, a
+    # property of SAMPLE PREP. Filing it as chemistry cost a measured 40.7% of a nuclear library.
+    # It lives in the processing manifest now, where a user may instruct it.
+
+# A child of the 10x-3p-gex family. Both former edges (to v3 and its byte-identical twin v3.1) were the
+# OVER-LENGTH-R1 whitelist split among siblings — now declared once, in the parent's
+# `children_decided_by: [onlist]`. So v2 declares no confusable_with of its own.
+parent: 10x-3p-gex
+
+confusable_with: []

seqforge/kb/specs/10x-3p-gex-v3/README.md

@@ -0,0 +1,56 @@
+# 10x Chromium Single Cell 3' Gene Expression v3 (and v3.1)
+
+Droplet single-cell RNA-seq — the current-generation 3' kit. Every droplet holds one gel bead, which
+tags all of a cell's transcripts with the same **cell barcode** and each mRNA molecule with a unique
+**UMI**.
+
+This page covers **both v3 and v3.1**. To a sequencer they are the same library, and seqforge
+processes them identically — see [v3 vs v3.1](#v3-vs-v31) below.
+
+## How it's read
+
+| read | length | what it holds |
+| --- | --- | --- |
+| **R1** | 28 bp | a 16 bp **cell barcode** + a 12 bp **UMI** |
+| **R2** | open-ended | the **cDNA** (the transcript itself), read sense to the mRNA |
+
+The cell barcode is drawn from 10x's `3M-february-2018` list (~6.8 million barcodes). Index reads
+(I1/I2) may or may not be present; seqforge doesn't need them.
+
+Names you'll see in the wild: "10x 3' v3", "Chromium 3' v3", "SC3Pv3", "single cell 3-prime v3",
+"Next GEM 3' v3.1". Papers often write only "10x 3' v3" for a v3.1 run, or name the kit and not the
+version — which changes nothing, as the next section explains.
+
+## v3 vs v3.1
+
+They are **identical to seqforge**: same read layout, same barcode list, same alignment settings. No
+probe can tell them apart from the reads, and none needs to — so seqforge records both names and asks
+you nothing. v3.1 exists as its own knowledge-base entry only so that "these two really are
+identical" is something the test suite re-checks on every build, rather than a claim sitting in a
+comment.
+
+## How seqforge tells it apart from other chemistries
+
+- **v2** — a 16 bp barcode + a **10** bp UMI makes a **26 bp** R1 (vs v3's 28 bp), on a different
+  list. The 2 bp length difference alone separates them.
+- **Multiome (ARC) and GEM-X 3' v4** produce the same 28 bp / 16+12 layout — here **only the barcode
+  list** tells them apart, because each uses a different one. Geometry narrows to a family; the list
+  picks the exact member.
+- **5' kits** share the barcode/UMI geometry but read the cDNA in the opposite direction. The reads
+  can't reveal that, so it takes metadata or a trial alignment, not geometry.
+
+## Gotchas
+
+- **The barcode read can go missing on SRA.** `fasterq-dump` without `--include-technical` drops the
+  28 bp R1; seqforge blocks rather than inventing a barcode read from a filename. Re-fetch with
+  `--include-technical`, or pull the submitter's original files.
+- **A pre-trimmed upload** (R1 no longer a single fixed length) shifts the barcode offsets — seqforge
+  refuses rather than reading the barcode from the wrong place.
+- SRA rewrites read-name headers, so seqforge never trusts them when grouping files into samples.
+
+## References
+
+Read structure cross-checked against
+**[scg_lib_structs — 10x Chromium 3'](https://teichlab.github.io/scg_lib_structs/methods_html/10xChromium3.html)**
+(Teichmann Lab, CC-BY). The exact, machine-readable definition seqforge uses lives in each entry's
+`spec.yaml`.

seqforge/kb/specs/10x-3p-gex-v3/spec.yaml

@@ -0,0 +1,118 @@
+schema_version: 1
+
+identity:
+  id: 10x-3p-gex-v3
+  version: "3"
+  name: "10x Chromium Single Cell 3' Gene Expression v3"
+  aliases: ["10x 3' v3", "Chromium 3' v3", "SC3Pv3", "single cell 3-prime v3"]
+  assay_ontology: ["EFO:0009922"]        # 10x 3' v3 — verified against live EFO (EBI OLS)
+  modality: rna
+
+reads:
+  # R1 = the technical/barcode read. 28 bp = 16 CB + 12 UMI. max_len is null, not 28: an
+  # over-sequenced R1 (e.g. 150 bp, CB+UMI in bp0-28, the rest junk) is a real 10x layout, and the
+  # segment_length over_length_min below is what still keeps 28 separable from v2's 26.
+  - id: R1
+    seqspec_read_id: R1
+    file_hint: "_R1_"
+    strand: pos
+    min_len: 28
+    max_len: null
+    elements:
+      - {type: barcode, name: CB,  start: 0,  end: 16, onlist: cb_whitelist, seqspec_region_type: barcode}
+      - {type: umi,     name: UMI, start: 16, end: 28,                       seqspec_region_type: umi}
+  # R2 = cDNA (open-ended). soloStrand Forward: R2 is sense to mRNA for 3' kits.
+  - id: R2
+    seqspec_read_id: R2
+    file_hint: "_R2_"
+    strand: pos
+    min_len: 25
+    max_len: null
+    elements:
+      - {type: cdna, name: cdna, start: 0, end: null, seqspec_region_type: cdna}
+
+onlists:
+  cb_whitelist:                 # used by backend + a supports test
+    registry: 3M-february-2018  # ~6,794,880 x 16 bp, forward orientation
+    role: cell_barcode
+    expected_orientation: forward
+  arc_v1_probe:                 # probe-only, used ONLY by the exclude anti-gate
+    registry: 737K-arc-v1       # Multiome (ARC) GEX list
+    role: cell_barcode
+    expected_orientation: forward
+
+signature:
+  requires:                     # hard structural gates, rungs 0-2 friendly (NO distinct_ratio, NO onlist)
+    - {test: read_count, roles: 2}
+    # length 28 stays exact for canonical reads; over_length_min 100 admits a full-length
+    # over-sequenced R1 (>=100 bp: the run read length) without loosening 26-vs-28. A shorter
+    # non-canonical read (a 60-94 bp cDNA or split-pool barcode) is below it, so it is still
+    # exact-checked and rejected -> v3 stays un-confusable with cDNA-only chemistries at rungs 0-2.
+    - {test: segment_length, read: R1, length: 28, tolerance: 0, over_length_min: 100}
+    - {test: has_segment, read: R1, start: 0,  end: 16, kind: random}
+    - {test: has_segment, read: R1, start: 16, end: 28, kind: random}
+  supports:                     # additive evidence (rung 3+)
+    - when: {test: onlist_hit_rate, read: R1, start: 0, end: 16, onlist: cb_whitelist, orientation: forward, min: 0.6}
+      weight: 5.0
+    - when: {test: distinct_ratio, read: R1, start: 0,  end: 16, expect: low}
+      weight: 2.0               # CB recurs -> low distinct ratio
+    - when: {test: distinct_ratio, read: R1, start: 16, end: 28, expect: high}
+      weight: 1.0               # UMI ~ unique -> high distinct ratio
+    - when: {test: distinct_ratio, read: R2, start: 0, end: 20, expect: high}
+      weight: 1.0               # cDNA is diverse -> the biological role is scored, not left at 0
+    - when: {test: header_index, present: true}
+      weight: 0.2
+  excludes:                     # anti-gate: if the Multiome list hits, it's not 3' GEX
+    - {test: onlist_hit_rate, read: R1, start: 0, end: 16, onlist: arc_v1_probe, orientation: forward, min: 0.6}
+
+backend:
+  module: map/starsolo
+  params:                       # chemistry-defining MINIMUM (CellRanger-parity knobs come from processing policy)
+    soloType: CB_UMI_Simple
+    soloCBstart: 1
+    soloCBlen: 16
+    soloUMIstart: 17
+    soloUMIlen: 12
+    soloCBwhitelist: "{onlist:cb_whitelist}"
+    soloStrand: Forward
+    # 0 disables STARsolo's barcode-read-length check, which by default (1) FATALs when the barcode
+    # read is longer than CB+UMI. An over-sequenced R1 (150 bp) needs this; CB/UMI are still read from
+    # the fixed offsets above. Kept identical in v3/v3.1 so `backend_identical` holds.
+    soloBarcodeReadLength: 0
+    # soloFeatures is NOT here, and that is the point. It says what to COUNT, and 10x 3' v3.1
+    # chemistry is byte-identical for cells and nuclei — what differs is the RNA population, a
+    # property of SAMPLE PREP. Filing it as chemistry cost a measured 40.7% of a nuclear library.
+    # It lives in the processing manifest now, where a user may instruct it.
+
+# A child of the 10x-3p-gex family. The v2 sibling edge (over-length whitelist split) now lives in the
+# parent's `children_decided_by: [onlist]`, so it is deleted here — the tree declares it once.
+parent: 10x-3p-gex
+
+confusable_with:
+  - id: 10x-3p-gex-v3.1
+    relationship: processing_equivalent
+    distinguishable_by: [none]
+    note: >
+      Identical 16+12=28 bp geometry, identical 3M-february-2018 whitelist, byte-identical STARsolo
+      params -> §12 benign: the resolver records both ids and asks 0 questions. KEPT as an explicit
+      edge (not collapsed into the parent): backend-identity is a byte fact the §2.4 biconditional
+      verifies pairwise, distinct from the divergent sibling relationship the tree carries.
+  - id: 10x-multiome-gex
+    relationship: processing_divergent
+    distinguishable_by: [onlist]
+    note: >
+      Same 28 bp geometry, but Multiome (ARC) GEX uses 737K-arc-v1, not 3M-february-2018. Rung-3
+      onlist check separates them; backend params differ only in soloCBwhitelist.
+  - id: 10x-gemx-3p-v4
+    relationship: processing_divergent
+    distinguishable_by: [onlist]
+    note: >
+      REQUIRED declaration: GEM-X 3' v4 shares the 28 bp / 16+12 geometry and is separable only by
+      its newer whitelist. Without this entry the flagship fails the CI under-declaration check.
+  - id: 10x-5p-gex
+    relationship: processing_divergent
+    distinguishable_by: [metadata, alignment]
+    note: >
+      5' chemistry reads antisense cDNA -> soloStrand Reverse. Read-undecidable when geometry and
+      whitelist coincide; metadata (rung 0) or alignment (rung 6) resolves it.
+

seqforge/kb/specs/10x-3p-gex-v3.1/README.md

@@ -0,0 +1,56 @@
+# 10x Chromium Single Cell 3' Gene Expression v3 (and v3.1)
+
+Droplet single-cell RNA-seq — the current-generation 3' kit. Every droplet holds one gel bead, which
+tags all of a cell's transcripts with the same **cell barcode** and each mRNA molecule with a unique
+**UMI**.
+
+This page covers **both v3 and v3.1**. To a sequencer they are the same library, and seqforge
+processes them identically — see [v3 vs v3.1](#v3-vs-v31) below.
+
+## How it's read
+
+| read | length | what it holds |
+| --- | --- | --- |
+| **R1** | 28 bp | a 16 bp **cell barcode** + a 12 bp **UMI** |
+| **R2** | open-ended | the **cDNA** (the transcript itself), read sense to the mRNA |
+
+The cell barcode is drawn from 10x's `3M-february-2018` list (~6.8 million barcodes). Index reads
+(I1/I2) may or may not be present; seqforge doesn't need them.
+
+Names you'll see in the wild: "10x 3' v3", "Chromium 3' v3", "SC3Pv3", "single cell 3-prime v3",
+"Next GEM 3' v3.1". Papers often write only "10x 3' v3" for a v3.1 run, or name the kit and not the
+version — which changes nothing, as the next section explains.
+
+## v3 vs v3.1
+
+They are **identical to seqforge**: same read layout, same barcode list, same alignment settings. No
+probe can tell them apart from the reads, and none needs to — so seqforge records both names and asks
+you nothing. v3.1 exists as its own knowledge-base entry only so that "these two really are
+identical" is something the test suite re-checks on every build, rather than a claim sitting in a
+comment.
+
+## How seqforge tells it apart from other chemistries
+
+- **v2** — a 16 bp barcode + a **10** bp UMI makes a **26 bp** R1 (vs v3's 28 bp), on a different
+  list. The 2 bp length difference alone separates them.
+- **Multiome (ARC) and GEM-X 3' v4** produce the same 28 bp / 16+12 layout — here **only the barcode
+  list** tells them apart, because each uses a different one. Geometry narrows to a family; the list
+  picks the exact member.
+- **5' kits** share the barcode/UMI geometry but read the cDNA in the opposite direction. The reads
+  can't reveal that, so it takes metadata or a trial alignment, not geometry.
+
+## Gotchas
+
+- **The barcode read can go missing on SRA.** `fasterq-dump` without `--include-technical` drops the
+  28 bp R1; seqforge blocks rather than inventing a barcode read from a filename. Re-fetch with
+  `--include-technical`, or pull the submitter's original files.
+- **A pre-trimmed upload** (R1 no longer a single fixed length) shifts the barcode offsets — seqforge
+  refuses rather than reading the barcode from the wrong place.
+- SRA rewrites read-name headers, so seqforge never trusts them when grouping files into samples.
+
+## References
+
+Read structure cross-checked against
+**[scg_lib_structs — 10x Chromium 3'](https://teichlab.github.io/scg_lib_structs/methods_html/10xChromium3.html)**
+(Teichmann Lab, CC-BY). The exact, machine-readable definition seqforge uses lives in each entry's
+`spec.yaml`.

seqforge/kb/specs/10x-3p-gex-v3.1/spec.yaml

@@ -0,0 +1,124 @@
+schema_version: 1
+
+# The §12 benign twin of 10x-3p-gex-v3, and the ONLY reason it is a separate file: `backend_identical`
+# is a computed predicate, and a predicate cannot be computed about a spec that does not exist. v3
+# declared `processing_equivalent: 10x-3p-gex-v3.1` from the start, but the twin was never written, so
+# the flagship example of the rule the whole resolver is built around was the one pair CI could not
+# check. Everything below except `identity` is byte-for-byte v3 — that IS the assertion.
+#
+# Do not "simplify" this by generating it from v3 at load time. The point is that two independently
+# authored specs are compared and found identical; deriving one from the other would make
+# `backend_identical(v3, v3.1)` true by construction and prove nothing.
+
+identity:
+  id: 10x-3p-gex-v3.1
+  version: "3.1"
+  name: "10x Chromium Single Cell 3' Gene Expression v3.1"
+  aliases: ["10x 3' v3.1", "Chromium 3' v3.1", "SC3Pv3.1", "single cell 3-prime v3.1", "Next GEM 3' v3.1"]
+  assay_ontology: ["EFO:0022980"]        # 10x 3' v3.1 — verified against live EFO (EBI OLS), FLAG-1
+  modality: rna
+
+reads:
+  # Identical to v3: 28 bp = 16 CB + 12 UMI (max_len null: an over-sequenced R1 is still v3.1). This
+  # identity is the whole point — the probe cannot separate v3 from v3.1, and §12 says it does not
+  # need to; the over_length_min below keeps 28 separable from v2's 26 either way.
+  - id: R1
+    seqspec_read_id: R1
+    file_hint: "_R1_"
+    strand: pos
+    min_len: 28
+    max_len: null
+    elements:
+      - {type: barcode, name: CB,  start: 0,  end: 16, onlist: cb_whitelist, seqspec_region_type: barcode}
+      - {type: umi,     name: UMI, start: 16, end: 28,                       seqspec_region_type: umi}
+  - id: R2
+    seqspec_read_id: R2
+    file_hint: "_R2_"
+    strand: pos
+    min_len: 25
+    max_len: null
+    elements:
+      - {type: cdna, name: cdna, start: 0, end: null, seqspec_region_type: cdna}
+
+onlists:
+  cb_whitelist:                 # the SAME list as v3 — this is why no onlist check can separate them
+    registry: 3M-february-2018  # ~6,794,880 x 16 bp, forward orientation
+    role: cell_barcode
+    expected_orientation: forward
+  arc_v1_probe:                 # probe-only, used ONLY by the exclude anti-gate
+    registry: 737K-arc-v1       # Multiome (ARC) GEX list
+    role: cell_barcode
+    expected_orientation: forward
+
+signature:
+  requires:
+    - {test: read_count, roles: 2}
+    # length 28 exact for canonical reads; over_length_min 100 admits a full-length over-sequenced
+    # R1 (>=100 bp) while a 60-94 bp cDNA/split-pool read stays exact-checked and rejected (see v3).
+    - {test: segment_length, read: R1, length: 28, tolerance: 0, over_length_min: 100}
+    - {test: has_segment, read: R1, start: 0,  end: 16, kind: random}
+    - {test: has_segment, read: R1, start: 16, end: 28, kind: random}
+  supports:
+    - when: {test: onlist_hit_rate, read: R1, start: 0, end: 16, onlist: cb_whitelist, orientation: forward, min: 0.6}
+      weight: 5.0
+    - when: {test: distinct_ratio, read: R1, start: 0,  end: 16, expect: low}
+      weight: 2.0
+    - when: {test: distinct_ratio, read: R1, start: 16, end: 28, expect: high}
+      weight: 1.0
+    - when: {test: distinct_ratio, read: R2, start: 0, end: 20, expect: high}
+      weight: 1.0
+    - when: {test: header_index, present: true}
+      weight: 0.2
+  excludes:
+    - {test: onlist_hit_rate, read: R1, start: 0, end: 16, onlist: arc_v1_probe, orientation: forward, min: 0.6}
+
+backend:
+  module: map/starsolo
+  params:                       # byte-identical to v3 -> backend_identical -> §12 benign
+    soloType: CB_UMI_Simple
+    soloCBstart: 1
+    soloCBlen: 16
+    soloUMIstart: 17
+    soloUMIlen: 12
+    soloCBwhitelist: "{onlist:cb_whitelist}"
+    soloStrand: Forward
+    # 0 disables STARsolo's barcode-read-length check (default 1 FATALs on an over-length barcode
+    # read); byte-identical to v3's, which is what keeps `backend_identical` true.
+    soloBarcodeReadLength: 0
+    # soloFeatures is NOT here, and that is the point. It says what to COUNT, and 10x 3' v3.1
+    # chemistry is byte-identical for cells and nuclei — what differs is the RNA population, a
+    # property of SAMPLE PREP. Filing it as chemistry cost a measured 40.7% of a nuclear library.
+    # It lives in the processing manifest now, where a user may instruct it.
+
+# A child of the 10x-3p-gex family; the v2 sibling edge now lives in the parent's children_decided_by.
+parent: 10x-3p-gex
+
+confusable_with:
+  - id: 10x-3p-gex-v3
+    relationship: processing_equivalent
+    distinguishable_by: [none]
+    note: >
+      The back-edge of v3's declaration. Identical 16+12=28 bp geometry, identical 3M-february-2018
+      whitelist, byte-identical STARsolo params -> §12 benign: the resolver records both ids and asks
+      0 questions. Declared on both sides so the relation reads as symmetric in the file, which is
+      what a human checks; the CI biconditional takes the union of both directions regardless.
+  - id: 10x-multiome-gex
+    relationship: processing_divergent
+    distinguishable_by: [onlist]
+    note: >
+      Same 28 bp geometry, but Multiome (ARC) GEX uses 737K-arc-v1, not 3M-february-2018. Rung-3
+      onlist check separates them; backend params differ only in soloCBwhitelist.
+  - id: 10x-gemx-3p-v4
+    relationship: processing_divergent
+    distinguishable_by: [onlist]
+    note: >
+      REQUIRED declaration: GEM-X 3' v4 shares the 28 bp / 16+12 geometry and is separable only by
+      its newer whitelist. v3.1 inherits every one of v3's divergent confusables — it is the same
+      chemistry to the probe, so it is confusable with exactly the same things.
+  - id: 10x-5p-gex
+    relationship: processing_divergent
+    distinguishable_by: [metadata, alignment]
+    note: >
+      5' chemistry reads antisense cDNA -> soloStrand Reverse. Read-undecidable when geometry and
+      whitelist coincide; metadata (rung 0) or alignment (rung 6) resolves it.
+

seqforge/kb/specs/bd-rhapsody-wta/README.md

@@ -0,0 +1,103 @@
+# BD Rhapsody WTA (Whole Transcriptome Analysis)
+
+BD Biosciences' droplet-free single-cell 3' RNA-seq. Cells are captured in a microwell plate and
+tagged with a **cell label** built from three barcode blocks on the capture bead, plus a **UMI** on
+each molecule.
+
+BD ships this chemistry in two bead generations, and seqforge recognizes and compiles **both**
+automatically, from the reads. The **original fixed-position bead** is described first; the 2022
+**[Enhanced bead](#enhanced-beads-2022)** — with its variable-length diversity insert — is described
+below. seqforge tells the two apart from the bytes (their linker structure differs), so you never have
+to declare which bead a dataset used.
+
+## How it's read
+
+Two reads:
+
+- **R2 = the cDNA** (the transcript), read sense to the mRNA.
+- **R1 = the bead read**: three 9 bp cell-label blocks separated by two fixed linker sequences, then
+  an 8 bp UMI.
+
+| segment on R1 | length | position |
+| --- | --- | --- |
+| cell label 1 | 9 bp | 0–9 |
+| linker 1 (`ACTGGCCTGCGA`) | 12 bp | 9–21 |
+| cell label 2 | 9 bp | 21–30 |
+| linker 2 (`GGTAGCGGTGACA`) | 13 bp | 30–43 |
+| cell label 3 | 9 bp | 43–52 |
+| UMI | 8 bp | 52–60 |
+
+Each cell-label block is drawn from its own published list of **97** 9-mers, so there are 97³ ≈
+913,000 possible cell labels. R1 is often sequenced past position 60 into poly(T)/cDNA; those extra
+bases are ignored.
+
+## How seqforge tells it apart
+
+The **two fixed linker sequences at known positions** are the signature — no other supported
+chemistry has them. Each cell-label block also matches its own barcode list, which both confirms the
+call and separates BD Rhapsody from a plain bulk paired-end library (bulk has no barcode list to
+match).
+
+## Strand
+
+The bead's capture oligo ends in poly(dT), which primes off the mRNA poly(A) tail, so R2 reads the
+cDNA **sense** to the transcript — a standard 3' poly-dT library, like 10x 3'. Getting this backwards
+would leave most reads uncounted while the aligner still exits cleanly, so seqforge derives it from
+the bead chemistry rather than guessing.
+
+## Enhanced beads (2022)
+
+In 2022 BD introduced **Enhanced Cell Capture Beads**, the current chemistry. The cell labels work the
+same way — three 9 bp blocks read off the bead — but two things change:
+
+- A short **diversity insert** of 0–3 bp (one of *nothing*, `A`, `GT`, or `TCA`) is added at the very
+  start of Read 1, to stagger the reads and cut the amount of PhiX needed.
+- The two linkers shrink to **`GTGA`** and **`GACA`** (4 bp each), from v1's 12 and 13 bp.
+
+So Enhanced Read 1 reads:
+
+```text
+[0–3 bp insert] [CLS1 · 9] GTGA [CLS2 · 9] GACA [CLS3 · 9] [UMI · 8]
+```
+
+There are two sub-versions, differing only in the cell-label lists: **96** or **384** sequences per
+block (the 384-list "Enhanced v2" allows more cell labels). The read layout is otherwise identical.
+
+### How seqforge handles the Enhanced bead
+
+seqforge recognizes and compiles the Enhanced bead **automatically** — you do not tell it the bead
+generation, and you do not pre-trim the diversity insert.
+
+- **Recognition.** The diversity insert shifts every barcode by a different amount from one read to the
+  next, so the positions are not fixed. seqforge finds the `GTGA…GACA` linker frame in each read
+  (tolerating the 0–3 bp stagger and sequencing error), then reads the cell-label and UMI blocks
+  relative to it. The presence of that frame is what separates Enhanced from the original bead, whose
+  longer `ACTGGCCTGCGA`/`GGTAGCGGTGACA` linkers sit at fixed positions instead.
+- **96 vs 384.** The two Enhanced sub-versions have identical read layout and differ only in which
+  cell-label list their blocks match, so seqforge picks the one the barcodes actually hit — exactly how
+  it tells 10x v2 from v3. The 96-plex bead reuses the original bead's cell-label lists; the 384-plex
+  lists ship with seqforge too.
+- **Compilation.** seqforge maps Enhanced reads with STARsolo's adapter anchor — no pre-trimming — and
+  derives the exact settings STAR's author endorsed in
+  [issue #1607](https://github.com/alexdobin/STAR/issues/1607) straight from the read layout:
+
+  ```bash
+  STAR --soloType CB_UMI_Complex \
+       --soloAdapterSequence NNNNNNNNNGTGANNNNNNNNNGACA \
+       --soloCBposition 2_0_2_8 2_13_2_21 3_1_3_9 \
+       --soloUMIposition 3_10_3_17 \
+       --soloCBwhitelist BD_CLS1.txt BD_CLS2.txt BD_CLS3.txt
+  ```
+
+  The adapter `NNNNNNNNNGTGANNNNNNNNNGACA` is `CLS1(9) + GTGA + CLS2(9) + GACA`; STARsolo finds it in
+  each read and reads the barcodes relative to it, so the variable insert at the front takes care of
+  itself. For a reproducible reference workflow spanning every bead generation, see
+  **[rhapsodist](https://github.com/imallona/rhapsodist)**.
+
+## References
+
+Read structure, linker sequences, and barcode lists pinned from
+**[scg_lib_structs — BD Rhapsody](https://teichlab.github.io/scg_lib_structs/methods_html/BD_Rhapsody.html)**
+(Teichmann Lab, CC-BY), cross-checked against the seqspec `bd_rhapsody_v1` example and the STARsolo
+maintainer's endorsed settings. The exact, machine-readable definition seqforge uses lives in this
+entry's `spec.yaml`.