Release 2026.3.0

.gitignore

@@ -172,3 +172,6 @@ notebooks/analysis/mavedb_files
 urn:*.json
 tmp:*.json
 *_mapping_*.json
+
+# Agent settings
+.claude/

schema.json

@@ -95,6 +95,17 @@
       "title": "MappedReferenceSequence",
       "type": "object"
     },
+    "MappingOutcome": {
+      "description": "Per-record outcome for one (variant, annotation level) pair.\n\nThe mapper's output is a complete accounting: for every variant and every\nannotation level in that variant's deterministically-reachable set, there is one\nrecord carrying its outcome -- never a silent omission. This field is uniform across\nmeasured (assay-level) and projected (deterministic non-assay) records so the two can\nbe treated identically by consumers; it distinguishes a benign absence from a genuine\nfailure, which a populated ``error_message`` alone cannot.\n\n- ``MAPPED`` -- a VRS allele was produced (``pre_mapped``/``post_mapped`` populated).\n- ``INTRONIC`` -- the variant's coding projection is intronic: no VRS-representable\n  coding form and no protein consequence. Benign (``error_message`` is ``None``).\n- ``NO_PROTEIN_CONSEQUENCE`` -- the protein layer was reachable but yields no\n  projectable protein change (e.g. UTR). Benign (``error_message`` is ``None``).\n- ``FAILED`` -- the mapping/projection genuinely failed (mis-selected transcript,\n  projection error, unresolvable reference contig). ``error_message`` carries detail.",
+      "enum": [
+        "mapped",
+        "intronic",
+        "no_protein_consequence",
+        "failed"
+      ],
+      "title": "MappingOutcome",
+      "type": "string"
+    },
     "Number": {
       "description": "Define VRS 1.3 Number.",
       "properties": {
@@ -295,6 +306,17 @@
           "default": null,
           "title": "Near Gap"
         },
+        "outcome": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/MappingOutcome"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
         "post_mapped": {
           "anyOf": [
             {

src/api/routers/map.py

@@ -126,10 +126,23 @@ async def map_scoreset(urn: str, store_path: Path | None = None) -> JSONResponse
     protein_align_results: dict[str, AlignmentResult | None] = {}
     try:
         for target_gene in metadata.target_genes:
+            target_records = records.get(target_gene)
+
+            # e.g. base-editor score sets that declare separate protein and
+            # cDNA accession targets for the same variant: every row's hgvs_nt
+            # prefix groups under the cDNA target, so the protein target has no
+            # record group of its own and contributes nothing independently.
+            if target_records is None:
+                _logger.info(
+                    "No score records reference target %s directly; skipping standalone VRS mapping for this target.",
+                    target_gene,
+                )
+                continue
+
             vrs_map_result = vrs_map(
                 metadata=metadata.target_genes[target_gene],
                 align_result=alignment_results[target_gene],
-                records=records[target_gene],
+                records=target_records,
                 transcript=transcripts[target_gene],
                 silent=True,
             )

src/dcd_mapping/align.py

@@ -177,7 +177,12 @@ def _run_blat(
         cmd.extend(shlex.split(target_args))
 
     cmd.extend(
-        [f"-minScore={min_score}", f"-out={out_format}", str(query_file), out_file]
+        [
+            f"-minScore={min_score}",
+            f"-out={out_format}",
+            str(query_file),
+            out_file,
+        ]
     )
     _logger.debug("Running BLAT command: %s", " ".join(cmd))
 
@@ -914,7 +919,22 @@ def _get_best_match(
     tcoords = coords[0]
     qcoords = coords[1]
 
-    strand = Strand.POSITIVE if int(qcoords[0]) <= int(qcoords[-1]) else Strand.NEGATIVE
+    protein_vs_dna = "-q=prot" in blat_params.get("target_args", "")
+
+    # For cDNA queries the strand is read from qcoords direction: cDNA on the
+    # negative strand is reverse-complemented, so its qcoords decrease.
+    # For protein queries qcoords always increase (protein reads N→C regardless
+    # of genome strand), so qcoords direction is uninformative — use tcoords
+    # instead (they decrease when the gene is on the minus strand).
+    if protein_vs_dna:
+        strand = (
+            Strand.POSITIVE if int(tcoords[0]) <= int(tcoords[-1]) else Strand.NEGATIVE
+        )
+    else:
+        strand = (
+            Strand.POSITIVE if int(qcoords[0]) <= int(qcoords[-1]) else Strand.NEGATIVE
+        )
+
     q_start = int(qcoords.min())
     q_end = int(qcoords.max())
 
@@ -938,10 +958,9 @@ def _get_best_match(
         if ts == te or qs == qe:
             continue
 
-        hit_subranges.append(SequenceRange(start=ts, end=te))
+        hit_subranges.append(SequenceRange(start=min(ts, te), end=max(ts, te)))
         query_subranges.append(SequenceRange(start=min(qs, qe), end=max(qs, qe)))
 
-    protein_vs_dna = "-q=prot" in blat_params.get("target_args", "")
     alignment_qc = _build_alignment_qc(best_aln, protein_vs_dna=protein_vs_dna)
 
     return AlignmentResult(
@@ -953,7 +972,10 @@ def _get_best_match(
         coverage=coverage,
         query_range=SequenceRange(start=q_start, end=q_end),
         query_subranges=query_subranges,
-        hit_range=SequenceRange(start=int(tcoords[0]), end=int(tcoords[-1])),
+        hit_range=SequenceRange(
+            start=min(int(tcoords[0]), int(tcoords[-1])),
+            end=max(int(tcoords[0]), int(tcoords[-1])),
+        ),
         hit_subranges=hit_subranges,
         score=float(_scores[id(best_aln)]),
         next_best_score=next_best,
@@ -1155,7 +1177,7 @@ def build_alignment_result(
     if score_set_type == "sequence":
         try:
             alignment_result = align(metadata, silent)
-        except AlignmentError as e:
+        except AlignmentError:
             failed_at_nucleotide_level = any(
                 target_gene.target_sequence_type == TargetSequenceType.DNA
                 for target_gene in metadata.target_genes.values()
@@ -1165,7 +1187,7 @@ def build_alignment_result(
                 msg = f"BLAT alignment failed for {metadata.urn} at the nucleotide level. This alignment will be retried at the protein level."
                 _logger.warning(msg)
             else:
-                raise AlignmentError from e
+                raise
 
             # So long as force=True, the content of the records dict is irrelevant.
             try:
@@ -1178,10 +1200,10 @@ def build_alignment_result(
                     metadata.urn,
                 )
 
-            except AlignmentError as e2:
+            except AlignmentError as e:
                 msg = f"BLAT alignment failed for {metadata.urn} at the protein level after failing at the nucleotide level."
                 _logger.error(msg)
-                raise AlignmentError(msg) from e2
+                raise AlignmentError(msg) from e
 
     else:
         alignment_result = fetch_alignment(metadata, silent)
@@ -1246,7 +1268,7 @@ def align_target_to_protein(
         qs, qe = int(qcoords[i]), int(qcoords[i + 1])
         if ts == te or qs == qe:
             continue
-        hit_subranges.append(SequenceRange(start=ts, end=te))
+        hit_subranges.append(SequenceRange(start=min(ts, te), end=max(ts, te)))
         query_subranges.append(SequenceRange(start=min(qs, qe), end=max(qs, qe)))
 
     # Attach full sequences so _build_alignment_qc can do per-base mismatch
@@ -1260,7 +1282,10 @@ def align_target_to_protein(
     result = AlignmentResult(
         query_range=SequenceRange(start=int(qcoords.min()), end=int(qcoords.max())),
         query_subranges=query_subranges,
-        hit_range=SequenceRange(start=int(tcoords[0]), end=int(tcoords[-1])),
+        hit_range=SequenceRange(
+            start=min(int(tcoords[0]), int(tcoords[-1])),
+            end=max(int(tcoords[0]), int(tcoords[-1])),
+        ),
         hit_subranges=hit_subranges,
         percent_identity=_blat_style_identity(
             best_counts.identities,