dsh-molbio-tools 0.22.2 → 0.24.1

package/contamination.mjs

@@ -0,0 +1,229 @@
+/**
+ * dsh-molbio-tools/contamination.mjs
+ *
+ * A small, EMBEDDED set of common vector-backbone/promoter/origin and
+ * Illumina/Nextera adapter signatures, plus a bounded both-strand screen.
+ *
+ * This is deliberately a short-signature screen, not a database search:
+ * a hit is evidence worth following up, and a miss is NOT evidence that a
+ * sample is clean. The table lives in code because the package has no external
+ * data files; every entry names the feature it represents so a report can be
+ * read without guessing which 20-mer matched.
+ *
+ * The adapters are shared with the FASTQ QC adapter-content panel. They are DNA
+ * here: the Small RNA 5' entry is publicly documented as RNA (GUUCAG...), but a
+ * FASTQ read is cDNA, so keeping the U in the table made the forward molecule
+ * unmatchable. Normalizing U→T at the source fixes the screen for both the
+ * standalone tool and fastq-qc's adapter panel.
+ */
+import { MolbioInputError, normalizeSequence, reverseComplement } from './lib.mjs';
+
+/** One signature in the embedded table. */
+export const ADAPTERS = [
+  { name: 'Illumina Universal', kind: 'adapter', category: 'adapter', sequence: 'AGATCGGAAGAG' },
+  { name: "Illumina Small RNA 3'", kind: 'adapter', category: 'adapter', sequence: 'TGGAATTCTCGG' },
+  { name: "Illumina Small RNA 5'", kind: 'adapter', category: 'adapter', sequence: 'GTTCAGAGTTCTACAGTCCGACGATC' },
+  { name: 'Nextera Transposase', kind: 'adapter', category: 'adapter', sequence: 'CTGTCTCTTATA' },
+  { name: 'PolyA', kind: 'adapter', category: 'homopolymer', sequence: 'AAAAAAAAAAAA' },
+  { name: 'PolyG', kind: 'adapter', category: 'homopolymer', sequence: 'GGGGGGGGGGGG' },
+];
+
+/**
+ * Common vector signatures. These are SHORT, deliberately: a 20-35 bp signature
+ * is enough to flag a backbone/promoter/origin in an assembly or read set, while
+ * a full vector sequence would turn this table into a reference database (and
+ * raise licensing questions). Names say which element matched.
+ */
+export const VECTORS = [
+  { name: 'pUC/pBR322 origin', kind: 'vector', category: 'origin', sequence: 'GTTTGCCGGATCAAGAGCTACCAACTCTTT' },
+  { name: 'pUC19 lacZ/M13 region', kind: 'vector', category: 'backbone', sequence: 'GTTTTCCCAGTCACGACGTTGTAAAACGACGGCCAGT' },
+  { name: 'pUC/pBR322 bla (AmpR) start', kind: 'vector', category: 'selection', sequence: 'ATGAGTATTCAACATTTCCGTGTCGCCCTT' },
+  { name: 'pET T7 promoter', kind: 'vector', category: 'promoter', sequence: 'TAATACGACTCACTATAGGG' },
+  { name: 'pET T7 terminator', kind: 'vector', category: 'terminator', sequence: 'GCTAGTTATTGCTCAGCGG' },
+  { name: 'pcDNA CMV promoter', kind: 'vector', category: 'promoter', sequence: 'CGCAAATGGGCGGTAGGCGTG' },
+  { name: 'pcDNA BGH polyA', kind: 'vector', category: 'terminator', sequence: 'CTAGAAGGCACAGTCGAGG' },
+  { name: 'Gateway attB1', kind: 'vector', category: 'recombination', sequence: 'ACAAGTTTGTACAAAAAAGCAGGCT' },
+  { name: 'Gateway attB2', kind: 'vector', category: 'recombination', sequence: 'ACCCAGCTTTCTTGTACAAAGTGGT' },
+];
+
+/** Every embedded signature, adapters first (the table order is stable). */
+export const SIGNATURES = [...ADAPTERS, ...VECTORS];
+
+/** Defaults and hard bounds shared by the tool, tests and docs. */
+export const CONTAMINATION_DEFAULTS = {
+  maxMismatches: 0,
+  maxMismatchesHard: 2,
+  maxReads: 0,
+  maxReadsHard: 200000,
+  maxHits: 100,
+};
+
+const round = (value, digits = 1) => Math.round(value * 10 ** digits) / 10 ** digits;
+
+/** Hamming distance over equal-length strings (non-ACGT positions count as mismatches). */
+function hamming(a, b) {
+  let distance = 0;
+  for (let index = 0; index < a.length; index++) {
+    if (a[index] !== b[index]) distance++;
+  }
+  return distance;
+}
+
+/** The seed chunks used by the mismatch path; one chunk when maxMismatches is 0. */
+function seedChunks(signature, maxMismatches) {
+  const count = maxMismatches + 1;
+  const base = Math.floor(signature.length / count);
+  const chunks = [];
+  let offset = 0;
+  for (let index = 0; index < count; index++) {
+    const length = index === count - 1 ? signature.length - offset : base;
+    chunks.push({ needle: signature.slice(offset, offset + length), offset });
+    offset += length;
+  }
+  return chunks;
+}
+
+/**
+ * Best occurrence of one needle on one strand, or undefined.
+ *
+ * Exact mode is a plain indexOf. The mismatch path uses maxMismatches+1 seed
+ * chunks: at most maxMismatches chunks can be altered, so at least one chunk
+ * must occur verbatim; every seed occurrence is verified with a Hamming count.
+ * This keeps a 30-mer search linear in the number of seed hits instead of
+ * scanning every window of every read.
+ */
+function bestOnStrand(sequence, needle, maxMismatches, strand) {
+  let best;
+  const consider = (start, mismatches) => {
+    if (start < 0 || start + needle.length > sequence.length) return;
+    if (best === undefined
+      || mismatches < best.mismatches
+      || (mismatches === best.mismatches && start < best.start)) {
+      best = { start, end: start + needle.length, strand, mismatches };
+    }
+  };
+  if (maxMismatches === 0) {
+    let from = 0;
+    while (from <= sequence.length - needle.length) {
+      const at = sequence.indexOf(needle, from);
+      if (at === -1) break;
+      consider(at, 0);
+      from = at + 1;
+    }
+    return best;
+  }
+  for (const chunk of seedChunks(needle, maxMismatches)) {
+    if (chunk.needle.length === 0) continue;
+    let from = 0;
+    while (from <= sequence.length - chunk.needle.length) {
+      const at = sequence.indexOf(chunk.needle, from);
+      if (at === -1) break;
+      const start = at - chunk.offset;
+      if (start >= 0 && start + needle.length <= sequence.length) {
+        const mismatches = hamming(sequence.slice(start, start + needle.length), needle);
+        if (mismatches <= maxMismatches) consider(start, mismatches);
+      }
+      from = at + 1;
+    }
+  }
+  return best;
+}
+
+/** Best hit of a signature against a sequence on either strand. */
+export function findSignatureHit(sequence, signature, maxMismatches = 0) {
+  const forward = bestOnStrand(sequence, signature, maxMismatches, '+');
+  const reverse = bestOnStrand(sequence, reverseComplement(signature), maxMismatches, '-');
+  if (forward === undefined) return reverse;
+  if (reverse === undefined) return forward;
+  if (reverse.mismatches < forward.mismatches) return reverse;
+  if (reverse.mismatches === forward.mismatches && reverse.start < forward.start) return reverse;
+  return forward;
+}
+
+/**
+ * Screen one or more sequences against the embedded signatures.
+ *
+ * @param {Array<{id: string, sequence: string}>} entries
+ * @param {{maxMismatches?: number, kinds?: 'both'|'adapter'|'vector', maxReads?: number}} [options]
+ * @returns {object} aggregate hits plus the criteria that produced them.
+ */
+export function screenContamination(entries, options = {}) {
+  if (!Array.isArray(entries) || entries.length === 0) throw new MolbioInputError('contamination screening needs at least one sequence');
+  const maxMismatches = options.maxMismatches ?? CONTAMINATION_DEFAULTS.maxMismatches;
+  if (!Number.isInteger(maxMismatches) || maxMismatches < 0 || maxMismatches > CONTAMINATION_DEFAULTS.maxMismatchesHard) {
+    throw new MolbioInputError('max_mismatches must be an integer between 0 and ' + CONTAMINATION_DEFAULTS.maxMismatchesHard);
+  }
+  const kinds = options.kinds ?? 'both';
+  if (!['both', 'adapter', 'vector'].includes(kinds)) throw new MolbioInputError('kinds must be "both", "adapter" or "vector"');
+  const maxReads = options.maxReads ?? CONTAMINATION_DEFAULTS.maxReads;
+  if (!Number.isInteger(maxReads) || maxReads < 0 || maxReads > CONTAMINATION_DEFAULTS.maxReadsHard) {
+    throw new MolbioInputError('max_reads must be an integer between 0 and ' + CONTAMINATION_DEFAULTS.maxReadsHard);
+  }
+  const limit = maxReads === 0 ? CONTAMINATION_DEFAULTS.maxReadsHard : maxReads;
+  const normalized = entries.map((entry, index) => ({
+    id: typeof entry?.id === 'string' && entry.id !== '' ? entry.id : 'entry' + (index + 1),
+    sequence: normalizeSequence(entry?.sequence ?? '', 'sequence'),
+  }));
+  const scanned = normalized.slice(0, limit);
+  const truncated = normalized.length > scanned.length;
+  const signatures = SIGNATURES.filter((signature) => kinds === 'both' || signature.kind === kinds);
+  let ambiguousBases = 0;
+  let bases = 0;
+  for (const entry of scanned) {
+    bases += entry.sequence.length;
+    for (const base of entry.sequence) if (!'ACGT'.includes(base)) ambiguousBases++;
+  }
+  const hits = [];
+  const withHit = new Set();
+  for (const signature of signatures) {
+    let reads = 0;
+    let best;
+    for (let index = 0; index < scanned.length; index++) {
+      const entry = scanned[index];
+      const hit = findSignatureHit(entry.sequence, signature.sequence, maxMismatches);
+      if (hit === undefined) continue;
+      reads++;
+      withHit.add(index);
+      if (best === undefined
+        || hit.mismatches < best.mismatches
+        || (hit.mismatches === best.mismatches && hit.start < best.start)) {
+        best = { ...hit, id: entry.id };
+      }
+    }
+    if (reads === 0) continue;
+    hits.push({
+      name: signature.name,
+      kind: signature.kind,
+      category: signature.category,
+      signature: signature.sequence,
+      reads,
+      percent: round((reads / scanned.length) * 100),
+      best_mismatches: best.mismatches,
+      example: {
+        id: best.id,
+        start: best.start + 1,
+        end: best.end,
+        strand: best.strand,
+        mismatches: best.mismatches,
+      },
+    });
+  }
+  hits.sort((a, b) => b.reads - a.reads || a.name.localeCompare(b.name));
+  return {
+    total_entries: normalized.length,
+    scanned_entries: scanned.length,
+    bases,
+    ambiguous_bases: ambiguousBases,
+    hits: hits.slice(0, CONTAMINATION_DEFAULTS.maxHits),
+    hit_count: Math.min(hits.length, CONTAMINATION_DEFAULTS.maxHits),
+    reads_with_hit: withHit.size,
+    truncated,
+    criteria: {
+      max_mismatches: maxMismatches,
+      kinds,
+      signature_count: signatures.length,
+      max_reads: maxReads,
+      match_basis: 'embedded short signatures, both strands, substitutions only (no gaps); a negative result does not prove the sample is clean',
+    },
+  };
+}

package/cordis.patch.yml

@@ -21,7 +21,7 @@
 #
 # Keep the tool in the PRESET and only the anchor here. An earlier version of
 # this file inserted a host row for the tool itself (`name: dsh-molbio-tools`),
-# which both registered all 60 tools globally and collided with the preset's own
+# which both registered every tool globally and collided with the preset's own
 # copy of that row:
 #
 #     broken: "tool-molbio (...): never started"
@@ -47,7 +47,7 @@
         id: molbio-lab
         order: 5
         name: Molecular Biology Lab
-        description: "分子生物学专属模式：标准编码能力 + 60 个 molbio_* 工具（序列分析、引物设计（含跨内含子 qPCR、盐/浓度旋钮与目标位置偏好）、TaqMan 水解探针（含 MGB 与订购 CSV）与多重 PCR 互扰/退火温度/浓度建议、克隆模拟与选酶（含 Golden Gate）、酶目录查询、甲基化敏感位点与双酶切 buffer 兼容检查、多序列比对（每个输入残基都会进比对结果）、保守性分析与比对后处理（共识/缺口修剪/同一性矩阵/逐列覆盖度，含 sequence logo 图）、CRISPR gRNA 设计（SpCas9/SaCas9/Cas12a/Cas13，家族特定 PAM/PFS/种子）与脱靶搜索、SnapGene/GenBank 解析与质粒图谱、Sanger 测序验证、蛋白性质/密码子优化/螺旋轮投影与疏水性图、qPCR 与绘图、虚拟凝胶、实验台分析（FASTQ 质控、密码子使用、系统发生树（长叶名自动折行）、in-silico PCR、CpG/GC 组成、批量文件分析/CSV）、静默酶切位点突变设计——生成的 SVG 图片自动用系统默认应用打开，文献/协议/实验记录）。"
+        description: "分子生物学专属模式：标准编码能力 + 64 个 molbio_* 工具（序列分析、引物设计（含跨内含子 qPCR、盐/浓度旋钮与目标位置偏好）、TaqMan 水解探针（含 MGB 与订购 CSV）与多重 PCR 互扰/退火温度/浓度建议、克隆模拟与选酶（含 Golden Gate）、酶目录查询、甲基化敏感位点与双酶切 buffer 兼容检查、多序列比对（每个输入残基都会进比对结果）、保守性分析与比对后处理（共识/缺口修剪/同一性矩阵/逐列覆盖度，含 sequence logo 图）、CRISPR gRNA 设计（SpCas9/SaCas9/Cas12a/Cas13，家族特定 PAM/PFS/种子）与脱靶搜索、SnapGene/GenBank 解析与质粒图谱、Sanger 测序验证、蛋白性质/电荷-pH 曲线/密码子优化/螺旋轮投影与疏水性图、qPCR 与绘图、虚拟凝胶、实验台分析（FASTQ 质控、密码子使用、系统发生树（长叶名自动折行）、in-silico PCR、CpG/GC 组成、序列 dotplot、载体/接头污染筛查、FASTQ 修剪/过滤、批量文件分析/CSV）、静默酶切位点突变设计——生成的 SVG 图片自动用系统默认应用打开，文献/协议/实验记录）。"
         plugins:
           - id: persona
             name: '@deepseek-ai/dsh-persona'
@@ -67,6 +67,11 @@
             disabled: !!js process.platform !== 'win32'
           - id: tool-fs
             name: '@deepseek-ai/dsh-tool-fs'
+            config:
+              # Set false to drop the apply_patch tool beside edit. (0.2.2-rc.1 makes this
+              # explicit in the shipped standard preset; the package default is false, and
+              # the row is kept verbatim so the two stay comparable.)
+              applyPatch: false
           - id: tool-fs-search
             name: '@deepseek-ai/dsh-tool-fs-search'
             config:
@@ -129,14 +134,13 @@
             config:
               - id: tool-subagent-control
                 name: '@deepseek-ai/dsh-tool-subagent-control'
-              - id: tool-subagent-list-agents
-                name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
               - id: tool-subagent
                 name: '@deepseek-ai/dsh-tool-subagent'
                 config:
                   provider: spawn
                   toolName: subagent
-                  modelSelectionSettings: true
+                  modelSelection: true
+                  modelDiscovery: true
               - id: tool-subagent-fork
                 name: '@deepseek-ai/dsh-tool-subagent'
                 config:
@@ -168,7 +172,7 @@
             name: '@deepseek-ai/dsh-plugin-market/tools'
             disabled: true
 
-          # dsh-molbio-tools: molecular-biology toolset (60 tools across sequence
+          # dsh-molbio-tools: molecular-biology toolset (64 tools across sequence
           # analysis, primers (incl. TaqMan probes and multiplex compatibility),
           # in-silico PCR, cloning (incl. Golden Gate), enzyme catalog, methylation-aware
           # and double digests, plasmids, Sanger verification, proteins (incl. helical

package/design.mjs

@@ -36,17 +36,17 @@
  *     from `anchor` and not from the RC-scan `start`. It is the REVERSE primer,
  *     and the amplicon ends at `anchor + length - 1`.
  *
- * NOTE — `designIntronSpanningPrimers` (tool: `molbio_design_intron_primers`)
- * deliberately does NOT follow this convention and is unchanged in 0.16.0: it
- * reports both primers as sense substrings of the spliced transcript, which is
- * what makes its `exon`/`junction_left`/`junction_right` geometry, its
- * spliced-vs-genomic mismatch report and its 3'-tail mispriming check read
- * uniformly on one sequence. Both ends are therefore reported 5'->3' on the
- * sense strand, `forward` is downstream of `reverse`, and the molecule to order
- * as the reverse primer is the reverse complement of the reported `reverse`.
- * That is a real usability wart, not a silent one (nothing feeds this pair to
- * `molbio_pcr_simulate`), so it is recorded on the roadmap rather than changed
- * in the same release that moves `designPrimerPairs`.
+ * `designIntronSpanningPrimers` (tool: `molbio_design_intron_primers`)
+ * follows the SAME convention since 0.23.0. The junction is carried by the
+ * REVERSE primer (the assay sits 5' of the junction), so the reverse candidate
+ * is scanned on the reverse complement of the spliced transcript: every 3'-end
+ * constraint is then evaluated on the molecule that is ordered, and the hit is
+ * mapped back to sense coordinates through `anchor` (its 3' end, the LEFT edge
+ * of its site). `forward` is upstream of `reverse`, the spliced amplicon runs
+ * from the forward 5' end to the reverse 5' end, and the reported reverse
+ * sequence is what goes on the order form. Before 0.23.0 the tool reported both
+ * primers as sense substrings, so `forward` sat downstream of `reverse` and the
+ * reported reverse was the reverse complement of the molecule to order.
  */
 
 import {
@@ -738,37 +738,60 @@ export function designPrimers(rawTemplate, rawOptions) {
 // ── cross-intron primer design ──────────────────────────────────────────────
 
 /**
- * Mismatch report for cross-intron candidates. Both primer scans run on the
- * spliced transcript in the sense orientation (the reported reverse.sequence
- * follows the established sense-substring convention of this tool), so the
- * mapping is uniform: `template_base` is what a perfectly matching primer
- * carries at the position on the spliced transcript, and coordinates come back
- * both spliced and genomic.
+ * Mismatch report for cross-intron candidates. The forward primer is the
+ * sense-strand substring at its binding site; the reverse primer is the REVERSE
+ * COMPLEMENT of the sense-strand substring at its site (the molecule that is
+ * ordered). `anchorStart` is the 0-based sense-strand position of the primer's
+ * 3' end — for the reverse primer that is the LEFT edge of its site — and
+ * `isReverse` flips both the perfect-match base and how a primer offset maps
+ * onto the transcript.
  */
-function intronMismatchReport(candidate, spliced, splicedToGenomic) {
+function intronMismatchReport(candidate, spliced, splicedToGenomic, anchorStart, isReverse) {
   const len = candidate.length;
-  return candidate.mismatches.map(({ p, base }) => ({
-    position: p + 1,
-    template_base: spliced[candidate.start + p],
-    primer_base: base,
-    spliced_position: candidate.start + p + 1,
-    genomic_position: splicedToGenomic[candidate.start + p] + 1,
-    distance_from_3prime: len - 1 - p,
-  }));
+  return candidate.mismatches.map(({ p, base }) => {
+    const offset = isReverse ? len - 1 - p : p;
+    const index = anchorStart + offset;
+    return {
+      position: p + 1,
+      template_base: isReverse ? complement(spliced[index]) : spliced[index],
+      primer_base: base,
+      spliced_position: index + 1,
+      genomic_position: splicedToGenomic[index] + 1,
+      distance_from_3prime: len - 1 - p,
+    };
+  });
 }
 
 /**
- * Design qPCR primer pairs where the forward primer spans an exon-exon
- * junction (>= min_junction_bases on each side) so genomic DNA cannot be
- * amplified, and the reverse primer sits in a different exon. Coordinates are
- * reported both on the spliced transcript and on the genomic sequence.
+ * The same weights as `mismatchPenalty`, over the snake_case report fields.
+ * The old intron path handed snake_case reports to the camelCase helper, so the
+ * 3'-zone surcharge never applied there; this keeps the two conventions apart on
+ * purpose instead of loosening the shared helper.
+ */
+function intronMismatchPenalty(report, zone) {
+  return report.reduce((sum, mismatch) => sum + 8 + (mismatch.distance_from_3prime <= zone ? 4 : 0), 0);
+}
+
+/**
+ * Design qPCR primer pairs across an exon-exon junction so genomic DNA cannot
+ * be amplified: the REVERSE primer straddles the junction (>= minJunctionBases
+ * on each side), the FORWARD primer sits upstream inside a single exon, and the
+ * spliced amplicon crosses the junction inside the reverse primer's site.
+ *
+ * Coordinates are reported both on the spliced transcript and on the genomic
+ * sequence. Orientation follows `designPrimerPairs` (see the file header):
+ * `forward.sequence` is the sense-strand substring at its site and
+ * `reverse.sequence` is the reverse complement of the sense-strand substring at
+ * its site. The reverse candidate is scanned on the reverse complement of the
+ * spliced transcript, so every 3'-end constraint (GC clamp, end stability, end
+ * GC, self-end, hairpin) applies to the molecule that is ordered.
  */
 export function designIntronSpanningPrimers(genomic, exons, opts) {
   if (!Array.isArray(exons) || exons.length < 2) throw new MolbioInputError('exons must be an array of at least two {start, end} spans');
   const sorted = [...exons].sort((a, b) => a.start - b.start);
   for (const exon of sorted) {
     if (!Number.isInteger(exon.start) || !Number.isInteger(exon.end) || exon.start < 1 || exon.end > genomic.length || exon.start > exon.end) {
-      throw new MolbioInputError(`exon ${JSON.stringify(exon)} is outside the genomic sequence (length ${genomic.length})`);
+      throw new MolbioInputError('exon ' + JSON.stringify(exon) + ' is outside the genomic sequence (length ' + genomic.length + ')');
     }
   }
   for (let i = 1; i < sorted.length; i++) {
@@ -791,33 +814,39 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
     }
   });
   if (spliced.length < 24) throw new MolbioInputError('the spliced transcript is too short for primer design');
+  const splicedLength = spliced.length;
+  const rcSpliced = reverseComplement(spliced);
 
   // v13 target position preference (coordinates on the spliced transcript).
   const targetPosition = opts.targetPosition;
-  if (targetPosition !== undefined && (!Number.isInteger(targetPosition) || targetPosition < 1 || targetPosition > spliced.length)) {
-    throw new MolbioInputError(`target_position ${targetPosition} is outside the spliced transcript (length ${spliced.length})`);
+  if (targetPosition !== undefined && (!Number.isInteger(targetPosition) || targetPosition < 1 || targetPosition > splicedLength)) {
+    throw new MolbioInputError('target_position ' + targetPosition + ' is outside the spliced transcript (length ' + splicedLength + ')');
   }
   const targetWeight = opts.targetPenalty ?? DESIGN_DEFAULTS.targetPenalty;
 
-  // Forward candidates must span a junction with minSide bases on each side.
-  const fwd = [];
-  for (const candidate of scanCandidates(spliced, 0, spliced.length - opts.lenMin, opts)) {
+  // Forward candidates: entirely inside one exon on the sense strand.
+  const fwd = scanCandidates(spliced, 0, splicedLength - opts.lenMin, opts)
+    .filter((candidate) => splicedToExon[candidate.start] === splicedToExon[candidate.start + candidate.length - 1])
+    .map((candidate) => ({ ...candidate, exon: splicedToExon[candidate.start] }))
+    .sort((a, b) => a.start - b.start);
+
+  // Reverse candidates: scanned on the reverse complement (the ordered
+  // molecule), then mapped back to the sense-strand 3' end `anchor`.
+  const rev = [];
+  for (const candidate of scanCandidates(rcSpliced, 0, splicedLength - opts.lenMin, opts)) {
+    const anchor = splicedLength - (candidate.start + candidate.length);
+    const topEnd = anchor + candidate.length - 1;
     for (const junction of junctionPositions) {
-      const left = junction.splicedPos - candidate.start;
-      const right = candidate.start + candidate.length - junction.splicedPos;
+      const left = junction.splicedPos - anchor;
+      const right = topEnd + 1 - junction.splicedPos;
       if (left >= minSide && right >= minSide) {
-        fwd.push({ ...candidate, junction, junction_left: left, junction_right: right });
+        rev.push({ ...candidate, anchor, junction, junction_left: left, junction_right: right });
         break;
       }
     }
   }
-
-  // Reverse candidates sit entirely inside one exon.
-  const rev = scanCandidates(spliced, 0, spliced.length - opts.lenMin, opts)
-    .filter((candidate) => splicedToExon[candidate.start] === splicedToExon[candidate.start + candidate.length - 1])
-    .map((candidate) => ({ ...candidate, exon: splicedToExon[candidate.start] }))
-    .sort((a, b) => a.start - b.start);
-  const revStarts = rev.map((candidate) => candidate.start);
+  rev.sort((a, b) => a.anchor - b.anchor);
+  const revAnchors = rev.map((candidate) => candidate.anchor);
 
   const tmCenter = (opts.tmMin + opts.tmMax) / 2;
   const misprimingIndex = opts.checkMispriming
@@ -826,48 +855,52 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
   const maxSites = opts.misprimingMaxSites ?? DESIGN_DEFAULTS.misprimingMaxSites;
   const pairs = [];
   for (const f of fwd) {
-    const fwdEnd = f.start + f.length - 1;
-    const aMin = fwdEnd - opts.ampliconMax + 1;
-    const aMax = fwdEnd - opts.ampliconMin + 1;
+    // The reverse site must start after the forward 3' end, and the amplicon
+    // (forward 5' -> reverse 5') must fit the window. The bounds are widened by
+    // the primer-length range and the exact length is checked below, because a
+    // long reverse primer can start earlier and still close inside the window.
+    const aMin = Math.max(f.start + f.length, f.start + opts.ampliconMin - opts.lenMax);
+    const aMax = f.start + opts.ampliconMax - opts.lenMin;
+    if (aMax < aMin) continue;
     let lo = 0;
-    let hi = revStarts.length;
+    let hi = revAnchors.length;
     while (lo < hi) {
       const mid = (lo + hi) >> 1;
-      if (revStarts[mid] < aMin) lo = mid + 1;
+      if (revAnchors[mid] < aMin) lo = mid + 1;
       else hi = mid;
     }
     for (let i = lo; i < rev.length; i++) {
       const r = rev[i];
-      if (r.start > aMax) break;
-      if (r.exon === f.junction.down) continue; // reverse primer must sit in a different exon
-      const gEnd = splicedToGenomic[fwdEnd];
-      const gStart = splicedToGenomic[r.start];
+      if (r.anchor > aMax) break;
+      const ampliconStart = f.start;
+      const ampliconEnd = r.anchor + r.length - 1;
+      const ampliconLength = ampliconEnd - ampliconStart + 1;
+      if (ampliconLength < opts.ampliconMin || ampliconLength > opts.ampliconMax) continue;
+      const gStart = splicedToGenomic[ampliconStart];
+      const gEnd = splicedToGenomic[ampliconEnd];
       if (gEnd - gStart + 1 < minGenomicSpan) continue;
       if (Math.abs(f.tm - r.tm) > opts.maxTmDelta) continue;
       const dimer = dimerThermo(f.sequence, r.sequence, opts.ctMolar ?? DEFAULT_CT_MOLAR);
       if (dimer.any_tm > opts.maxDimerTm || dimer.end_tm > opts.maxDimerEndTm) continue;
+      const misK = opts.mispriming3PrimeBases ?? DESIGN_DEFAULTS.mispriming3PrimeBases;
       let fMispriming = { count: 0, sites: [] };
       let rMispriming = { count: 0, sites: [] };
       if (misprimingIndex !== undefined) {
-        const misK = opts.mispriming3PrimeBases ?? DESIGN_DEFAULTS.mispriming3PrimeBases;
-        fMispriming = misprimingForCandidate(f, f.sequence.slice(-misK), misprimingIndex, opts, f.start);
+        // Exclude each primer's own 3'-tail window (not its 5' end).
+        fMispriming = misprimingForCandidate(f, f.sequence.slice(-misK), misprimingIndex, opts, f.start + f.length - misK);
         if (fMispriming.count > maxSites) continue;
-        // the reported reverse sequence follows the sense-substring convention:
-        // the real oligo is its reverse complement, so its 3' tail is the RC
-        // of the FIRST k bases and the intended site is r.start
-        const rTail = reverseComplement(r.sequence.slice(0, misK));
-        rMispriming = misprimingForCandidate(r, rTail, misprimingIndex, opts, r.start);
+        rMispriming = misprimingForCandidate(r, r.sequence.slice(-misK), misprimingIndex, opts, r.anchor);
         if (rMispriming.count > maxSites) continue;
       }
-      const fMismatches = intronMismatchReport(f, spliced, splicedToGenomic);
-      const rMismatches = intronMismatchReport(r, spliced, splicedToGenomic);
+      const fMismatches = intronMismatchReport(f, spliced, splicedToGenomic, f.start, false);
+      const rMismatches = intronMismatchReport(r, spliced, splicedToGenomic, r.anchor, true);
       const zone = opts.mismatch3PrimeZone ?? DESIGN_DEFAULTS.mismatch3PrimeZone;
       let fTargetDistance;
       let rTargetDistance;
       let targetDistance;
       if (targetPosition !== undefined) {
-        fTargetDistance = Math.abs(f.start + f.length - targetPosition); // spliced 1-based 3' end
-        rTargetDistance = Math.abs(r.start + 1 - targetPosition);
+        fTargetDistance = Math.abs(f.start + f.length - targetPosition); // forward 3' end (1-based)
+        rTargetDistance = Math.abs(r.anchor + 1 - targetPosition);       // reverse 3' end (1-based)
         targetDistance = Math.min(fTargetDistance, rTargetDistance);
       }
       const penalty = 0.6 * Math.abs(f.tm - r.tm) + Math.abs(f.tm - tmCenter) + Math.abs(r.tm - tmCenter)
@@ -875,8 +908,8 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
         + 1.0 * Math.max(0, f.self_end - 1) + 1.0 * Math.max(0, r.self_end - 1)
         + 0.2 * Math.max(0, f.hairpin_tm - 40) + 0.2 * Math.max(0, r.hairpin_tm - 40)
         + 0.2 * Math.max(0, dimer.any_tm - 40) + 0.2 * Math.max(0, dimer.end_tm - 40)
-        + mismatchPenalty(fMismatches, zone)
-        + mismatchPenalty(rMismatches, zone)
+        + intronMismatchPenalty(fMismatches, zone)
+        + intronMismatchPenalty(rMismatches, zone)
         + 8 * fMispriming.count + 8 * rMispriming.count
         + (targetDistance !== undefined ? targetWeight * targetDistance : 0);
       pairs.push({
@@ -894,9 +927,7 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
           spliced_end: f.start + f.length,
           genomic_start: splicedToGenomic[f.start] + 1,
           genomic_end: splicedToGenomic[f.start + f.length - 1] + 1,
-          exons: [String(f.junction.up + 1), String(f.junction.down + 1)],
-          junction_left: f.junction_left,
-          junction_right: f.junction_right,
+          exon: f.exon + 1,
           mismatch_count: fMismatches.length,
           mismatches: fMismatches,
           mispriming_count: fMispriming.count,
@@ -918,11 +949,13 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
           hairpin_tm: r.hairpin_tm,
           end_stability_kcal: r.end_stability_kcal,
           end_gc_count: r.end_gc_count,
-          spliced_start: r.start + 1,
-          spliced_end: r.start + r.length,
-          genomic_start: splicedToGenomic[r.start] + 1,
-          genomic_end: splicedToGenomic[r.start + r.length - 1] + 1,
-          exon: r.exon + 1,
+          spliced_start: r.anchor + 1,
+          spliced_end: r.anchor + r.length,
+          genomic_start: splicedToGenomic[r.anchor] + 1,
+          genomic_end: splicedToGenomic[r.anchor + r.length - 1] + 1,
+          exons: [String(r.junction.up + 1), String(r.junction.down + 1)],
+          junction_left: r.junction_left,
+          junction_right: r.junction_right,
           mismatch_count: rMismatches.length,
           mismatches: rMismatches,
           mispriming_count: rMispriming.count,
@@ -934,7 +967,7 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
           })),
           ...(rTargetDistance !== undefined ? { target_distance: rTargetDistance } : {}),
         },
-        spliced_amplicon: { start: r.start + 1, end: fwdEnd + 1, length: fwdEnd - r.start + 1 },
+        spliced_amplicon: { start: ampliconStart + 1, end: ampliconEnd + 1, length: ampliconLength },
         genomic_amplicon_length: gEnd - gStart + 1,
         ...(targetDistance !== undefined ? { target_distance: targetDistance } : {}),
         penalty: Math.round(penalty * 100) / 100,
@@ -945,7 +978,7 @@ export function designIntronSpanningPrimers(genomic, exons, opts) {
   const seen = new Set();
   const unique = [];
   for (const pair of pairs) {
-    const key = `${pair.spliced_amplicon.start}:${pair.spliced_amplicon.end}`;
+    const key = pair.spliced_amplicon.start + ':' + pair.spliced_amplicon.end;
     if (seen.has(key)) continue;
     seen.add(key);
     unique.push(pair);

package/docs/capability-gap-survey.md

@@ -6,6 +6,11 @@ mainstream bioinformatics landscape offer that this toolset does **not**, and wh
 deterministic algorithms in a few hundred lines of dependency-free JS with **no external data files,
 binaries, network, or reference databases**?
 
+> **Status note (0.24.0).** The baseline below is the 52-tool package this survey was written
+> against. Since then rows 1–7, 11, 12, 23, 30, 34, 40 and the Cas-family half of row 20 have shipped
+> (see [history.md](history.md) and the roadmap); the remaining rows are still candidates unless
+> §3 names a blocker. The rankings are left as written so the original judgement can be audited.
+
 **Method.** Surveyed nine source families (commercial plasmid/cloning suites; bench web calculators;
 Biopython/BioPerl/SeqKit/EMBOSS command-line toolkits; standard sequence/statistics analyses;
 microbiome; population genetics; protein prediction; alignment post-processing; sequencing QC),