seqforge 2026.7.1__py3-none-any.whl

seqforge/kb/specs/bd-rhapsody-wta/spec.yaml

@@ -0,0 +1,130 @@
+schema_version: 1
+
+# ============================================================================================
+# BD RHAPSODY WTA (Whole Transcriptome Analysis) — the ORIGINAL fixed-offset cell-label bead.
+#
+# Read structure, linkers, whitelists and strand pinned from primary sources (never memory):
+#   - scg_lib_structs (CC-BY): https://teichlab.github.io/scg_lib_structs/methods_html/BD_Rhapsody.html
+#   - seqspec assay example:   docs/examples/assays/bd_rhapsody_v1.spec.yaml (pachterlab/seqspec)
+#   - STARsolo maintainer-endorsed position string: github.com/alexdobin/STAR/issues/1111, #1607
+#   - EFO term verified live on EBI OLS4.
+#
+# Read 1 (the BEAD read), 5'->3'  [structural length 60 bp; R1 is sequenced longer, into poly(T)/cDNA]:
+#   [CLS1 9bp][linker1 12bp][CLS2 9bp][linker2 13bp][CLS3 9bp][UMI 8bp]
+#     offsets: CLS1 [0,9)  linker1 [9,21)  CLS2 [21,30)  linker2 [30,43)  CLS3 [43,52)  UMI [52,60)
+# Read 2 = the cDNA read (top strand as template — sense to the mRNA, see soloStrand).
+# The three cell-label sets (CLS1/CLS2/CLS3) are 97 x 9 bp EACH (BD publishes 97 per pool, not 96 —
+# verified by downloading the shipped lists; see README). soloCBwhitelist order == CB-position order.
+#
+# THE VARIANT DISCRIMINATOR (the thing most likely to be silently mismatched): this entry is the
+# ORIGINAL cell-label bead, whose CLS/UMI sit at FIXED offsets. The 2022 "Enhanced" bead prepends a
+# VARIABLE-length diversity insert (0-3 bp) before CLS1 and shortens both linkers to 4 bp
+# (GTGA / GACA) — that shifts every downstream offset and is NOT a fixed CB_UMI_Complex. seqforge
+# models fixed-offset elements only, so the Enhanced bead needs anchored-element support first and is
+# deliberately OUT OF SCOPE here — a separate future entry, never conflated with this one.
+# ============================================================================================
+
+identity:
+  id: bd-rhapsody-wta
+  version: v1-cell-label                 # the original fixed-offset bead (NOT the Enhanced variable bead)
+  name: "BD Rhapsody WTA (3' whole-transcriptome, original cell-label bead)"
+  aliases: ["BD Rhapsody", "Rhapsody", "BD Rhapsody WTA", "BD Rhapsody Whole Transcriptome Analysis",
+            "Rhapsody WTA", "BD Rhapsody Single-Cell"]
+  assay_ontology: ["EFO:0700003"]        # "BD Rhapsody Whole Transcriptome Analysis" — verified via
+                                         # EBI OLS4 (obo_id=EFO:0700003). NB EFO:0700004 is the
+                                         # Targeted-mRNA panel, a different assay — never this one.
+  modality: rna
+
+reads:
+  # Read 2 (cDNA). BD/STARsolo pass cDNA first (--readFilesIn R2 R1); the role is decided by the
+  # elements here, not by the read id, so declaring cdna on R2 is all that is needed.
+  - id: cdna
+    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}
+  # Read 1 (the bead read): three fixed 9 bp cell-label blocks split by two fixed linkers, then an
+  # 8 bp UMI. `max_len: null` because R1 is over-sequenced past byte 60 into poly(T)/cDNA — CB/UMI are
+  # read from their fixed offsets and the tail is ignored (the two constant linkers are the signature,
+  # so no segment_length gate is needed to stay separable).
+  - id: bc
+    seqspec_read_id: R1
+    file_hint: "_R1_"
+    strand: pos
+    min_len: 60
+    max_len: null
+    elements:
+      - {type: barcode, name: cls1, start: 0,  end: 9,  onlist: cls1, seqspec_region_type: barcode}
+      # linker1 = the CLS1->CLS2 spacer (verbatim from scg_lib_structs / seqspec bd_rhapsody_v1)
+      - {type: linker,  name: linker1, start: 9, end: 21, seqspec_region_type: linker,
+         sequence: "ACTGGCCTGCGA"}
+      - {type: barcode, name: cls2, start: 21, end: 30, onlist: cls2, seqspec_region_type: barcode}
+      # linker2 = the CLS2->CLS3 spacer (verbatim from scg_lib_structs / seqspec bd_rhapsody_v1)
+      - {type: linker,  name: linker2, start: 30, end: 43, seqspec_region_type: linker,
+         sequence: "GGTAGCGGTGACA"}
+      - {type: barcode, name: cls3, start: 43, end: 52, onlist: cls3, seqspec_region_type: barcode}
+      - {type: umi,     name: UMI, start: 52, end: 60, seqspec_region_type: umi}
+
+onlists:
+  cls1: {registry: bd-rhapsody-cls1, role: cell_barcode, expected_orientation: forward}  # 97 x 9 bp
+  cls2: {registry: bd-rhapsody-cls2, role: cell_barcode, expected_orientation: forward}
+  cls3: {registry: bd-rhapsody-cls3, role: cell_barcode, expected_orientation: forward}
+  tenx_probe: {registry: 3M-february-2018, role: cell_barcode, expected_orientation: forward}  # exclude only
+
+signature:
+  requires:                              # the two FIXED linkers are the structural signature
+    - {test: read_count, roles: 2}
+    - {test: has_segment, read: bc, start: 9,  end: 21, kind: constant}   # linker1 (12 bp)
+    - {test: has_segment, read: bc, start: 30, end: 43, kind: constant}   # linker2 (13 bp)
+  supports:                              # each CLS block hits its own 97 x 9 bp whitelist
+    - when: {test: onlist_hit_rate, read: bc, element: cls1, onlist: cls1, orientation: forward, min: 0.5}
+      weight: 3.0
+    - when: {test: onlist_hit_rate, read: bc, element: cls2, onlist: cls2, orientation: forward, min: 0.5}
+      weight: 3.0
+    - when: {test: onlist_hit_rate, read: bc, element: cls3, onlist: cls3, orientation: forward, min: 0.5}
+      weight: 3.0
+    - when: {test: distinct_ratio, read: bc, start: 52, end: 60, expect: high}   # UMI ~unique
+      weight: 1.0
+    - when: {test: distinct_ratio, read: cdna, start: 0, end: 20, expect: high}  # cDNA role is scored too
+      weight: 1.0
+  excludes:                              # a 16 bp 10x CB at read start => not BD Rhapsody
+    - {test: onlist_hit_rate, read: bc, start: 0, end: 16, onlist: tenx_probe, orientation: forward, min: 0.6}
+
+backend:
+  module: map/starsolo
+  params:
+    soloType: CB_UMI_Complex
+    soloCBwhitelist: ["{onlist:cls1}", "{onlist:cls2}", "{onlist:cls3}"]   # order == CB-position order
+    # soloStrand: DERIVED, not pattern-matched (a wrong strand leaves most reads unassigned while
+    # STARsolo exits 0 and emits a matrix that merely looks thin — neither gate can catch it).
+    # DERIVATION: the bead oligo terminates in (dT)18 at its 3' end; that poly(dT) primes reverse
+    # transcription off the mRNA poly(A) tail, so R2 sequences the cDNA in the SAME orientation as the
+    # original mRNA — a standard 3' poly-dT capture library, exactly like 10x Chromium 3'. STARsolo
+    # defines Forward as "read strand same as the original RNA molecule" -> Forward (also its default).
+    # CORROBORATION: a full working BD Rhapsody STARsolo command sets --soloStrand Forward
+    # (github.com/alexdobin/STAR/issues/1607), and scg_lib_structs runs BD with STARsolo's Forward
+    # default. No source claims Reverse.
+    soloStrand: Forward
+    # soloCBposition / soloUMIposition are DERIVED from the element coordinates at compose time
+    # (compose/params.py::derived_params) -> "0_0_0_8 0_21_0_29 0_43_0_51" and UMI "0_52_0_59", with
+    # soloUMIlen 8. That quadruple set is byte-identical to the maintainer-endorsed STARsolo string
+    # on issue #1111, which is an independent cross-check on the geometry above. Never hand-enter it.
+    # soloFeatures is NOT here: it says what to COUNT (cells vs nuclei is sample prep, not chemistry),
+    # and lives in the processing manifest where a user may instruct it.
+
+# The combinatorial CLS geometry + the two fixed linkers separate this from 10x / SPLiT-seq (different
+# linker sequences and positions). What it does NOT separate itself from is the generic paired-end
+# fallback, which forbids so little it accepts these two files at rungs 0-2 — the confusion runs in
+# that direction, the relation is symmetric, so it is declared on both sides (see bulk-rnaseq-pe).
+confusable_with:
+  - id: bulk-rnaseq-pe
+    relationship: processing_divergent
+    distinguishable_by: [onlist]
+    note: >
+      The generic paired-end fallback accepts cdna+bc on geometry alone. Rung 3 decides it: the three
+      CLS whitelists hit, and bulk has no whitelist to hit. Maximally divergent downstream
+      (map/starsolo with three cell-label rounds vs map/star with none), so a silent preference would
+      emit a bulk gene-count matrix for a single-cell library and exit 0.

seqforge/kb/specs/bd-rhapsody-wta-enhanced/spec.yaml

@@ -0,0 +1,99 @@
+schema_version: 1
+
+# ============================================================================================
+# BD RHAPSODY WTA — ENHANCED CELL CAPTURE BEAD (2022, "v2.0"): the ABSTRACT FAMILY NODE.
+#
+# The Enhanced bead prepends a VARIABLE-LENGTH 0-3 bp diversity insert to Read 1, so every cell-label
+# block downstream STAGGERS per read — the fixed-offset original bead (`bd-rhapsody-wta`) cannot express
+# this. Read 1 (5'->3'):
+#     [VB 0-3bp][CLS1 9][GTGA][CLS2 9][GACA][CLS3 9][UMI 8](dT)...   (R1 over-sequenced into poly(T))
+# The two 4 bp linkers GTGA / GACA (vs the original bead's 12/13 bp linkers) at their staggered
+# positions are the byte signature. It recognises the bead by phase-locking that GTGA...GACA frame
+# (`motif_present`, tolerant of the 0-3 bp stagger + 2 substitutions), exactly as rhapsodist does by
+# Hamming-matching the linkers across a range(4) offset scan (workflow/src/workflow_functions.py).
+#
+# This node is a FAMILY, not a runnable chemistry: the two Enhanced sub-versions differ ONLY in
+# whitelist size (96 vs 384 sequences per block) — an ONLIST-decided split, exactly like 10x v2/v3 — so
+# there is no single recipe here. Descent resolves to a leaf:
+#     bd-rhapsody-wta-enhanced-v1   (97 x 3 cell-label lists, == the original bead's lists)
+#     bd-rhapsody-wta-enhanced-v2   (384 x 3 cell-label lists)
+# It is NEVER scored as a candidate (the scorer skips backend-less nodes) and self-tests by RECOGNITION
+# (test_a_family_node_recognizes_its_children_and_no_one_else), not `kb roundtrip`.
+#
+# Sources (never memory): read structure + linkers from the BD Rhapsody Enhanced v2.0 protocol and
+# rhapsodist (imallona/rhapsodist, Moro & Mallona 2025); STARsolo adapter-anchor recipe endorsed by
+# @alexdobin on github.com/alexdobin/STAR/issues/1607.
+# ============================================================================================
+
+identity:
+  id: bd-rhapsody-wta-enhanced
+  version: enhanced-family
+  name: "BD Rhapsody WTA — Enhanced Cell Capture Bead (family)"
+  aliases: ["BD Rhapsody Enhanced", "Rhapsody Enhanced", "BD Rhapsody Enhanced Beads",
+            "BD Enhanced Cell Capture Beads", "BD Rhapsody WTA Enhanced"]
+  assay_ontology: ["EFO:0700003"]        # BD Rhapsody WTA — the assay the whole family instantiates
+  modality: rna
+
+node_kind: family
+# The children (96 / 384) share the byte-identical Enhanced geometry and are told apart ONLY by which
+# cell-label whitelist their CLS blocks hit — the two pools are DISJOINT (0 shared 9-mers), so the
+# onlist separates them cleanly at rung 3, exactly the v2/v3 pattern.
+children_decided_by: [onlist]
+
+reads:
+  # Read 2 = the cDNA (open-ended, sense to the mRNA — 3' poly-dT capture, like the original bead).
+  - id: cdna
+    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}
+  # Read 1 = the bead read. The leading `vb` diversity insert is variable-length (0-3 bp); every element
+  # after it is ANCHORED to the previous one (a sequential chain), so the whole cell label FLOATS by the
+  # per-read insert length. The resolver phase-locks the frame on the GTGA/GACA linkers. `max_len: null`
+  # because R1 is over-sequenced past the ~43 bp structure into poly(T)/cDNA. The family's CLS blocks
+  # carry NO onlist — which whitelist they hit is exactly what descent decides.
+  - id: bc
+    seqspec_read_id: R1
+    file_hint: "_R1_"
+    strand: pos
+    min_len: 43
+    max_len: null
+    elements:
+      - {type: diversity, name: vb, min_len: 0, max_len: 3, seqspec_region_type: linker}
+      - {type: barcode, name: cls1, min_len: 9, max_len: 9, seqspec_region_type: barcode,
+         anchor: {relative_to: element, ref_element: vb, ref_side: end, offset: 0}}
+      - {type: linker, name: linker1, sequence: "GTGA", seqspec_region_type: linker,
+         anchor: {relative_to: element, ref_element: cls1, ref_side: end, offset: 0, max_mismatch: 1}}
+      - {type: barcode, name: cls2, min_len: 9, max_len: 9, seqspec_region_type: barcode,
+         anchor: {relative_to: element, ref_element: linker1, ref_side: end, offset: 0}}
+      - {type: linker, name: linker2, sequence: "GACA", seqspec_region_type: linker,
+         anchor: {relative_to: element, ref_element: cls2, ref_side: end, offset: 0, max_mismatch: 1}}
+      - {type: barcode, name: cls3, min_len: 9, max_len: 9, seqspec_region_type: barcode,
+         anchor: {relative_to: element, ref_element: linker2, ref_side: end, offset: 0}}
+      - {type: umi, name: UMI, min_len: 8, max_len: 8, seqspec_region_type: umi,
+         anchor: {relative_to: element, ref_element: cls3, ref_side: end, offset: 0}}
+
+onlists: {}
+
+signature:
+  # Coarse recognition only — enough to admit either Enhanced child at rungs 0-2 and reject everything
+  # else (the original fixed bead, 10x, bulk). The GTGA...GACA composite is the structural signature:
+  # `GTGANNNNNNNNNGACA` = GTGA + CLS2(9N) + GACA, searched across the 0-3 bp insert stagger (start
+  # positions 8-13), tolerating 2 substitutions. NO onlist here (that is the children's job).
+  requires:
+    - {test: read_count, roles: 2}
+    - {test: motif_present, read: bc, motif: "GTGANNNNNNNNNGACA", where: window,
+       search_start: 8, search_end: 13, max_mismatch: 2, min_rate: 0.5}
+  supports:
+    # the cell label recurs (low distinct-ratio, resolved at the anchored frame); UMI ~unique; cDNA diverse
+    - {when: {test: distinct_ratio, read: bc, element: cls1, expect: low}, weight: 2.0}
+    - {when: {test: distinct_ratio, read: bc, element: UMI, expect: high}, weight: 1.0}
+    - {when: {test: distinct_ratio, read: cdna, start: 0, end: 20, expect: high}, weight: 1.0}
+  excludes: []
+
+# no backend: abstract classifier. no parent: a root family (distinct from the original-bead root
+# `bd-rhapsody-wta` — the two beads are byte-separable by their linker structure, so they are not kin).
+confusable_with: []

seqforge/kb/specs/bd-rhapsody-wta-enhanced-v1/spec.yaml

@@ -0,0 +1,93 @@
+schema_version: 1
+
+# ============================================================================================
+# BD RHAPSODY WTA — ENHANCED bead v1, 96(/97) x 3 cell-label lists (rhapsodist class `enhanced`).
+#
+# A leaf of `bd-rhapsody-wta-enhanced`. "v1" is the FIRST Enhanced generation (96-plex), as against the
+# `-v2` sibling (384-plex) — not the original fixed-offset bead, which is `bd-rhapsody-wta`. Byte-
+# identical Enhanced geometry (0-3 bp diversity insert + GTGA/GACA linkers); what makes it THIS leaf is
+# that its three CLS blocks hit the ORIGINAL 97 x 9 bp cell-label pools — the very same
+# `bd-rhapsody-cls1/2/3` whitelists the original fixed-offset bead uses (verified: the shipped lists are
+# byte-identical to rhapsodist's whitelist_96x3, 97 entries each). The `-v2` sibling uses the disjoint
+# 384 x 3 pools; the two share 0 barcodes, so the onlist decides.
+#
+# The layout (reads/elements) is inherited verbatim from the family and is what the round-trip and the
+# adapter-anchored `compose` derivation read; see the family node for the annotated read structure.
+# ============================================================================================
+
+identity:
+  id: bd-rhapsody-wta-enhanced-v1
+  version: enhanced-v1
+  name: "BD Rhapsody WTA — Enhanced bead v1 (96-plex cell labels)"
+  aliases: ["BD Rhapsody Enhanced 96", "Rhapsody Enhanced 96x3", "BD Rhapsody Enhanced v1"]
+  assay_ontology: ["EFO:0700003"]
+  modality: rna
+
+parent: bd-rhapsody-wta-enhanced
+
+reads:
+  - id: cdna
+    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}
+  - id: bc
+    seqspec_read_id: R1
+    file_hint: "_R1_"
+    strand: pos
+    min_len: 43
+    max_len: null
+    elements:
+      - {type: diversity, name: vb, min_len: 0, max_len: 3, seqspec_region_type: linker}
+      - {type: barcode, name: cls1, min_len: 9, max_len: 9, onlist: cls1, seqspec_region_type: barcode,
+         anchor: {relative_to: element, ref_element: vb, ref_side: end, offset: 0}}
+      - {type: linker, name: linker1, sequence: "GTGA", seqspec_region_type: linker,
+         anchor: {relative_to: element, ref_element: cls1, ref_side: end, offset: 0, max_mismatch: 1}}
+      - {type: barcode, name: cls2, min_len: 9, max_len: 9, onlist: cls2, seqspec_region_type: barcode,
+         anchor: {relative_to: element, ref_element: linker1, ref_side: end, offset: 0}}
+      - {type: linker, name: linker2, sequence: "GACA", seqspec_region_type: linker,
+         anchor: {relative_to: element, ref_element: cls2, ref_side: end, offset: 0, max_mismatch: 1}}
+      - {type: barcode, name: cls3, min_len: 9, max_len: 9, onlist: cls3, seqspec_region_type: barcode,
+         anchor: {relative_to: element, ref_element: linker2, ref_side: end, offset: 0}}
+      - {type: umi, name: UMI, min_len: 8, max_len: 8, seqspec_region_type: umi,
+         anchor: {relative_to: element, ref_element: cls3, ref_side: end, offset: 0}}
+
+onlists:
+  cls1: {registry: bd-rhapsody-cls1, role: cell_barcode, expected_orientation: forward}  # 97 x 9 bp
+  cls2: {registry: bd-rhapsody-cls2, role: cell_barcode, expected_orientation: forward}
+  cls3: {registry: bd-rhapsody-cls3, role: cell_barcode, expected_orientation: forward}
+
+signature:
+  requires:                              # the GTGA...GACA frame is the byte signature (stagger-tolerant)
+    - {test: read_count, roles: 2}
+    - {test: motif_present, read: bc, motif: "GTGANNNNNNNNNGACA", where: window,
+       search_start: 8, search_end: 13, max_mismatch: 2, min_rate: 0.5}
+  supports:                              # each CLS block hits its own 97 x 9 bp pool, resolved per-read
+    - {when: {test: onlist_hit_rate, read: bc, element: cls1, onlist: cls1, orientation: forward, min: 0.5}, weight: 3.0}
+    - {when: {test: onlist_hit_rate, read: bc, element: cls2, onlist: cls2, orientation: forward, min: 0.5}, weight: 3.0}
+    - {when: {test: onlist_hit_rate, read: bc, element: cls3, onlist: cls3, orientation: forward, min: 0.5}, weight: 3.0}
+    - {when: {test: distinct_ratio, read: bc, element: UMI, expect: high}, weight: 1.0}
+    - {when: {test: distinct_ratio, read: cdna, start: 0, end: 20, expect: high}, weight: 1.0}
+  excludes: []
+
+backend:
+  module: map/starsolo
+  params:
+    soloType: CB_UMI_Complex
+    soloCBwhitelist: ["{onlist:cls1}", "{onlist:cls2}", "{onlist:cls3}"]   # order == CB-position order
+    # soloStrand Forward: the bead oligo ends in poly(dT) priming off the mRNA poly(A), so R2 is sense to
+    # the transcript — a 3' poly-dT capture library like the original bead (STAR #1607 sets Forward).
+    soloStrand: Forward
+    # soloAdapterSequence, soloCBposition, soloUMIposition are DERIVED from the anchored element model at
+    # compose time (compose/params.py) -> "NNNNNNNNNGTGANNNNNNNNNGACA" + "2_0_2_8 2_13_2_21 3_1_3_9" +
+    # "3_10_3_17", byte-identical to the maintainer-endorsed STARsolo string on issue #1607. Never
+    # hand-entered: the adapter anchor is where STARsolo absorbs the variable diversity insert.
+
+# Siblings under the family are decided by onlist (parent.children_decided_by), so no per-sibling edge.
+# Nothing else is confusable: the GTGA...GACA `requires` motif rejects the original bead, 10x and bulk
+# outright, and the >43 bp bc read is length-infeasible for 10x. (The generic bulk fallback accepts THIS
+# on read-count alone, so the edge is declared on `bulk-rnaseq-pe`, mirroring the original bead.)
+confusable_with: []

seqforge/kb/specs/bd-rhapsody-wta-enhanced-v2/spec.yaml

@@ -0,0 +1,81 @@
+schema_version: 1
+
+# ============================================================================================
+# BD RHAPSODY WTA — ENHANCED bead, 384 x 3 cell-label lists (rhapsodist class `enhanced_v2`).
+#
+# A leaf of `bd-rhapsody-wta-enhanced`, identical to `-96` in every byte-decided way (0-3 bp diversity
+# insert, GTGA/GACA linkers, 9/9/9 CLS + 8 bp UMI). The ONLY difference is the whitelist: 384 x 9 bp per
+# CLS block instead of 97 — the higher-plexity "Enhanced v2" bead. The 384 and 97 pools are DISJOINT
+# (0 shared 9-mers), so a real dataset hits exactly one set at rung 3 and the sibling tie resolves.
+#
+# The 384 x 3 lists ship pre-packed as `bd-rhapsody-cls{1,2,3}-384` (source: imallona/rhapsodist
+# workflow/data/whitelist_384x3, Moro & Mallona 2025).
+# ============================================================================================
+
+identity:
+  id: bd-rhapsody-wta-enhanced-v2
+  version: enhanced-384
+  name: "BD Rhapsody WTA — Enhanced bead v2 (384-plex cell labels)"
+  aliases: ["BD Rhapsody Enhanced v2", "Rhapsody Enhanced 384x3", "BD Rhapsody Enhanced 384"]
+  assay_ontology: ["EFO:0700003"]
+  modality: rna
+
+parent: bd-rhapsody-wta-enhanced
+
+reads:
+  - id: cdna
+    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}
+  - id: bc
+    seqspec_read_id: R1
+    file_hint: "_R1_"
+    strand: pos
+    min_len: 43
+    max_len: null
+    elements:
+      - {type: diversity, name: vb, min_len: 0, max_len: 3, seqspec_region_type: linker}
+      - {type: barcode, name: cls1, min_len: 9, max_len: 9, onlist: cls1, seqspec_region_type: barcode,
+         anchor: {relative_to: element, ref_element: vb, ref_side: end, offset: 0}}
+      - {type: linker, name: linker1, sequence: "GTGA", seqspec_region_type: linker,
+         anchor: {relative_to: element, ref_element: cls1, ref_side: end, offset: 0, max_mismatch: 1}}
+      - {type: barcode, name: cls2, min_len: 9, max_len: 9, onlist: cls2, seqspec_region_type: barcode,
+         anchor: {relative_to: element, ref_element: linker1, ref_side: end, offset: 0}}
+      - {type: linker, name: linker2, sequence: "GACA", seqspec_region_type: linker,
+         anchor: {relative_to: element, ref_element: cls2, ref_side: end, offset: 0, max_mismatch: 1}}
+      - {type: barcode, name: cls3, min_len: 9, max_len: 9, onlist: cls3, seqspec_region_type: barcode,
+         anchor: {relative_to: element, ref_element: linker2, ref_side: end, offset: 0}}
+      - {type: umi, name: UMI, min_len: 8, max_len: 8, seqspec_region_type: umi,
+         anchor: {relative_to: element, ref_element: cls3, ref_side: end, offset: 0}}
+
+onlists:
+  cls1: {registry: bd-rhapsody-cls1-384, role: cell_barcode, expected_orientation: forward}  # 384 x 9 bp
+  cls2: {registry: bd-rhapsody-cls2-384, role: cell_barcode, expected_orientation: forward}
+  cls3: {registry: bd-rhapsody-cls3-384, role: cell_barcode, expected_orientation: forward}
+
+signature:
+  requires:
+    - {test: read_count, roles: 2}
+    - {test: motif_present, read: bc, motif: "GTGANNNNNNNNNGACA", where: window,
+       search_start: 8, search_end: 13, max_mismatch: 2, min_rate: 0.5}
+  supports:
+    - {when: {test: onlist_hit_rate, read: bc, element: cls1, onlist: cls1, orientation: forward, min: 0.5}, weight: 3.0}
+    - {when: {test: onlist_hit_rate, read: bc, element: cls2, onlist: cls2, orientation: forward, min: 0.5}, weight: 3.0}
+    - {when: {test: onlist_hit_rate, read: bc, element: cls3, onlist: cls3, orientation: forward, min: 0.5}, weight: 3.0}
+    - {when: {test: distinct_ratio, read: bc, element: UMI, expect: high}, weight: 1.0}
+    - {when: {test: distinct_ratio, read: cdna, start: 0, end: 20, expect: high}, weight: 1.0}
+  excludes: []
+
+backend:
+  module: map/starsolo
+  params:
+    soloType: CB_UMI_Complex
+    soloCBwhitelist: ["{onlist:cls1}", "{onlist:cls2}", "{onlist:cls3}"]
+    soloStrand: Forward
+    # soloAdapterSequence / soloCBposition / soloUMIposition DERIVED from the anchored elements (see -96).
+
+confusable_with: []

seqforge/kb/specs/bulk-rnaseq-pe/README.md

@@ -0,0 +1,35 @@
+# Bulk paired-end RNA-seq
+
+Standard bulk RNA-seq on an Illumina sequencer: two paired-end cDNA reads, **no cell barcode and no
+UMI**. Every base is transcript sequence — there's nothing to demultiplex into cells. seqforge aligns
+these with plain STAR and counts genes, rather than STARsolo.
+
+## How it's read
+
+- **R1** and **R2** are the two ends of the same cDNA fragment (a mate pair). Both are transcript
+  sequence, typically 75–150 bp.
+- No barcode, no UMI, no whitelist.
+
+## How seqforge tells it apart from single-cell
+
+It's the **absence** of a barcode that identifies bulk. seqforge looks for a short, low-diversity
+technical read — the tell-tale of a cell barcode — and finds none, just two long, near-unique cDNA
+mates. A single-cell barcode read is short (26–28 bp) and repeats the same 16 bp prefix across reads;
+a bulk mate is long and near-unique from the first base, so a barcode read can never be mistaken for
+bulk cDNA.
+
+Because this entry demands so little, it also serves as the **fallback** for any paired-end data.
+That's deliberate: when a real single-cell library (BD Rhapsody, SPLiT-seq) happens to share this
+loose shape, seqforge falls back to the barcode-list check to make sure it never quietly treats a
+single-cell library as bulk.
+
+## Coverage note
+
+This is the paired-end, poly-A branch. Single-end bulk and explicit strand-protocol handling aren't
+modeled yet.
+
+## References
+
+The exact, machine-readable definition seqforge uses lives in this entry's `spec.yaml`.
+(scg_lib_structs documents single-cell library structures; plain bulk RNA-seq isn't one of them, so
+there's no page to link.)

seqforge/kb/specs/bulk-rnaseq-pe/spec.yaml

@@ -0,0 +1,97 @@
+schema_version: 1
+
+identity:
+  id: bulk-rnaseq-pe
+  version: illumina-pe
+  name: "Bulk Illumina paired-end RNA-seq (no cell barcode)"
+  aliases: ["bulk RNA-seq", "paired-end RNA-seq", "Illumina PE RNA-seq", "polyA RNA-seq PE", "RNA-seq PE"]
+  assay_ontology: ["EFO:0008896"]        # "RNA-Seq" (generic bulk) — verified against live EFO (EBI OLS)
+  modality: rna
+
+reads:
+  # Two symmetric cDNA mates, no cell barcode / UMI. The min_len gate (>=40) is what excludes a short
+  # single-cell barcode read (26/28 bp) from ever filling a bulk role.
+  - id: R1
+    seqspec_read_id: R1
+    file_hint: "_R1_"
+    strand: pos
+    min_len: 40
+    max_len: null
+    elements:
+      - {type: cdna, name: cdna_r1, start: 0, end: null, seqspec_region_type: cdna}
+  - id: R2
+    seqspec_read_id: R2
+    file_hint: "_R2_"
+    strand: neg                          # the reverse mate
+    min_len: 40
+    max_len: null
+    elements:
+      - {type: cdna, name: cdna_r2, start: 0, end: null, seqspec_region_type: cdna}
+
+onlists: {}
+
+signature:
+  requires:
+    - {test: read_count, roles: 2}       # two reads, both biological; no barcode role to fill
+  supports:                              # diverse cDNA => high distinct-ratio (not a repeated barcode)
+    - when: {test: distinct_ratio, read: R1, start: 0, end: 25, expect: high}
+      weight: 2.0
+    - when: {test: distinct_ratio, read: R2, start: 0, end: 25, expect: high}
+      weight: 2.0
+    - when: {test: header_index, present: true}     # real Illumina headers carry the sample index
+      weight: 0.5
+  excludes: []
+
+backend:
+  module: map/star                       # plain STAR (no solo): bulk has no barcode/UMI demultiplex
+  params: {}
+  # EMPTY, and meaningfully so — not degenerate. Bulk paired-end RNA-seq has nothing byte-decided to
+  # pass: no barcode, no UMI, no whitelist, no offsets. Every knob that used to live here was on the
+  # wrong side of the parse/count line:
+  #   - quantMode: GeneCounts        -> COUNTING. Now processing.quantification (BulkQuant.mode).
+  #   - outSAMtype: [BAM, Sorted..]  -> an OUTPUT FORMAT: neither parse nor count. It is a module
+  #     implementation detail, and the proof was already in this repo — starsolo.smk hardcoded
+  #     `--outSAMtype BAM Unsorted` in its shell block while star.smk read the same knob from config.
+  #     Two hand-written modules, two answers, one detail. star.smk now hardcodes it too.
+  #
+  # There is also no strandedness knob, and none is needed. This file used to promise that "library
+  # strandedness is resolved at compose from processing policy" — no code ever implemented it, because
+  # there was never a decision to make: `--quantMode GeneCounts` already emits ALL THREE strand columns
+  # in ReadsPerGene.out.tab. Same law as soloFeatures: when the aligner computes every alternative in
+  # one pass and the outputs are small, compute them all and let the consumer choose.
+
+confusable_with:
+  - id: splitseq
+    relationship: processing_divergent
+    distinguishable_by: [onlist]
+    note: >
+      This entry is the GENERIC PAIRED-END FALLBACK: it requires two reads and forbids very little,
+      so at rungs 0-2 it accepts SPLiT-seq's cdna+bc pair as readily as real bulk data. Computed, not
+      assumed — `rung02_separable(bulk, splitseq)` is False, which is what forced this declaration.
+      The two are maximally divergent downstream (map/star vs map/starsolo: no barcodes at all vs
+      three rounds of them), so silently preferring the alphabetically-luckier entry would emit a
+      bulk gene-count matrix for a single-cell library and exit 0. Only the onlist separates them:
+      SPLiT-seq's round1/2/3 barcodes hit their whitelists at rung 3 and bulk has no whitelist to
+      hit, which is why the resolver reaches rung 3 here rather than deciding at rung 2.
+  - id: bd-rhapsody-wta
+    relationship: processing_divergent
+    distinguishable_by: [onlist]
+    note: >
+      Same story as SPLiT-seq: the generic paired-end fallback accepts BD Rhapsody's cdna+bc pair on
+      geometry alone (`rung02_separable(bulk, bd-rhapsody-wta)` is False), so silently preferring bulk
+      would emit a gene-count matrix for a single-cell library and exit 0. Only the onlist separates
+      them — BD's three CLS whitelists hit at rung 3, and bulk has none.
+  - id: bd-rhapsody-wta-enhanced-v1
+    relationship: processing_divergent
+    distinguishable_by: [onlist]
+    note: >
+      The BD Rhapsody Enhanced bead (v1, 96-plex). Identical story to the original bead: this fallback
+      requires only two reads, so it accepts the Enhanced cdna+bc pair on read-count alone. Enhanced
+      REJECTS bulk (its GTGA...GACA `requires` motif is absent from bulk cDNA), but the acceptance is
+      one-directional, so the edge is declared here. The three CLS whitelists hit at rung 3; bulk has none.
+  - id: bd-rhapsody-wta-enhanced-v2
+    relationship: processing_divergent
+    distinguishable_by: [onlist]
+    note: >
+      The BD Rhapsody Enhanced bead (v2, 384-plex) — same reasoning as `-enhanced-v1`. Separated at rung
+      3 by the 384 x 3 CLS whitelists (disjoint from both the 96 pools and from anything bulk could hit).

seqforge/kb/specs/splitseq/README.md

@@ -0,0 +1,51 @@
+# SPLiT-seq (split-pool combinatorial barcoding)
+
+A single-cell RNA-seq method that needs no special instrument. Instead of one droplet per cell, cells
+are barcoded by **splitting and pooling** them through several rounds of labeling; after three rounds
+each cell carries a unique combination of three barcodes.
+
+This entry covers the **original published SPLiT-seq** (Rosenberg et al., *Science* 2018). Parse
+Biosciences' **Evercode** is a separate commercial descendant with different linkers and barcodes — a
+different chemistry, not covered here.
+
+## How it's read
+
+- **Read 1 = the cDNA** (the transcript).
+- **Read 2 = the barcode read**: a 10 bp UMI, then three 8 bp round-barcodes separated by two fixed
+  30 bp linkers.
+
+```text
+[10 bp UMI] [8 bp round-3] --linker1-- [8 bp round-2] --linker2-- [8 bp round-1]
+```
+
+A cell's identity is the combination of its round-1, round-2, and round-3 barcodes; each round draws
+from a list of ~96 barcodes.
+
+## How seqforge tells it apart
+
+Like BD Rhapsody, the **two fixed linker sequences at known positions** are the signature, and each
+round-barcode matches its own list. The exact linker lengths matter: the original 2018 chemistry puts
+round-1 at a different position than the later Parse chemistry, so a position copied from the wrong
+source silently mismatches. seqforge pins the original layout from the paper's own oligos.
+
+## Status: not yet ready for real data
+
+SPLiT-seq is the pilot's generalization test — it exercises machinery the 10x entries don't (8 bp
+barcodes instead of 16, a barcode split combinatorially across a read). Two things must land before
+it can process real data:
+
+- **The barcode lists must ship.** The entry names three round-barcode lists that aren't bundled yet.
+- **The strand must be confirmed on real data.** It's derived from the paper's oligos and the authors'
+  own pipeline (both point the same way), but the honest state is that most pipelines never explicitly
+  chose the strand — they inherited a default. The decisive check is to run the paper's own data both
+  ways; the correct strand assigns far more reads.
+
+Until then this entry is intentionally inert.
+
+## References
+
+Read structure and linker sequences pinned from
+**[scg_lib_structs — SPLiT-seq](https://teichlab.github.io/scg_lib_structs/methods_html/SPLiT-seq.html)**
+(Teichmann Lab, CC-BY) and independently reconstructed from the paper's oligo tables
+([Rosenberg et al., *Science* 2018](https://doi.org/10.1126/science.aam8999)). The exact,
+machine-readable definition seqforge uses lives in this entry's `spec.yaml`.