Gene list matching: single alias hop, and a resync that deletes #1669

claude/maps/commands.md

@@ -144,7 +144,7 @@ Generated by `vg map commands` (do not edit; run `scripts/vg map commands` after
 | `fix_migrate_flags_to_imported_allele_info` | classification | (helper module, not a command) (guessed) | classification, flags, snpdb |
 | `fix_nbk_citations` | classification |  | classification |
 | `fix_orphanet_revalidation` | classification |  | classification |
-| `fix_rematch_release_symbols_to_genes` | genes |  | genes |
+| `fix_rematch_release_symbols_to_genes` | genes | Resyncs ReleaseGeneSymbolGene (the symbol -> gene matches for a GeneAnnotationRelease) with what | genes |
 | `fix_tag_colors_collection_permissions` | snpdb |  | snpdb |
 | `fix_truncated_annotation_runs` | annotation | Find AnnotationRuns whose VEP output was silently truncated, and mark them ERROR so they can be | annotation |
 | `fix_variant_annotation_add_hgvs_g` | annotation |  | annotation |

claude/plans/tso500_overall_plan.md

@@ -404,8 +404,9 @@ one, so they want to stay stable from the first client.
 Phase 6's gene-symbol item rests on that assumption holding. Phase 5's fusion parser goes through the
 same resolver for `SEPT14` → `SEPTIN14`, so one check against a real database covers both — and if the
 alias is missing, a fusion partner still imports, just under a local `GENE:` id rather than its HGNC one.
-[`1669_release_gene_matcher_alias_chaining_plan.md`](1669_release_gene_matcher_alias_chaining_plan.md)
-changes alias resolution to single-hop, so do the check after that lands.
+[#1669](https://github.com/SACGF/variantgrid/issues/1669) made `ReleaseGeneMatcher` single-hop; that is a
+different resolver from this one, but do the check against a database that has had
+`fix_rematch_release_symbols_to_genes` run.
 
 **Clients send a build's own name (`GRCh37`), not an alias.** `GenomeBuild.get_name_or_alias("hg19")`
 raises `MultipleObjectsReturned` rather than `DoesNotExist`, so a declared build that will not resolve

claude/research/genes.md

@@ -81,8 +81,11 @@ A symbol does not name a gene; it names a gene *in a release*. The same symbol h
 RefSeq ids over time (and TAZ became TAFAZZIN between builds), so `genes/gene_matching.py:ReleaseGeneMatcher` writes
 `genes/models/models_gene_annotation_release.py:ReleaseGeneSymbol` / `ReleaseGeneSymbolGene` rows per release: first
 a direct hit on the release's own GeneVersion symbols, then `genes/gene_matching.py:ReleaseGeneMatcher.aliases_dict`,
-which walks the alias graph (`ReleaseGeneMatcher._aliases`, loop-guarded) and the symbols other builds' GeneVersions
-gave the same gene, recording the path as `match_info` so the gene list grid can show why. Readers never touch the
+which takes a single `GeneSymbolAlias` hop in either direction (the symbol is the alias, or the alias is of the symbol)
+plus the symbols other builds' GeneVersions gave the same gene, recording the hop as `match_info` so the gene list grid
+can show why. The hop count is the whole point: chaining hops let an alias string shared by two unrelated genes bridge
+them, which is how an MT-TS2 gene list matched PDCD2 via "RP8" (#1669), and HGNC lists every previous symbol of a gene
+so renames never need more than one. Readers never touch the
 matcher: `genes/models/models_gene_annotation_release.py:GeneAnnotationRelease.genes_for_symbols` and
 `genes/models/models_gene_list.py:GeneList.get_genes` read the cached rows, and the release always comes from the
 VAV (`GeneAnnotationRelease.get_for_latest_annotation_versions_for_builds`). Matching is triggered whenever symbols
@@ -247,8 +250,10 @@ dicts on first use and `GeneSymbolMatcher.create_gene_list_gene_symbols` re-matc
 a loop creating lists should share one matcher. Inserting
 `GeneListGeneSymbol` rows any other way leaves symbols with no release rows and the list matches nothing in analyses
 until `genes/management/commands/rematch_unmatched_gene_list_symbols.py:Command` runs;
-`genes/management/commands/fix_rematch_release_symbols_to_genes.py:Command` re-runs the alias walk for symbols that
-have a release row but no gene.
+`genes/management/commands/fix_rematch_release_symbols_to_genes.py:Command` resyncs the whole derived table for every
+release - it inserts, updates `match_info` and deletes matches the current rules no longer make, which matching itself
+never does (`match_symbols_to_genes` only inserts), so rows left behind by an alias re-import or an older matcher need
+it. Run it `--dry-run` first.
 
 Genes prefixed `unknown_` are legacy placeholders from pre-GFF imports; `genes/management/commands/fix_fake_genes.py:Command`
 re-points their transcripts where another version names the gene and `Gene.delete_orphaned_fake_genes` removes the

genes/CLAUDE.md

@@ -32,6 +32,8 @@ Gotchas:
 - `PanelAppPanel.cache_valid` expires after `settings.PANEL_APP_CACHE_DAYS` (models/models_panel_app.py:PanelAppPanel.cache_valid); panel_app.py:get_panel_app_local_cache re-fetches from the live API when stale, so tests must not depend on it.
 - GeneCoverageCollection is a partitioned model (models/models_gene_coverage.py:GeneCoverageCollection); delete via the model so partitions are dropped.
 - gene_matching.py:GeneSymbolMatcher and gene_matching.py:ReleaseGeneMatcher cache whole-table dicts on first use; build one per import, not per symbol.
+- gene_matching.py:ReleaseGeneMatcher takes exactly one GeneSymbolAlias hop (either direction) - chaining hops lets an alias string shared by two unrelated genes bridge them (#1669). Keep it single-hop.
+- Matching only ever inserts ReleaseGeneSymbolGene rows, so a rematch can't remove a match that's since become wrong; `manage.py fix_rematch_release_symbols_to_genes` (`--dry-run` first) is the full resync that also updates and deletes.
 - `<CNV>` and `<INS>` have no HGVS at all - neither a ranged form nor an explicit expansion - so hgvs/hgvs_matcher.py:HGVSMatcher raises hgvs/hgvs_converter.py:HGVSNoRepresentationException before any converter runs, and classification records it as `ResolvedVariantInfo.error` rather than a Rollbar bug.
 Tests:
 - annotation/tests/test_data_fake_genes.py:create_fake_transcript_version builds Gene/GeneVersion/Transcript/TranscriptVersion (RUNX1, ENST00000300305.7) for a build; `create_gata2_transcript_version` / `create_pten_transcript_version` add RefSeq examples.