allelix 2.4.0__tar.gz → 2.4.1__tar.gz

allelix-2.4.1/MANIFEST.in

@@ -0,0 +1,4 @@
+# The source distribution ships what the package needs to build and install.
+# setuptools adds tests/test*.py by default; the test suite (with its
+# fixtures and conftest) lives in the repository, not in the distribution.
+prune tests

{allelix-2.4.0 → allelix-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: allelix
-Version: 2.4.0
+Version: 2.4.1
 Summary: Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first.
 Author: Allelix
 Maintainer-email: dial481 <dial481@users.noreply.github.com>
@@ -47,7 +47,7 @@ Dynamic: license-file
 
 [![python](https://img.shields.io/pypi/pyversions/allelix.svg)](https://www.python.org/downloads/)
 [![pypi](https://img.shields.io/pypi/v/allelix.svg)](https://pypi.org/project/allelix/)
-[![license](https://img.shields.io/pypi/l/allelix.svg)](LICENSE)
+[![license](https://img.shields.io/pypi/l/allelix.svg)](https://github.com/allelix/allelix/blob/main/LICENSE)
 [![CI](https://github.com/allelix/allelix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/allelix/allelix/actions/workflows/ci.yml)
 [![privacy: local-first](https://img.shields.io/badge/privacy-local--first-success)](#privacy)
 
@@ -55,7 +55,7 @@ Dynamic: license-file
 
 # Allelix
 
-> **Status:** Production. Nine parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three GRCh38 enrichment sources (gnomAD + AlphaMissense + CADD) reached from GRCh37 input through a cross-build rsID identity table, licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports and annotated VCF output for pipeline integration (v2.3.0+), methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Modern-build position detection requires at least three concordant seed SNPs and an 80% winning ratio before it overrides a fallback or header signal; a tentative GRCh36 signal instead fails closed to GRCh36 because no modern position cache is safe for it (ADR-0025, ADR-0037). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
+> **Status:** Production. Nine parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three GRCh38 enrichment sources (gnomAD + AlphaMissense + CADD) reached from GRCh37 input through a cross-build rsID identity table, licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports and annotated VCF output for pipeline integration (v2.3.0+), methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. The genome build is decided before annotation from the evidence the file carries: VCF contig lengths, or known-SNP positions from the whole file. Evidence that contradicts the file's label, or a VCF with no usable evidence, stops the run and asks for `--build` instead of producing a report on the wrong build; a tentative GRCh36 signal fails closed to GRCh36 because no modern position cache is safe for it (ADR-0025, ADR-0037, ADR-0044). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
 
 ## Quickstart
 
@@ -99,14 +99,14 @@ See [Development](#development) for source installs and running tests, [Managing
 
 | Format | Status | Notes |
 |---|---|---|
-| MyHappyGenes (Tempus) | ✓ | Tab-delimited, 5 columns. **Build is auto-detected** — real-world MHG exports mislabel the header as "build 37.1" while shipping GRCh38 coordinates. Allelix detects from position data and warns on header/data disagreement (ADR-0021). See [docs/formats.md](https://github.com/allelix/allelix/blob/main/docs/formats.md#myhappygenes-tempus). |
+| MyHappyGenes (Tempus) | ✓ | Tab-delimited, 5 columns. **Build is auto-detected** — real-world MHG exports mislabel the header as "build 37.1" while shipping GRCh38 coordinates. Allelix decides the build from position data and warns on header/data disagreement (ADR-0021, ADR-0044). See [docs/formats.md](https://github.com/allelix/allelix/blob/main/docs/formats.md#myhappygenes-tempus). |
 | 23andMe | ✓ | Tab-delimited, 4 columns, concatenated genotype. Supports build 36/37/38 from header. I-prefixed probe IDs passed through. |
 | AncestryDNA | ✓ | Tab-delimited, 5 columns. Chromosome mapping: 23→X, 24→Y, 25→X (PAR), 26→MT. V1 and V2 chip layouts. |
-| Family Tree DNA | ✓ | CSV, double-quoted fields, concatenated genotype. Build 37 default. |
+| Family Tree DNA | ✓ | CSV, double-quoted fields, concatenated genotype. Build 37 default when known-SNP positions are present but do not decide; with none at all and no build line, the run stops (ADR-0044). |
 | MyHeritage DNA | ✓ | CSV, same structure as FTDNA. Detected by "MyHeritage" in the file's preamble. Handles double-double-quoted fields and files re-saved through a spreadsheet (padded rows, signature not on line 1, tab-delimited copies). Two exports: the **array** export (pre-2026 kits) and the **low-pass WGS** export (kits from January 2026; genotypes imputed from about 2x coverage), which the report labels as imputed and whose `##reference=build37` line is used as the header build. See [docs/formats.md](https://github.com/allelix/allelix/blob/main/docs/formats.md#myheritage). |
 | Living DNA | ✓ | Tab-delimited despite `.csv` extension. Handles AX-, AFFX-prefixed and CHR:POS positional SNP IDs. |
-| FTDNA Illumina raw | ✓ | Tab-delimited variant of the FTDNA export (distinct from the CSV format above). `RSID/CHROMOSOME/POSITION/RESULT` columns. Build 37 default. |
-| FTDNA FamFinder | ✓ | Third FTDNA file shape: tab-delimited with **separate `ALLELE1` / `ALLELE2` columns** instead of a concatenated `RESULT`. Detected by the `famfinder` substring in the file header plus the 5-column canonical header. Build 37 default. |
+| FTDNA Illumina raw | ✓ | Tab-delimited variant of the FTDNA export (distinct from the CSV format above). `RSID/CHROMOSOME/POSITION/RESULT` columns. Build 37 default when known-SNP positions are present but do not decide. |
+| FTDNA FamFinder | ✓ | Third FTDNA file shape: tab-delimited with **separate `ALLELE1` / `ALLELE2` columns** instead of a concatenated `RESULT`. Detected by the `famfinder` substring in the file header plus the 5-column canonical header. Build 37 default when known-SNP positions are present but do not decide. |
 | VCF / gVCF | ✓ | REF/ALT encoding, `0/1` genotype notation. Plain VCF: absence at a position means reference. gVCF: explicit reference blocks (lines with `<NON_REF>` ALT and `END=` INFO) are not annotated — they match nothing in any annotation database — but they are read at high-value positions: a block with low genotype quality or no reads there makes the position a no-call, and so does a gVCF position no record covers. High-value no-calls list the reason (for example `low_gq_block`, `no_coverage`, `filtered`, `low_gq_call`). A plain VCF has no reference blocks, so a position without a record is reported as unknown rather than as reference or as a no-call. Multi-sample files require `--sample <ID>`. Rows the variant caller rejected (FILTER other than `PASS` or `.`) are skipped and counted in the report; `--keep-filtered` keeps them. A call with genotype quality below `--min-gq` (default 20) or with no reads (DP 0) is reported as a no-call. The spanning-deletion allele `*` is treated as symbolic. A VCF that holds only structural-variant or copy-number records (such as a provider's separate `sv` / `cnv` file) is rejected with a message naming the file to use instead; see [docs/formats.md](https://github.com/allelix/allelix/blob/main/docs/formats.md#sequencingcom-30x-whole-genome) for per-provider deliverables. Streams via stdlib; `.vcf.gz` handled transparently. Optional `pip install allelix[vcf-index]` enables pysam-backed tabix random access for fast `extract --snps` on huge VCFs. |
 
 Adding a new format means adding one file to `allelix/parsers/` and registering an instance in the `PARSERS` list in `allelix/parsers/__init__.py`.
@@ -126,7 +126,7 @@ Issues and milestones are tracked at [github.com/allelix/allelix/issues](https:/
 
 | Database | Status | Notes |
 |---|---|---|
-| ClinVar (GRCh37 + GRCh38) | ✓ | Public domain (NCBI). SNVs + indels + multi-allelic sites. **Both builds cached**; `analyze` dispatches by detected build (ADR-0021). Rows are matched by chromosome, position, REF and ALT, never by rsID alone, and reference-allele records (REF = ALT) are never reported (ADR-0039). Carrier rule (ADR-0007) requires the user to carry the ALT allele. Indel-anchor protection (ADR-0011) prevents single-base array readouts from matching anchor-base indels. |
+| ClinVar (GRCh37 + GRCh38) | ✓ | Public domain (NCBI). SNVs + indels + multi-allelic sites. **Both builds cached**; `analyze` dispatches by the decided build (ADR-0044). Rows are matched by chromosome, position, REF and ALT, never by rsID alone, and reference-allele records (REF = ALT) are never reported (ADR-0039). Carrier rule (ADR-0007) requires the user to carry the ALT allele. Indel-anchor protection (ADR-0011) prevents single-base array readouts from matching anchor-base indels. |
 | ClinPGx (formerly PharmGKB) | ✓ | CC BY-SA 4.0. Clinical annotations only — single-rsid SNVs; star alleles and haplotypes deferred (ADR-0009). **Primary non-finding filter is the ClinVar REF carrier rule (ADR-0023):** if ClinVar publishes a single-base REF for the rsid and the user is homozygous for it, the row is suppressed. CPIC's `(rsid, base) → function_class` join (ADR-0020) survives as a secondary tier for rsids ClinVar doesn't catalog. Earlier prose tiers (ADR-0013, ADR-0017, ADR-0018) are superseded. |
 | CPIC (per-allele function table) | ✓ | Internal data source for the ClinPGx filter. Fetched from `api.cpicpgx.org` at `db update` time. Used to populate the `pharmgkb_allele_function` table — not surfaced to end users as its own annotator. |
 | SNPedia | ✓ | CC BY-NC-SA 3.0 US. Pre-built cache downloaded via `db update` (~216K wiki pages, ~105K genotype rows). The cache carries SNPedia's orientation metadata: minus-strand alleles are complemented before matching, while unknown-orientation palindromic genotypes abstain rather than risk a false match. If the database is absent, analysis runs without it. For commercial use, pass `--exclude-snpedia`. The cache can also be rebuilt from source via `scripts/scrape_snpedia.py` + `scripts/parse_snpedia.py`. |
@@ -383,11 +383,27 @@ If the failure is a network timeout on the same source repeatedly, the issue is
 
 Almost always a schema or interpreter version bump in a recent allelix release that invalidates the pre-bump cache. The fix is `allelix db update` — it'll re-ingest only the affected annotators (everything else signal-skips). See the relevant `CHANGELOG.md` entry for "Cache invalidation" notes per release.
 
-### Build mismatch warning when analyzing a known-good file
+### How the genome build is decided, and why a run can stop
 
-Either: (a) the file's header claims one build and the position data confidently indicates another (real-world MHG / Tempus exports do this — header says 37, positions are 38), or (b) the position signal is too small or mixed to be authoritative. Allelix requires at least three concordant seed SNPs and an 80% winning ratio. A VCF record without an rsID counts as a seed when it sits at that seed's position on a build, so variant-caller output with an empty ID column is detected by position too. Weaker GRCh37/38 evidence is reported as tentative and the header or fallback remains effective. A tentative GRCh36 winner is the safety exception: Allelix uses GRCh36 so it cannot accidentally query a modern position cache. Modern position-keyed caches are unavailable for that build (see [`docs/grch36-liftover.md`](https://github.com/allelix/allelix/blob/main/docs/grch36-liftover.md)).
+Before anything is annotated, Allelix decides the file's genome build from the evidence the file itself carries (ADR-0044):
 
-If you trust the file's header more than allelix's detection, force the build: `--build grch37` or `--build grch38`. The build banner in the analyze output will reflect what was actually used.
+- **VCF contig lengths.** Every nuclear chromosome has a different length in GRCh37 and GRCh38, so the `##contig` lengths settle the build whatever the contig names look like (`chr1` or `1`). If chrM has the old hg19 length, mitochondrial records are not annotated and a note says so.
+- **Known-SNP positions across the whole file.** A set of well-known SNPs sits at different positions in each build. Allelix reads the whole file for them before annotating (a few seconds on a full chip). At least three concordant positions and an 80% majority make the evidence confident (ADR-0037). A VCF record without an rsID counts when it sits at such a position.
+- **The file's own label** (a build line in an array header, or a VCF `assembly=`) is used only when the evidence does not contradict it.
+
+The banner says where the build came from, for example `Build: GRCh38 (from the contig lengths: 24 contig length(s) match GRCh38)`. If confident positions contradict the label (real-world MHG / Tempus exports say 37 and ship 38), Allelix uses the positions and prints a **Build mismatch** notice. An unlabelled chip whose known-SNP positions do not decide uses its format's documented default, with a visible note, provided at least one of those positions matches a build and the build most of them match is the default (a few that disagree do not stop it); the note gives the counts. A tentative GRCh36 winner is the safety exception: Allelix uses GRCh36 so it cannot query a modern position cache (see [`docs/grch36-liftover.md`](https://github.com/allelix/allelix/blob/main/docs/grch36-liftover.md)).
+
+**The run stops** instead of guessing when:
+
+- a VCF's contig lengths contradict its `assembly=`, contradict each other, or match no supported assembly;
+- weaker (tentative) position evidence contradicts the file's label, or points an unlabelled chip away from its default;
+- the known-SNP positions are tied between builds and the build that would otherwise decide (the label, the format default, or the contig-length build) is not one of them. When it is one of them, Allelix proceeds on it and prints an "inconclusive" warning, also shown in the HTML report. Without contig lengths, a tie that includes GRCh36 instead takes the GRCh36 safety exception described above, with the same warning;
+- a VCF has no contig lengths, no assembly and too few known-SNP positions;
+- a chip states no build and carries none of the known-SNP positions at all (for example an X-chromosome-only export, since they are all on autosomes);
+- the file has known-SNP positions but none of them sits at any supported build's coordinate, whether or not it states a build (contig lengths, when a VCF declares them, still decide);
+- contig lengths decided, but the known-SNP positions met while annotating point to the other build (for example a lifted-over file that kept its old header). The message says the annotation pass ran; nothing is written.
+
+The message names the evidence and asks you to say which build the file uses: `--build grch37` or `--build grch38`, or `--build grch36` for an old GRCh36 / hg18 file, which then runs with position-keyed lookups off (see [`docs/grch36-liftover.md`](https://github.com/allelix/allelix/blob/main/docs/grch36-liftover.md)). For `compare`, use `--build1` / `--build2`. A stop leaves no report, annotated VCF, diff, PLINK files or extract table behind. A forced build is recorded as such in every report.
 
 ### Is my database stale? How fresh is the data?
 
@@ -419,6 +435,7 @@ Notable load-bearing ADRs:
 - **ADR-0038 — GWAS effect-modifier disambiguation.** Only positively identified odds ratios receive an effect-size modifier; beta and ambiguous effects abstain.
 - **ADR-0042 — VCF quality gate.** The variant caller's FILTER and genotype quality are honoured, low-quality reference blocks are no-calls, and every exclusion is counted in the report.
 - **ADR-0043 — One rsID-recovery step.** Every command that needs rsIDs recovers them for rsID-less input through the same shared step; build detection votes by position instead.
+- **ADR-0044 — Evidence before labels.** The build is decided before annotation from contig lengths or whole-file known-SNP positions; evidence that contradicts the label, or no usable evidence, stops the run instead of producing a report on the wrong build.
 - **ADR-0041 — Plausibility flag.** Very rare homozygous calls and heterozygous calls with no gnomAD carriers are flagged for review, never suppressed.
 
 Release history: see [`CHANGELOG.md`](https://github.com/allelix/allelix/blob/main/CHANGELOG.md).
@@ -439,7 +456,7 @@ pytest
 
 The pre-commit hook enforces `ruff check` + `ruff format --check`. If a commit is blocked, fix the underlying problem rather than skipping the hook.
 
-For the full real-data release-validation battery — every parser format, VCF/gVCF, PLINK round-trip, edge cases, the GIAB/1000G corpus — see [`test_data/FULL_TEST_PROTOCOL.md`](test_data/FULL_TEST_PROTOCOL.md). That document is the project's real-data testing story; running `pytest` covers the fast suite that gates every commit.
+For the full real-data release-validation battery — every parser format, VCF/gVCF, PLINK round-trip, edge cases, the GIAB/1000G corpus — see [`test_data/FULL_TEST_PROTOCOL.md`](https://github.com/allelix/allelix/blob/main/test_data/FULL_TEST_PROTOCOL.md). That document is the project's real-data testing story; running `pytest` covers the fast suite that gates every commit.
 
 ## License
 

{allelix-2.4.0 → allelix-2.4.1}/README.md

@@ -8,7 +8,7 @@
 
 [![python](https://img.shields.io/pypi/pyversions/allelix.svg)](https://www.python.org/downloads/)
 [![pypi](https://img.shields.io/pypi/v/allelix.svg)](https://pypi.org/project/allelix/)
-[![license](https://img.shields.io/pypi/l/allelix.svg)](LICENSE)
+[![license](https://img.shields.io/pypi/l/allelix.svg)](https://github.com/allelix/allelix/blob/main/LICENSE)
 [![CI](https://github.com/allelix/allelix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/allelix/allelix/actions/workflows/ci.yml)
 [![privacy: local-first](https://img.shields.io/badge/privacy-local--first-success)](#privacy)
 
@@ -16,7 +16,7 @@
 
 # Allelix
 
-> **Status:** Production. Nine parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three GRCh38 enrichment sources (gnomAD + AlphaMissense + CADD) reached from GRCh37 input through a cross-build rsID identity table, licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports and annotated VCF output for pipeline integration (v2.3.0+), methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. Modern-build position detection requires at least three concordant seed SNPs and an 80% winning ratio before it overrides a fallback or header signal; a tentative GRCh36 signal instead fails closed to GRCh36 because no modern position cache is safe for it (ADR-0025, ADR-0037). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
+> **Status:** Production. Nine parser formats (including VCF + gVCF), four annotators (ClinVar + ClinPGx + GWAS Catalog + SNPedia), three GRCh38 enrichment sources (gnomAD + AlphaMissense + CADD) reached from GRCh37 input through a cross-build rsID identity table, licensable-source gating for commercial users, dual-build ClinVar caches (GRCh37 + GRCh38), HTML/JSON/terminal reports and annotated VCF output for pipeline integration (v2.3.0+), methylation + pharmacogenomics focused commands, report diffing, persistent config with commercial-mode safety switch. The genome build is decided before annotation from the evidence the file carries: VCF contig lengths, or known-SNP positions from the whole file. Evidence that contradicts the file's label, or a VCF with no usable evidence, stops the run and asks for `--build` instead of producing a report on the wrong build; a tentative GRCh36 signal fails closed to GRCh36 because no modern position cache is safe for it (ADR-0025, ADR-0037, ADR-0044). No regex on prose anywhere in production. The [Changelog](https://github.com/allelix/allelix/blob/main/CHANGELOG.md) tracks every release.
 
 ## Quickstart
 
@@ -60,14 +60,14 @@ See [Development](#development) for source installs and running tests, [Managing
 
 | Format | Status | Notes |
 |---|---|---|
-| MyHappyGenes (Tempus) | ✓ | Tab-delimited, 5 columns. **Build is auto-detected** — real-world MHG exports mislabel the header as "build 37.1" while shipping GRCh38 coordinates. Allelix detects from position data and warns on header/data disagreement (ADR-0021). See [docs/formats.md](https://github.com/allelix/allelix/blob/main/docs/formats.md#myhappygenes-tempus). |
+| MyHappyGenes (Tempus) | ✓ | Tab-delimited, 5 columns. **Build is auto-detected** — real-world MHG exports mislabel the header as "build 37.1" while shipping GRCh38 coordinates. Allelix decides the build from position data and warns on header/data disagreement (ADR-0021, ADR-0044). See [docs/formats.md](https://github.com/allelix/allelix/blob/main/docs/formats.md#myhappygenes-tempus). |
 | 23andMe | ✓ | Tab-delimited, 4 columns, concatenated genotype. Supports build 36/37/38 from header. I-prefixed probe IDs passed through. |
 | AncestryDNA | ✓ | Tab-delimited, 5 columns. Chromosome mapping: 23→X, 24→Y, 25→X (PAR), 26→MT. V1 and V2 chip layouts. |
-| Family Tree DNA | ✓ | CSV, double-quoted fields, concatenated genotype. Build 37 default. |
+| Family Tree DNA | ✓ | CSV, double-quoted fields, concatenated genotype. Build 37 default when known-SNP positions are present but do not decide; with none at all and no build line, the run stops (ADR-0044). |
 | MyHeritage DNA | ✓ | CSV, same structure as FTDNA. Detected by "MyHeritage" in the file's preamble. Handles double-double-quoted fields and files re-saved through a spreadsheet (padded rows, signature not on line 1, tab-delimited copies). Two exports: the **array** export (pre-2026 kits) and the **low-pass WGS** export (kits from January 2026; genotypes imputed from about 2x coverage), which the report labels as imputed and whose `##reference=build37` line is used as the header build. See [docs/formats.md](https://github.com/allelix/allelix/blob/main/docs/formats.md#myheritage). |
 | Living DNA | ✓ | Tab-delimited despite `.csv` extension. Handles AX-, AFFX-prefixed and CHR:POS positional SNP IDs. |
-| FTDNA Illumina raw | ✓ | Tab-delimited variant of the FTDNA export (distinct from the CSV format above). `RSID/CHROMOSOME/POSITION/RESULT` columns. Build 37 default. |
-| FTDNA FamFinder | ✓ | Third FTDNA file shape: tab-delimited with **separate `ALLELE1` / `ALLELE2` columns** instead of a concatenated `RESULT`. Detected by the `famfinder` substring in the file header plus the 5-column canonical header. Build 37 default. |
+| FTDNA Illumina raw | ✓ | Tab-delimited variant of the FTDNA export (distinct from the CSV format above). `RSID/CHROMOSOME/POSITION/RESULT` columns. Build 37 default when known-SNP positions are present but do not decide. |
+| FTDNA FamFinder | ✓ | Third FTDNA file shape: tab-delimited with **separate `ALLELE1` / `ALLELE2` columns** instead of a concatenated `RESULT`. Detected by the `famfinder` substring in the file header plus the 5-column canonical header. Build 37 default when known-SNP positions are present but do not decide. |
 | VCF / gVCF | ✓ | REF/ALT encoding, `0/1` genotype notation. Plain VCF: absence at a position means reference. gVCF: explicit reference blocks (lines with `<NON_REF>` ALT and `END=` INFO) are not annotated — they match nothing in any annotation database — but they are read at high-value positions: a block with low genotype quality or no reads there makes the position a no-call, and so does a gVCF position no record covers. High-value no-calls list the reason (for example `low_gq_block`, `no_coverage`, `filtered`, `low_gq_call`). A plain VCF has no reference blocks, so a position without a record is reported as unknown rather than as reference or as a no-call. Multi-sample files require `--sample <ID>`. Rows the variant caller rejected (FILTER other than `PASS` or `.`) are skipped and counted in the report; `--keep-filtered` keeps them. A call with genotype quality below `--min-gq` (default 20) or with no reads (DP 0) is reported as a no-call. The spanning-deletion allele `*` is treated as symbolic. A VCF that holds only structural-variant or copy-number records (such as a provider's separate `sv` / `cnv` file) is rejected with a message naming the file to use instead; see [docs/formats.md](https://github.com/allelix/allelix/blob/main/docs/formats.md#sequencingcom-30x-whole-genome) for per-provider deliverables. Streams via stdlib; `.vcf.gz` handled transparently. Optional `pip install allelix[vcf-index]` enables pysam-backed tabix random access for fast `extract --snps` on huge VCFs. |
 
 Adding a new format means adding one file to `allelix/parsers/` and registering an instance in the `PARSERS` list in `allelix/parsers/__init__.py`.
@@ -87,7 +87,7 @@ Issues and milestones are tracked at [github.com/allelix/allelix/issues](https:/
 
 | Database | Status | Notes |
 |---|---|---|
-| ClinVar (GRCh37 + GRCh38) | ✓ | Public domain (NCBI). SNVs + indels + multi-allelic sites. **Both builds cached**; `analyze` dispatches by detected build (ADR-0021). Rows are matched by chromosome, position, REF and ALT, never by rsID alone, and reference-allele records (REF = ALT) are never reported (ADR-0039). Carrier rule (ADR-0007) requires the user to carry the ALT allele. Indel-anchor protection (ADR-0011) prevents single-base array readouts from matching anchor-base indels. |
+| ClinVar (GRCh37 + GRCh38) | ✓ | Public domain (NCBI). SNVs + indels + multi-allelic sites. **Both builds cached**; `analyze` dispatches by the decided build (ADR-0044). Rows are matched by chromosome, position, REF and ALT, never by rsID alone, and reference-allele records (REF = ALT) are never reported (ADR-0039). Carrier rule (ADR-0007) requires the user to carry the ALT allele. Indel-anchor protection (ADR-0011) prevents single-base array readouts from matching anchor-base indels. |
 | ClinPGx (formerly PharmGKB) | ✓ | CC BY-SA 4.0. Clinical annotations only — single-rsid SNVs; star alleles and haplotypes deferred (ADR-0009). **Primary non-finding filter is the ClinVar REF carrier rule (ADR-0023):** if ClinVar publishes a single-base REF for the rsid and the user is homozygous for it, the row is suppressed. CPIC's `(rsid, base) → function_class` join (ADR-0020) survives as a secondary tier for rsids ClinVar doesn't catalog. Earlier prose tiers (ADR-0013, ADR-0017, ADR-0018) are superseded. |
 | CPIC (per-allele function table) | ✓ | Internal data source for the ClinPGx filter. Fetched from `api.cpicpgx.org` at `db update` time. Used to populate the `pharmgkb_allele_function` table — not surfaced to end users as its own annotator. |
 | SNPedia | ✓ | CC BY-NC-SA 3.0 US. Pre-built cache downloaded via `db update` (~216K wiki pages, ~105K genotype rows). The cache carries SNPedia's orientation metadata: minus-strand alleles are complemented before matching, while unknown-orientation palindromic genotypes abstain rather than risk a false match. If the database is absent, analysis runs without it. For commercial use, pass `--exclude-snpedia`. The cache can also be rebuilt from source via `scripts/scrape_snpedia.py` + `scripts/parse_snpedia.py`. |
@@ -344,11 +344,27 @@ If the failure is a network timeout on the same source repeatedly, the issue is
 
 Almost always a schema or interpreter version bump in a recent allelix release that invalidates the pre-bump cache. The fix is `allelix db update` — it'll re-ingest only the affected annotators (everything else signal-skips). See the relevant `CHANGELOG.md` entry for "Cache invalidation" notes per release.
 
-### Build mismatch warning when analyzing a known-good file
+### How the genome build is decided, and why a run can stop
 
-Either: (a) the file's header claims one build and the position data confidently indicates another (real-world MHG / Tempus exports do this — header says 37, positions are 38), or (b) the position signal is too small or mixed to be authoritative. Allelix requires at least three concordant seed SNPs and an 80% winning ratio. A VCF record without an rsID counts as a seed when it sits at that seed's position on a build, so variant-caller output with an empty ID column is detected by position too. Weaker GRCh37/38 evidence is reported as tentative and the header or fallback remains effective. A tentative GRCh36 winner is the safety exception: Allelix uses GRCh36 so it cannot accidentally query a modern position cache. Modern position-keyed caches are unavailable for that build (see [`docs/grch36-liftover.md`](https://github.com/allelix/allelix/blob/main/docs/grch36-liftover.md)).
+Before anything is annotated, Allelix decides the file's genome build from the evidence the file itself carries (ADR-0044):
 
-If you trust the file's header more than allelix's detection, force the build: `--build grch37` or `--build grch38`. The build banner in the analyze output will reflect what was actually used.
+- **VCF contig lengths.** Every nuclear chromosome has a different length in GRCh37 and GRCh38, so the `##contig` lengths settle the build whatever the contig names look like (`chr1` or `1`). If chrM has the old hg19 length, mitochondrial records are not annotated and a note says so.
+- **Known-SNP positions across the whole file.** A set of well-known SNPs sits at different positions in each build. Allelix reads the whole file for them before annotating (a few seconds on a full chip). At least three concordant positions and an 80% majority make the evidence confident (ADR-0037). A VCF record without an rsID counts when it sits at such a position.
+- **The file's own label** (a build line in an array header, or a VCF `assembly=`) is used only when the evidence does not contradict it.
+
+The banner says where the build came from, for example `Build: GRCh38 (from the contig lengths: 24 contig length(s) match GRCh38)`. If confident positions contradict the label (real-world MHG / Tempus exports say 37 and ship 38), Allelix uses the positions and prints a **Build mismatch** notice. An unlabelled chip whose known-SNP positions do not decide uses its format's documented default, with a visible note, provided at least one of those positions matches a build and the build most of them match is the default (a few that disagree do not stop it); the note gives the counts. A tentative GRCh36 winner is the safety exception: Allelix uses GRCh36 so it cannot query a modern position cache (see [`docs/grch36-liftover.md`](https://github.com/allelix/allelix/blob/main/docs/grch36-liftover.md)).
+
+**The run stops** instead of guessing when:
+
+- a VCF's contig lengths contradict its `assembly=`, contradict each other, or match no supported assembly;
+- weaker (tentative) position evidence contradicts the file's label, or points an unlabelled chip away from its default;
+- the known-SNP positions are tied between builds and the build that would otherwise decide (the label, the format default, or the contig-length build) is not one of them. When it is one of them, Allelix proceeds on it and prints an "inconclusive" warning, also shown in the HTML report. Without contig lengths, a tie that includes GRCh36 instead takes the GRCh36 safety exception described above, with the same warning;
+- a VCF has no contig lengths, no assembly and too few known-SNP positions;
+- a chip states no build and carries none of the known-SNP positions at all (for example an X-chromosome-only export, since they are all on autosomes);
+- the file has known-SNP positions but none of them sits at any supported build's coordinate, whether or not it states a build (contig lengths, when a VCF declares them, still decide);
+- contig lengths decided, but the known-SNP positions met while annotating point to the other build (for example a lifted-over file that kept its old header). The message says the annotation pass ran; nothing is written.
+
+The message names the evidence and asks you to say which build the file uses: `--build grch37` or `--build grch38`, or `--build grch36` for an old GRCh36 / hg18 file, which then runs with position-keyed lookups off (see [`docs/grch36-liftover.md`](https://github.com/allelix/allelix/blob/main/docs/grch36-liftover.md)). For `compare`, use `--build1` / `--build2`. A stop leaves no report, annotated VCF, diff, PLINK files or extract table behind. A forced build is recorded as such in every report.
 
 ### Is my database stale? How fresh is the data?
 
@@ -380,6 +396,7 @@ Notable load-bearing ADRs:
 - **ADR-0038 — GWAS effect-modifier disambiguation.** Only positively identified odds ratios receive an effect-size modifier; beta and ambiguous effects abstain.
 - **ADR-0042 — VCF quality gate.** The variant caller's FILTER and genotype quality are honoured, low-quality reference blocks are no-calls, and every exclusion is counted in the report.
 - **ADR-0043 — One rsID-recovery step.** Every command that needs rsIDs recovers them for rsID-less input through the same shared step; build detection votes by position instead.
+- **ADR-0044 — Evidence before labels.** The build is decided before annotation from contig lengths or whole-file known-SNP positions; evidence that contradicts the label, or no usable evidence, stops the run instead of producing a report on the wrong build.
 - **ADR-0041 — Plausibility flag.** Very rare homozygous calls and heterozygous calls with no gnomAD carriers are flagged for review, never suppressed.
 
 Release history: see [`CHANGELOG.md`](https://github.com/allelix/allelix/blob/main/CHANGELOG.md).
@@ -400,7 +417,7 @@ pytest
 
 The pre-commit hook enforces `ruff check` + `ruff format --check`. If a commit is blocked, fix the underlying problem rather than skipping the hook.
 
-For the full real-data release-validation battery — every parser format, VCF/gVCF, PLINK round-trip, edge cases, the GIAB/1000G corpus — see [`test_data/FULL_TEST_PROTOCOL.md`](test_data/FULL_TEST_PROTOCOL.md). That document is the project's real-data testing story; running `pytest` covers the fast suite that gates every commit.
+For the full real-data release-validation battery — every parser format, VCF/gVCF, PLINK round-trip, edge cases, the GIAB/1000G corpus — see [`test_data/FULL_TEST_PROTOCOL.md`](https://github.com/allelix/allelix/blob/main/test_data/FULL_TEST_PROTOCOL.md). That document is the project's real-data testing story; running `pytest` covers the fast suite that gates every commit.
 
 ## License
 

{allelix-2.4.0 → allelix-2.4.1}/allelix/__init__.py

@@ -10,8 +10,8 @@ from importlib.metadata import PackageNotFoundError, version
 def _read_pyproject_version() -> str | None:
     """Read the package version from ``pyproject.toml``.
 
-    fall back to ``pyproject.toml`` when run from a bare source
-    checkout (no editable install, no installed package metadata). Keeps
+    This is the fallback when run from a bare source
+    checkout (no editable install, no installed package metadata). It keeps
     ``--version`` and the outbound HTTP User-Agent reporting the real
     version string instead of the ``0.0.0+local`` sentinel that
     misidentifies our traffic to NCBI / EBI / HuggingFace.

{allelix-2.4.0 → allelix-2.4.1}/allelix/annotators/alphamissense.py

@@ -129,12 +129,16 @@ class AlphaMissenseAnnotator(Annotator):
             logger.warning("Could not remove staged file at %s", gz_path)
 
     def is_ready(self) -> bool:
-        """True when the AlphaMissense SQLite cache exists with current schema version."""
+        """True when the AlphaMissense SQLite cache exists with current schema version.
+
+        A cache with no ``local_version_tag`` is not ready: its schema version
+        is unknown, so it could pass as the current one after a bump. The
+        installer stamps the current version, so ``db update`` replaces it.
+        """
         info = get_database_info(self._db_path, "alphamissense")
         if info is None:
             return False
-        tag = info.get("local_version_tag") or ""
-        return tag == f"sv:{ALPHAMISSENSE_SCHEMA_VERSION}" or not tag
+        return info.get("local_version_tag") == f"sv:{ALPHAMISSENSE_SCHEMA_VERSION}"
 
     def version(self) -> str | None:
         """Return the cached database version, or None."""

{allelix-2.4.0 → allelix-2.4.1}/allelix/annotators/cadd.py

@@ -158,7 +158,9 @@ class CaddAnnotator(Annotator):
         """True when the active backend is available.
 
         In full mode, checks for the tabix file. In cache mode, checks
-        the SQLite database.
+        the SQLite database, which must carry the current schema stamp: a
+        cache with no ``local_version_tag`` has an unknown schema version, so
+        it is not ready and ``db update`` replaces it.
         """
         if self._full_mode:
             return (
@@ -168,8 +170,7 @@ class CaddAnnotator(Annotator):
         info = get_database_info(self._db_path, "cadd")
         if info is None:
             return False
-        tag = info.get("local_version_tag") or ""
-        return tag == f"sv:{CADD_SCHEMA_VERSION}" or not tag
+        return info.get("local_version_tag") == f"sv:{CADD_SCHEMA_VERSION}"
 
     def version(self) -> str | None:
         """Return the cached database version, or None."""

{allelix-2.4.0 → allelix-2.4.1}/allelix/annotators/clinvar.py

@@ -153,7 +153,7 @@ def _collapse_identical_scvs(annotations: list[Annotation]) -> list[Annotation]:
     surface, and collapsing them would be the Frankenstein-pair
     regression the per-SCV loader retired.
 
-    cross-PR review (Finding 1): ``alt`` is in the key for the
+    ``alt`` is in the key for the
     wrong-allele safety invariant. Two SCVs at a multi-allelic site
     can share (significance, condition, gene) but differ in alt — e.g.
     rs1065852 (G→A drug_response/Codeine_response + G→C drug_response/
@@ -283,7 +283,7 @@ class ClinVarAnnotator(Annotator):
     def setup(self) -> None:
         """Download the per-SCV TSV pair once and ingest both builds from it.
 
-        v2.2 stage B: the VCF-per-build path is replaced by the
+        Since v2.2 the VCF-per-build path is replaced by the
         variant_summary + submission_summary TSV pair. variant_summary
         carries per-(VariationID, Assembly) rows so the same downloaded
         file populates both GRCh37 and GRCh38 caches with no second
@@ -445,7 +445,7 @@ class ClinVarAnnotator(Annotator):
         # may have BOTH SNV and indel rows for the same rsid; the WHERE
         # filters those out so we keep only the SNV REF.
         #
-        # item 1: iterate the cursor directly instead of fetchall()
+        # Iterate the cursor directly instead of fetchall()
         # so peak memory is one row + the dict, not the entire result set
         # twice.
         cursor = conn.execute(
@@ -463,8 +463,8 @@ class ClinVarAnnotator(Annotator):
     def fetch_remote_signal(self) -> str | None:
         r"""Freshness signal derived from the per-SCV submission_summary md5.
 
-        v2.2 stage B: pre-stage-B this returned a composite VCF-md5
-        per build. After stage B, the cache is built from a build-agnostic
+        Before v2.2 this returned a composite VCF-md5 per build. Since
+        v2.2, the cache is built from a build-agnostic
         TSV pair, and submission_summary's md5 endpoint is the change
         cadence we want to track (per-SCV submissions land daily; the
         slower-moving variant_summary only adds new VariationIDs).
@@ -500,7 +500,7 @@ class ClinVarAnnotator(Annotator):
         None if any managed build's cache is absent / unstamped or if the
         builds' stamps diverge (an interrupted partial reingest).
 
-        Stage B: both builds now share the same source TSVs and therefore
+        Since v2.2 both builds share the same source TSVs and therefore
         the same remote_signal. We still cross-check that EVERY managed
         build's cache carries the stamp; a missing build means the
         last-setup didn't complete, treat as "no signal" and let
@@ -699,7 +699,7 @@ class ClinVarAnnotator(Annotator):
           input). Together with the locus this identifies the variant by
           ``(chrom, pos, ref, alt)`` rather than by rsID.
         - ADR-0011: ClinVar indels never match single-base array calls.
-        - ADR-0035 PR 4 / ADR-0007: the user carries the ALT, directly or
+        - ADR-0035 / ADR-0007: the user carries the ALT, directly or
           via a confirmed strand flip.
         - Benign rows are suppressed unless ``include_benign``.
 

{allelix-2.4.0 → allelix-2.4.1}/allelix/annotators/gnomad.py

@@ -114,12 +114,10 @@ class GnomadAnnotator(Annotator):
     def is_ready(self) -> bool:
         """True when the gnomAD SQLite cache exists with current schema version.
 
-        a cache with no ``local_version_tag`` used to be accepted
-        as ready (the previous ``or not tag`` escape). That defeated the
-        whole point of ``GNOMAD_SCHEMA_VERSION``: if it ever gets bumped,
-        every tagless legacy cache would silently pass as the new
-        version. Reject tagless caches so the user is told to re-run
-        ``db update``.
+        A cache with no ``local_version_tag`` is not ready. Accepting it
+        would defeat ``GNOMAD_SCHEMA_VERSION``: after a bump, every
+        untagged legacy cache would silently pass as the new version.
+        Rejecting it tells the user to re-run ``db update``.
         """
         info = get_database_info(self._db_path, "gnomad")
         if info is None:

{allelix-2.4.0 → allelix-2.4.1}/allelix/annotators/gwas.py

@@ -26,6 +26,7 @@ from allelix.databases.manager import (
     download,
     get_database_info,
     head_request_headers,
+    parse_baked_version,
 )
 from allelix.models import Annotation
 
@@ -57,7 +58,7 @@ logger = logging.getLogger(__name__)
 
 _BATCH_CHUNK = 500  # SQLite default SQLITE_MAX_VARIABLE_NUMBER is 999
 
-# ADR-0035 PR 3: PheCode often arrives embedded in the upstream DISEASE/TRAIT
+# ADR-0035: PheCode often arrives embedded in the upstream DISEASE/TRAIT
 # field (e.g. ``"Type 2 diabetes (PheCode 250.2)"``). The annotator extracts it
 # at the boundary so downstream code reads ``Annotation.phecode`` as a
 # structured field instead of regex-parsing prose. The trimmed trait flows into
@@ -504,8 +505,11 @@ def _stamp_existing_gwas_cache(db_path: Path) -> bool:
     """One-shot migration: stamp ``local_version_tag`` on a GWAS cache.
 
     Handles legacy caches with ``|cv:N`` baked into ``remote_signal``
-    by moving the tag and cleaning the signal. Returns True if the
-    current categorizer version is now stamped.
+    by moving the tag and cleaning the signal, but only when ``N`` is the
+    current categorizer version. A cache without the marker, or with
+    another ``N``, has unknown or old data: it is left unstamped and the
+    caller re-ingests or re-downloads it. Returns True if the current
+    categorizer version is now stamped.
     """
     if not db_path.exists():
         return False
@@ -523,6 +527,8 @@ def _stamp_existing_gwas_cache(db_path: Path) -> bool:
                 return True
             if existing_tag is not None:
                 return False
+            if parse_baked_version(sig, "cv") != _CATEGORIZER_VERSION:
+                return False
             clean_signal = (sig or "").split("|cv:")[0]
             conn.execute(
                 "UPDATE database_versions "

{allelix-2.4.0 → allelix-2.4.1}/allelix/annotators/pharmgkb.py

@@ -122,9 +122,9 @@ class PharmGKBAnnotator(Annotator):
         per-allele function table is the secondary fallback for rsids
         ClinVar doesn't catalog.
 
-        The ZIP is retained on disk so ``is_ready()`` can auto-reingest
-        when the interpreter version bumps — mirroring the GWAS TSV
-        retention pattern.
+        This is also how a cache built by an older interpreter version is
+        rebuilt: ``is_ready()`` reports it stale and ``db update`` calls
+        this, so the CPIC table is fetched again with the annotations.
         """
         url = PHARMGKB_CLINICAL_URL
         signal = self.fetch_remote_signal()
@@ -162,13 +162,15 @@ class PharmGKBAnnotator(Annotator):
     def is_ready(self) -> bool:
         """True iff a ClinPGx SQLite cache exists with current schema and interpreter stamp.
 
-        When the interpreter version has bumped and the raw ZIP is still
-        on disk (retained since the last ``db update``), auto-reingests
-        from the cached ZIP using the existing CPIC allele-function data —
-        mirroring the GWAS auto-reingest pattern.
+        Never touches the network, so ``analyze`` stays offline. When the
+        interpreter version has bumped, the cache is not ready and
+        ``allelix db update`` rebuilds it, fetching the ClinPGx annotations
+        and the CPIC allele-function table again (``setup``).
 
-        Pre-mechanism caches (tag missing or baked into ``remote_signal``)
-        are self-healed with a one-shot stamp update.
+        Pre-mechanism caches (tag missing, version baked into
+        ``remote_signal``) are self-healed with a one-shot stamp update
+        when the baked version is the current one; otherwise they are not
+        ready either.
         """
         info = get_database_info(self._db_path, "pharmgkb")
         if info is None:
@@ -178,9 +180,7 @@ class PharmGKBAnnotator(Annotator):
         tag = info.get("local_version_tag") or ""
         if tag == f"iv:{PHARMGKB_INTERPRETER_VERSION}":
             return True
-        if not tag:
-            return _stamp_existing_pharmgkb_cache(self._db_path)
-        return _reingest_pharmgkb_from_cached_zip(self._db_path, self.data_dir)
+        return not tag and _stamp_existing_pharmgkb_cache(self._db_path)
 
     def version(self) -> str | None:
         """Cached database version (download date, or version supplied to load)."""
@@ -199,7 +199,7 @@ class PharmGKBAnnotator(Annotator):
             self._conn = None
 
     def fetch_remote_signal(self) -> str | None:
-        """Composite freshness signal for ClinPGx + CPIC (M-2, ADR-0020).
+        """Composite freshness signal for ClinPGx + CPIC (ADR-0020).
 
         The signal format is `pgkb:<pgkb-signal>|cpic:<cpic-signal>`.
 
@@ -269,7 +269,7 @@ class PharmGKBAnnotator(Annotator):
         if is_clinvar_homref(variant, self._clinvar_ref_provider):
             return []
 
-        # ADR-0035 PR 4: fetch all rows for the rsid (typically <5) and apply
+        # ADR-0035: fetch all rows for the rsid (typically <5) and apply
         # strand-aware genotype match in Python. Forward-stranded users hit
         # the same set of rows as the v0.7-era ``WHERE genotype = ?`` SQL;
         # reverse-stranded users now also match when Variant.ref confirms
@@ -402,7 +402,7 @@ class PharmGKBAnnotator(Annotator):
                     _score,
                     pgkb_annotation_id,
                 ) = row
-                # ADR-0035 PR 4: strand-aware genotype match. See annotate() for
+                # ADR-0035: strand-aware genotype match. See annotate() for
                 # the safety rationale (palindrome guard + variant.ref orientation).
                 if not strand_aware_genotype_match(
                     variant.allele1,
@@ -458,12 +458,15 @@ def _stamp_existing_pharmgkb_cache(db_path: Path) -> bool:
     """One-shot migration: stamp ``local_version_tag`` on a ClinPGx cache.
 
     Handles legacy caches with ``|iv:N`` baked into ``remote_signal``
-    by moving the tag and cleaning the signal. Returns True if the
-    current interpreter version is now stamped.
+    by moving the tag and cleaning the signal, but only when ``N`` is the
+    current interpreter version. A cache without the marker, or with
+    another ``N``, has unknown or old data: it is left unstamped and the
+    caller re-ingests or re-downloads it. Returns True if the current
+    interpreter version is now stamped.
     """
     import contextlib
 
-    from allelix.databases.manager import _ensure_local_version_tag_column
+    from allelix.databases.manager import _ensure_local_version_tag_column, parse_baked_version
 
     if not db_path.exists():
         return False
@@ -480,6 +483,10 @@ def _stamp_existing_pharmgkb_cache(db_path: Path) -> bool:
             sig, existing_tag = row
             if existing_tag == tag:
                 return True
+            if existing_tag is not None:
+                return False
+            if parse_baked_version(sig, "iv") != PHARMGKB_INTERPRETER_VERSION:
+                return False
             clean_signal = (sig or "").split("|iv:")[0]
             conn.execute(
                 "UPDATE database_versions "
@@ -491,57 +498,3 @@ def _stamp_existing_pharmgkb_cache(db_path: Path) -> bool:
         return True
     except (sqlite3.OperationalError, sqlite3.DatabaseError):
         return False
-
-
-def _read_cached_cpic_lookup(db_path: Path) -> dict[tuple[str, str], str]:
-    """Extract the CPIC allele-function table from an existing ClinPGx cache."""
-    import contextlib
-
-    lookup: dict[tuple[str, str], str] = {}
-    try:
-        with contextlib.closing(sqlite3.connect(db_path)) as conn:
-            rows = conn.execute(
-                "SELECT rsid, allele, function_class FROM pharmgkb_allele_function"
-            ).fetchall()
-            for rsid, allele, function_class in rows:
-                lookup[(rsid, allele)] = function_class
-    except (sqlite3.OperationalError, sqlite3.DatabaseError):
-        pass
-    return lookup
-
-
-def _reingest_pharmgkb_from_cached_zip(db_path: Path, data_dir: Path) -> bool:
-    """Re-ingest ClinPGx from the retained ZIP when the interpreter version bumps.
-
-    Reads the existing CPIC allele-function data from the current cache
-    before replacing it — no network required for the reingest. Preserves
-    the original source URL and version from the previous cache.
-    """
-    zip_path = data_dir / "clinicalAnnotations.zip"
-    if not zip_path.exists():
-        return False
-    info = get_database_info(db_path, "pharmgkb")
-    if info is None:
-        return False
-    old_signal = info.get("remote_signal") or ""
-    old_version = info.get("version") or ""
-    old_source_url = info.get("source_url") or ""
-    cpic_lookup = _read_cached_cpic_lookup(db_path)
-    logger.info("ClinPGx interpreter changed — re-ingesting from cached ZIP...")
-    try:
-        load_pharmgkb_tsv(
-            zip_path,
-            db_path,
-            source_url=old_source_url,
-            version=old_version,
-            remote_signal=old_signal,
-            allele_function_lookup=cpic_lookup,
-            min_rows=PHARMGKB_MIN_ROWS,
-        )
-    except Exception:
-        logger.warning("Auto-reingest from cached ZIP failed", exc_info=True)
-        return False
-    new_info = get_database_info(db_path, "pharmgkb")
-    if new_info is None:
-        return False
-    return (new_info.get("local_version_tag") or "") == f"iv:{PHARMGKB_INTERPRETER_VERSION}"