Skip to content

Roadmap history — the items that shipped

Split out of ROADMAP.md, which is forward-only: it now carries active work and nothing else. This file keeps the rationale of every RMn that shipped from the 0.6 line onward — and, since 2026-08-21, of the ones closed by a decision not to do them, which leave the active file for the same reason and are just as worth not re-deriving — the earlier ones are in the archive named below — because a lot of it is reasoning worth not re-deriving, including one entry that corrects an argument it originally made.

  • CHANGELOG.md is the release record: what changed, newest first, shared across the ecosystem repos. This file is the roadmap-item view of the same events.
  • RM_TOC.md is the complete index of every RMn, active and shipped.
  • COMPILER.md carries the per-feature coverage table.

RM1, RM2, RM3, RM8, RM9, RM18 and RM19 also shipped, but their entries live in USE_CASES.md § Roadmap items surfaced — where they were derived — and were never duplicated here.

The 0.5 line and everything before it moved to ROADMAP_HISTORY_PRE_0_6.md on 2026-08-17 — the release narratives through 0.5.0, and every RMn that shipped before 0.6.

The 0.6 line moved to ROADMAP_HISTORY_0_6.md on 2026-09-12, when 0.7.0 was cut and published — every RMn that shipped in a 0.6 number, and the rounds that produced them. This file starts at the 0.7 build round. The boundary is the v0.6.6 tag read off git show, never a date: three rounds dated 2026-08-21 shipped in 0.7.0 rather than in 0.6.6. RM_TOC.md indexes all three halves plus the open roadmap, so it is where to look an item up.

The 0.8.x patch line

Patches on main after the 0.8.0 cut (2026-11-05), newest first.

RM452 — a NULL start raises TypeError in the Ensembl rsID scan and in the position back-fill

SHIPPED 2026-11-18 on main, cut 2026-11-18 as v0.8.9 — a patch. Severity low · Owner enricher (resolver._lookup_positions_by_rsid, resolver._lookup_rsid_candidates) · Motivating case the RM431 builder on 0.9 (recorded under RM431, 08a83122; the pm, 2026-11-18: "predates 0.9, a patch on main, triage's") · related RM271, RM381

What was seen. A synthetic split-core row ("1", NULL, "A", "G", "rs2100212723") made lookup_loci raise TypeError: int() argument must be … not 'NoneType' at _lookup_positions_by_rsid's int(start). The back-fill _lookup_rsid_candidates has the same read for a probe: it drops a probe with no start from the query (concrete), but its result loop still calls int(start) when the probe has a chrom. So it raises whenever another probe in the call is whole. No published Ensembl release on this machine carries a NULL start (ensembl-variation-2026_07_13-vep116.0: 0 rows, read 2026-11-18), so this guards against a defect in the data, and no module has met it.

Built (triage, 2026-11-18). The scan leaves a row with no chrom or start out of the answer. An rsID named only on such rows is said in one warning and never read as an answer, so the chain asks its next link, which an absence must not foreclose (@unreachable-not-absent). The back-fill gives a probe with no start no candidates, as it already gave one with no chrom. Tests in test_a_null_start_places_nothing.py: the builder's repro as it ran, a placed row beside an unplaced one, and the back-fill's probe. All three fail on origin/main (dae4e0c8) with the reported TypeError.

Class. A patch: no schema, column, code or vocabulary moves (P3). Severity low: no real snapshot carries the shape.

Residuals none

RM451 — reverse writes a resolution row from the cells of a coordinate row the table never filed, so compile → reverse → compile moves resolution_signature

SHIPPED 2026-11-18 on main, cut 2026-11-18 as v0.8.9 — a patch. Severity low · Owner compiler (compiler/reverse._write_resolution_csv, the cell rebuild) · Motivating case the lead's 0.8.9 run (2026-11-18): restoring pathogenic_clinvar's coordinate row 11:5226762 C>CAAAG (RM449's remedy) broke test_reference_example_round_trips_to_a_fixed_point[pathogenic_clinvar] · related RM364, RM380, RM449

What was seen, and that it is not RM449's. The restored row validates and compiles under --strict, but a lap moves resolution_signature and vrs_alleles 531 → 532. Reverse wrote a row keyed 11:5226762:C:CAAAG, rebuilt from the row's own cells, that the injected table did not have, and lap 2 read it. The example's table was enriched before the row came back, so nothing filed it: its parquet row carries no resolution_loci, and _write_resolution_csv falls back to the cell rebuild meant for a parquet compiled before RM364. The same happens with no mirrored site at all. A two-row module (an rsID row the table files, and ,1,1000,C,T,C/T it does not) fails reconstructed_projection equality across one lap, and reverse's table gains ga4gh:VA.pPch…. After one offline enrich pass the table files the restored row and all four pathogenic_clinvar round-trip tests pass (checked on a scratch copy, 2026-11-18). Every reference example is enriched, which is why the suite never met it.

Shape of a fix (the builder decides). A parquet compiled since RM364 says what the table filed under each key; an empty resolution_loci there means "the table filed nothing", not "compiled before the column". Reverse should then write nothing for that key, and fall back to the cell rebuild only for a parquet without the column. Test: the two-row module above, one lap, projection equal.

Class. A patch: no schema, column or vocabulary moves (P3). Severity low: the artifact's digest and content_signature hold, only the table's signature moves, and an enrich pass (which closing needs anyway) removes it.

Sized (the pm, 2026-11-18). Agreed that it predates RM449: a module whose table files every coordinate row is a fixed point, and closing needs that enrich pass anyway. The builder's shape and test above.

Built (triage, 2026-11-18). The shape above, corrected on the way: an empty resolution_loci already meant "the cells answer" (RM364's saving) as well as "filed nothing", so the two had to be written apart, not read apart. parquets.resolution_loci returns [] when a table was read and the key holds no positioned locus on the module's build (a key filed only as not_found included, since reverse never writes one back). table_read is InjectedResolution.consulted, threaded through _build_weights and with_resolution_loci. It is never "the table has rows": reverse hands an empty table back header-only, and lap 2 must write [] where lap 1 did. The round-trip matrix's not_found and table-says-more cases caught a first draft that read it from the dict. reverse._filed_nothing skips such a row in both loops. Null still means the cells answer, and the cell rebuild still writes those. Tests in test_an_unfiled_coordinate_row_round_trips.py:

  • the two-row module laps to an equal projection, with nothing invented;
  • a module that read no table laps unchanged;
  • pathogenic_clinvar as the restore stood before its enrich pass (the committed example with the row's table entry taken out) laps on digest, content and projection.

The first and last fail on aa5b88f7. The example sweep moves one digest, cyp2c9_warfarin_grch37: its 12 unfiled pharm_variants rows now say [], reverse gives back the same five table rows, and the CHANGELOG declares the byte change.

Residuals none

RM449 — an rsID row's indel genotype is hosted by an insertion and a deletion at one position, so its claim lands on both events

SHIPPED 2026-11-18 on main, cut 2026-11-18 as v0.8.9 — a patch, a declared corrected derivation. Severity high · Owner compiler (the positional fill and hosting_verdict), enricher (the ClinVar drafter) · Motivating case S158's first question (the registry, 2026-11-17/18): 21 post-resolution: Duplicate (variant, genotype) refusals in cardio, 25 or more in cancer and 14 or more in pathogenic, all indels · related RM31, RM267, RM274, RM381

Reproduced on main (5ff00802, 2026-11-18), two cases with this machine's caches, enriched online with verify_ref.

  • Loud. variants.csv holds rs1057516393 … C/CT (rsID only, drafted from ClinVar VCV 370313, the insertion) and 11,108256251,CT,C, C/CT (a coordinate row, from VCV 3653980, the deletion). The rsID resolves to two loci, 11:108256251 C>CT (placement_verdict=same_event, ClinVar witnessed) and CT>C (unplaced). C/CT is hosted at both, the fill expands the rsID row onto both, and the second expansion's key is the coordinate row's: the strict compile refuses with Duplicate (variant, genotype): (11:108256251:CT:C, C/CT).
  • Silent. The same rsID row alone, with a study row. The strict compile succeeds, and weights.parquet holds the insertion's claim (conclusion=ins, pathogenic in the module) on both C>CT and CT>C. A consumer carrying the heterozygous one-base deletion matches the insertion's annotation. Nothing warns.

Why, and which decision this reopens. RM31's hosting rule (@hosting-tri-state) compares the raw strings first. It relies on "a genotype naming two alleles carries the frame", because an rsID row states no coordinate. Here both strings occur in both frames with opposite meanings. On C>CT, C/CT is one inserted T; on CT>C it is one deleted T. That premise fails for an insertion and a deletion mirrored at one position, so hosting answers "yes" twice for one authored event. ClinVar settles which one was meant: the rsID is on VCV 370313, the insertion, and the deletion's record carries no rsID.

The reporter's three candidates, weighed. (2), an authored coordinate row winning over the expansion, silences only the loud case; the silent one stays. (3), the ClinVar drafter writing the coordinate for an indel rsID row, removes the ambiguity at the source for new drafts. It does nothing for modules already drafted, three of them in production. (1), treating a genotype hosted by both spellings at one position as ambiguous and taking the locus a witness placed as same_event, else neither, fixes both cases for existing modules. It withholds rather than guesses where no witness settles it. The recommendation is (1) with (3) beside it; the builder decides.

Class. A corrected derivation (P3): the fill writes fewer rows for a module already compiled, so artifact.digest moves, and the release must declare the correction. RM31's raw-first rule says normalization may only add acceptances. This item removes one, on purpose, for a case that rule did not consider, and says so where the rule is written. The one-to-many reverse must stay a fixed point (P7): the expansion it drops must not come back on lap two. Severity high: a silent wrong annotation on an indel, in production modules.

Sized (the pm, 2026-11-18). A patch on main: a corrected derivation may ship in any release, never silently (P3), so 0.8.9's notes declare it, readable offline, naming what moves (the fill writes no row on the locus a mirrored indel genotype was wrongly expanded onto, and artifact.digest moves for a module holding one). Candidate (1) with (3) beside it, the more complete reading:

  1. A genotype hosted by both an insertion and a deletion at one position is ambiguous. The fill takes the locus the recorded placement_verdict says is same_event, else neither, with a warning naming the rsID and both events. The verdict is read from resolution.csv, so the compile stays offline (P2). Its cost, stated in the notes: a module enriched offline, where no indel is judged, loses such a row until it is enriched online.
  2. The ClinVar drafter writes the coordinate on an indel rsID row, so new drafts carry the frame.
  3. The rule's change is written where RM31's is (@hosting-tri-state in AGENT_NOTES.md and its CLAUDE.md line): raw-first may now remove an acceptance, for this case only.

Tests: the loud and the silent case above as fixtures; a reverse, recompile, reverse lap that is a fixed point (P7); and a sweep over reference_examples/ listing every row whose expansion moves, read before the cut. Built first, before RM448: it is the silent wrong annotation.

The sweep's case, decided (the pm, 2026-11-18, from triage's build). Every multi-locus expansion in reference_examples/ is a mirrored insertion and deletion pair: 13 sites in hboc_palb2 and pathogenic_clinvar. At 11 of them ClinVar files both spellings under the one rsID, each same_event (the HBB frameshifts both ways); at 2 only the deletion (rs80356821, rs193922563). "same_event, else neither", read literally, fills neither at the 11, so both examples would refuse under strict. Decided:

  1. At a mirrored site the fill takes every witnessed spelling and drops the unwitnessed ones; none witnessed fills neither (triage's B). The two one-sided sites move, S158's rs1057516393 and the registry's superhuman@2.4.1 rs766212849 settle to the witnessed spelling, and a site witnessed both ways keeps both.
  2. A site witnessed both ways is never silent. The fill warns in both modes, once per rsID, naming both events and saying that an rsID row there claims both and that a coordinate row picks one (@unreachable-not-absent's "warn in both modes"; @warning-code-names-the-finding). It does not escalate under strict in 0.8.9.
  3. Rejected for 0.8.9: refusing a both-witnessed rsID row until it is re-authored with coordinates (triage's A). It is the stricter reading of @rsid-not-per-allele, but it would make modules that compile today refuse in a patch, the two examples and at least one production module among them, while the drafter's coordinate (3 above) fixes new drafts only. Escalating the warning of 2 is that change, and can be taken in a minor if the maintainer wants it; the warning's count is the evidence for it.

The registry's two published cases go into the tests: superhuman@2.4.1 rs766212849 (A/A, protective, compiled on both A>AAACTT, where it is the reference homozygote, and AAACTT>A, where it is a homozygous deletion) and the polygon's thrombophilia@2.0.1 rs1572088853 (C/CC). Of 69 latest versions compiled by 0.8.x, these are the 2 that carry a claim on the other spelling (the registry's lead, 2026-11-18).

Built (triage, 2026-11-18). Candidate (1) as the pm's B, plus (3).

  • The fill (resolution._settle_mirrored_spellings, called in resolve_from_table right after _hostable_loci). Among an rsID row's hosting loci, a position holding both an insertion and a deletion is settled by placement_verdict. The spellings witnessed same_event are filled and the rest are not. Witnessed both ways, both stay, and one rsid_genotype_reads_as_two_events sentence per rsID names both events and says a coordinate row picks one. Witnessed neither way, neither is filled and the row stays unpositioned. Every arm warns under that one new code, in both modes, never escalated. A, refusing the both-ways site, is rejected for the patch and left to a minor that would escalate this warning (the pm, c172667a). Other positions (a paralog, a PAR partner) and non-mirrored sites keep @membership-union's expansion. A mirror needs each spelling to host the genotype on its own: a compound het in a padded frame (G/GTTT on GTT>G and G>GT) names one allele of each, no locus hosts it alone, and it keeps both pieces (test_split_snapshot_per_alt caught the first draft, which settled it).
  • The drafter. clinvar_draft.is_indel_record sends every indel record through the coordinate identity, as multi_allelic_rsids already did for a multi-allelic rsID. Its study row follows it, and a re-draft names an older rsID-only indel row through _superseded_rsid_rows.
  • Tests. test_a_mirrored_indel_genotype_names_one_event.py has eight tests:
  • S158's silent and loud cases;
  • the registry's two published cases at their real places (superhuman@2.4.1 rs766212849 A/A, and thrombophilia@2.0.1 rs1572088853 C/CC, where ClinVar files only the deletion);
  • the neither case under strict;
  • the both-ways case and its once-per-rsID sentence;
  • a compile-reverse-compile lap with equal artifact.digest and content_signature.

Five of them fail on the code before the fix. A drafter test drafts S158's pair. The MLH1 re-draft test now also turns the indel rule off for its stale draft. - The reference-examples sweep, every row that moves. All 22 examples were compiled before and after. Two rows move, both in pathogenic_clinvar: rs80356821 (C/CAAAG) and rs193922563 (a 25-base C/C…A). Each is now filled on the deletion ClinVar witnessed and no longer on the mirrored insertion. The 11 other mirrored sites in pathogenic_clinvar and hboc_palb2 are witnessed both ways and keep their expansion, now with the warning. Every test reading the examples is green. - For the pm's read before the cut. pathogenic_clinvar's README ("One authored edit") records that the coordinate-only row 11:5226762 C>CAAAG was removed, because the rs80356821 row's expansion collided with it and "the rsID row now carries both events". After this item the rsID row no longer carries the insertion, so the example states nothing about C>CAAAG. Restoring the removed row, with its studies.csv row, would bring the claim back without a collision. That moves content_signature and needs the module closed again, so it is left as a decision, not done here.

The example's removed row comes back in 0.8.9 (the pm, 2026-11-18). pathogenic_clinvar removed the coordinate row 11:5226762 C>CAAAG (ClinVar Variation 3572115, the pathogenic HBB insertion) at the 0.8 regeneration, because rs80356821's expansion collided with it. After RM449 that rsID fills only the witnessed deletion, so the example now states nothing about the insertion. The row and its studies.csv row are restored, which is the remedy RM449's warning names (a coordinate row picks the event); the README's 0.8 paragraph says why, and the module is closed again. content_signature moves on a reference example that nothing publishes.

0.8.9 waits for both build defects (the pm, 2026-11-18, from the lead's full suite). (1) One enricher test fails on the block and passes without it (test_clinvar.py::test_a_record_the_genotype_cannot_host_is_left_out_of_the_table: rs777 left unresolved under strict). (2) The restored example is not a fixed point: with the coordinate row back, compile, reverse, compile moves resolution_signature and vrs_alleles (531 to 532). Before RM449 that row was refused as a duplicate, so the instability is RM449's, and its own warning recommends exactly that row. Both are defects of this build, so RM449 is not done until both pass, and the restored pathogenic_clinvar row is the P7 fixture for the second. If the lap fix outgrows half a day, RM448 ships alone as 0.8.9 once (1) is shown not to be its, and RM449 follows as 0.8.10. A re-close after the restore needs an enrich pass first, since close drops verification.json's enrich records when the module hash moves.

The two build defects the lead's run found (2026-11-18), and what each was.

  • test_clinvar's rs777: a ClinVar fill, offline, records no placement_verdict, and the first build read "no verdict" as "witnessed neither" and left the row unpositioned. Not asked is not witnessed-neither. A mirrored site with no verdict anywhere now keeps the expansion it had before, and says so once per rsID (same code, "no second source was asked"). Neither is filled only where a witness was asked and placed neither. There is a test for it.
  • The lap that broke on the restored pathogenic_clinvar row is not this item's: it is a coordinate row the table never filed, and it breaks a lap with no mirror anywhere. Filed as RM451. An enrich pass removes it, and the four round-trip tests then pass on the restored example. Every remedy sentence now says to re-run the enricher after authoring the coordinate.
  • A third, from the lead's re-run after the restore (aa5b88f7, test_reproduced_locus_compares_every_rebuilt_column): with the verdicts stripped, the not-asked arm expanded rs80356821 onto the restored coordinate row again, and --strict refused Duplicate (variant, genotype). So the remedy refused wherever no verdict was recorded. Now an authored coordinate row wins: an expansion member re-keyed onto its exact (variant_key, genotype) is not filled, and rsid_genotype_reads_as_two_events names it (the pm, 05addf11). Tests: S158's loud case with no verdicts, and pathogenic_clinvar with every placement verdict stripped, compiled strict and lapped. Both fail on aa5b88f7. Scoped to a mirrored site, RM449's own (_mirrored_sites): an expansion colliding with an authored row anywhere else, a paralog's other copy, still refuses as the duplicate it is, which test_one_verdict pins (expansion_collides_with_an_authored_row). The first cut applied it to every expansion and that test caught it.

Both resolved (the pm, 2026-11-18, 84a256ef). (1) was RM449's: an offline ClinVar fill records no verdict, and no verdict was read as witnessed by neither. Not asked is not witnessed-neither (@unreachable-not-absent), so a mirrored site with no verdict anywhere keeps its expansion, under the same warning. (2) predates RM449 and is RM451: one offline enrich pass files the restored row and the four round-trip tests pass, so 0.8.9 waits for neither. The warning's remedy now says "and re-run the enricher".

A third build defect, and 0.8.9 waits for it (the pm, 2026-11-18, from the lead's suite at aa5b88f7). With the example's row restored, a table with no placement verdict (an older enricher's, an offline fill, a hand-written one; test_a_version_with_no_id_survives_the_round_trip[pathogenic_clinvar] strips the provenance columns) expands rs80356821 onto the insertion again, and strict refuses Duplicate (variant, genotype): (11:5226762:C:CAAAG, C/CAAAG). So the remedy RM449's warning names refuses whenever the verdict is absent. Decided: an authored coordinate row wins over an rsID row's expansion onto its exact (variant, genotype) key. The expansion is dropped there, and RM449's warning names it, so nothing is silent; the coordinate row is the author's narrower statement of that event, which is what the warning asked for. The test that failed is the fixture, plus a lap with the verdicts stripped. RM449 is a defect of this build until it passes; the half-day fallback above still stands.

Two calls before the 0.8.9 cut (the pm, 2026-11-18, from the lead's cut branch).

  1. The warning code waits for 0.9; the warning ships in 0.8.9 uncoded. warnings_summary validates its keys against the closed VALID_WARNING_CODES, so a reader on just-dna-format 0.8.6 refuses a 0.8.9 manifest that carries rsid_genotype_reads_as_two_events (measured on hboc_palb2). Every code added in the 0.8 line was added in the minor, where INTEGRATION_0_8 § 1 tells a consumer to raise its format floor with it; a patch carries no such instruction, and main is patch scope only. The warning's text and its pinned phrase ship unchanged, and 0.9 adds the code and its INTEGRATION row. Rejected: shipping the code with a documented floor raise, which makes a patch an old-reader break for every consumer reading a module that triggers it. Amended the same night (the lead's build): an uncoded warning cannot ship, because findings.classify in the format tier refuses a channel where some warnings carry no code, and every triggering module has coded ones. So 0.8.9 borrows the nearest existing codes, the 0.8 line's "no new code" idiom, by what the row became: where the fill writes no position, rsid_no_hosting_locus ("the position remains unset", word for word); where it fills one or more loci (both spellings kept, or one dropped as unwitnessed or under an authored coordinate row), rsid_expanded_to_multiple_loci ("one authored row became several, because the source says so"). The message text is RM449's own in every arm. The cost, stated in the cut entry: until 0.9, a site narrowed to one locus is counted in warnings_summary as an expansion. 0.9 adds rsid_genotype_reads_as_two_events and moves these sentences to it. Rejected: one borrowed code for every arm (it miscounts the filled arms as unplaced), withholding warnings_summary on a mixed channel, a partial summary, and the floor raise above.
  2. A recorded undecided on both spellings reads as no verdict, fixed before the cut. An offline run writes undecided, which says the second source could not judge, not that it witnessed neither (@unreachable-not-absent; the same reading as 84a256ef's for a missing verdict). Such a site keeps its expansion under the warning, as the CHANGELOG already says, so an offline re-derivation never turns a module that compiled into a strict refusal. The test: the example enriched offline, compiled strict.

Confirmed: the corrected derivation's reach is stated by compilation.expanded_keys in the release record, and RM451 is declared an addition whose reach is unstated where a header-only resolution.csv leaves expanded_keys null.

Cut now, with one offline case stated (the pm, 2026-11-18, from the lead at b9b4f8c7). A real enrich --offline of pathogenic_clinvar writes no undecided; 12 of its 13 mirrored sites match the online table, but rs80356821 comes out unplaced on both spellings where online places the deletion same_event, so strict refuses that row under "witnessed neither". Offline nothing can judge an indel, so a definite unplaced there is likely the offline witness answering where it could not ask (@unreachable-not-absent), a placement defect RM449 exposed rather than made. 0.8.9 is cut now: it fixes a silent wrong annotation in production modules, and this case is loud, names its rsID, needs an offline re-derivation of a mirrored indel site, and an online one clears it. The cut entry says so. Triage files the offline placement as its own item, a patch for 0.8.10.

Residuals RM453 · won't fix — a site witnessed both ways is not refused in 0.8 (the pm: refusing it is a minor's question, by escalating rsid_genotype_reads_as_two_events) · won't fix — an authored coordinate row winning over the expansion (S158's option 2) silences only the loud case

RM448 — the placement witness reads another ALT of a multi-allelic indel site as a disagreement, so the whole placement is withheld and the rsID is left with no row

SHIPPED 2026-11-18 on main, cut 2026-11-18 as v0.8.9 — a patch. Severity high · Owner enricher (placement.compare_placements, events.counterparts) · Motivating case S158's second question (the registry, 2026-11-17/18): 12 rsIDs of the production pathogenic module, and rs1452575772 in cardio, re-derived with no resolution.csv row, so strict refuses them as unresolved · related RM267, RM375, RM381

Reproduced on main (5ff00802, 2026-11-18) with this machine's caches (Ensembl split snapshot ensembl-variation-2026_07_13-vep116.0, ClinVar clinvar_2026-11-15). A spec of four rsID rows from S158's list (rs1452575772, rs1212793496, rs1362830842, rs1175404096) was enriched online with verify_ref on. All four were left unresolved with no row. The run warned "Placement disagreement — 4 rsID(s) are placed as different events": rs1452575772: ensembl places 7:150946949 A>AT; clinvar places 7:150946949 A>AC, and the same shape for the other three. In every pair, ClinVar's allele is also one of Ensembl's. Ensembl holds A>AC and A>AT at that site, and ClinVar holds A>AC only. The same spec enriched offline places all four from the snapshot (placement_verdict=undecided), because offline nothing can judge an indel. So the loss happens only where the judge can run: online with the reference read, which is how the registry re-derives.

The mechanism. counterparts pairs an allele with every witness allele of the same kind and length near it. Two one-base insertions of different bases at one position are counterparts. same_event(A>AT, A>AC) is then correctly False, and compare_placements records a disagreement for A>AT. That withholds the locus holding it, and with it A>AC, the allele both authorities agree on, because the split snapshot's locus carries both ALTs. RM267 decided the opposite for this case: "A different allele is unplaced, never a disagreement". A witness that holds one ALT of a multi-allelic site says nothing about the others. Its allele is already matched, as the same event, by another allele of the same answer.

Shape of a fix (the builder decides). A witness allele that is the same event as one of the authority's alleles for the rsID is accounted for, and is no counterpart for that rsID's other alleles. Those read unplaced. A witness allele that matches none of them still disagrees, as RM267 wants (S117's rs8176719). Tests: the four sites above as fixtures, plus a real one-ALT disagreement that must still withhold.

For the registry. The rows are withheld at enrich time, so a re-derivation on a fixed enricher places them. A plain enrich re-asks only the subjects with no row (merge-not-clobber), never the whole table.

Class. A patch: no schema, column or vocabulary moves (P3). The written rows are what the snapshot already says, so no published value changes meaning; rows that were wrongly withheld start being written. Severity high: it blocks three production modules' upgrade, and online it silently drops a placement for any multi-allelic indel site where ClinVar holds a subset of the ALTs.

Sized (the pm, 2026-11-18). A patch on main, the builder's shape above, with both tests. Built after RM449, since RM449 is the silent one, and cut with it as 0.8.9; the registry then re-derives the 13 rsIDs online. On 0.9 the merge carries it like RM446.

Built (triage, 2026-11-18). The shape above. compare_placements judges every (placed allele, witness counterpart) pair once. A witness allele that is the same event as any of the rsID's placed alleles is accounted for, and is dropped from the other alleles' counterparts. An allele left with no counterpart reads unplaced. All calls stay inside compare_placements, so the judge-caller registry (test_authored_event) does not move. Tests in test_placement_witness.py:

  • S158's four sites (rs1452575772, rs1212793496, rs1362830842, rs1175404096) at their real places, with GRCh38 windows read from Ensembl REST on 2026-11-18 behind a multi-window proxy, so the minter mints the real ids and the judge reaches the verdict the online run did. Each gives no disagreement and an unplaced row.
  • RM381's per-ALT pieces, where the witnessed A>AC reads same_event and A>AT beside it unplaced.

All five fail on the code before the fix with S158's own PlacementDisagreement. The real one-ALT disagreement, S117's rs8176719, still withholds (test_s117_is_withheld_…, unchanged and green).

Residuals won't fix — an authority's single ALT beside a witness's different ALT of the same length at one position (no third allele to account for it) still reads as a disagreement. Whether that is a different allele or a disputed placement is RM267's own question, not this item's; no report has met it

RM447 — Ensembl REST answers rs646776 without the A allele its own release 116 dump and dbSNP 157 carry, so an online fill and a snapshot fill disagree

SHIPPED 2026-11-17 on main, cut 2026-11-18 as v0.8.9 — a patch. Severity low · Owner enricher (the REST leg, ensembl._rest_rsid / _loci_from_rest); the fix is the compiler's message (allele_checks._stale_reading) · Motivating case the lead's RM404 online run on 0.9 (3e9b993c), recorded by the pm under RM404 in ROADMAP_0_9.md (ad49b85d, 2026-11-16) · related RM374, RM376, RM271

Both sides, read 2026-11-17 04:15 UTC.

  • Ensembl REST (/variation/human/rs646776; /info/data says release 116) answers 1:109275908, allele_string C/G/T.
  • The Ensembl snapshot on this machine (ensembl_variations, homo_sapiens-chr1.parquet, the same release's VCF dump) holds three rows at 1:109275908: C>A, C>G and C>T.
  • dbSNP (/variation/v0/refsnp/646776, the top-level GRCh38 placement) carries C>A, C>G and C>T.
  • reference_examples/longevity_studies/resolution.csv records C with A,G,T and three VRS ids, source=cache, ensembl-variation-2026_07_13-vep116.0.

So the example agrees with its pinned snapshot and with dbSNP, and nothing in it should move on this evidence. This is the case RM376 tested for rs746071566 and ruled out ("the snapshot carries alleles REST does not: No"). Here the answer is yes. Corrected after the measurement below: the filing read this as two surfaces of one release disagreeing, with REST the narrower one. It is a dbSNP build gap inside one Ensembl release. REST's /info/variation names dbSNP 156, and so does the VEP cache line in the snapshot's header. The VCF dump the snapshot is built from (2026_07_13) declares dbSNP 157, and dbSNP's own record of rs646776 was last updated in build 157. So RM374's reading, "a row from dbSNP 156", was right about the row's age; what it missed is that REST serves that build at the current release, so a re-derivation through REST cannot move it.

Why it matters. REST answers an rsID the snapshot holds only when the run has no snapshot: enrich(download=False) on a host without one, or a provisioning that failed and degraded to live. Such a run records G,T, and a run with the snapshot records A,G,T. The module and the Ensembl release are the same in both. A correct A/C genotype is then refused under --strict after the first run only. RM374's probe met exactly this refusal. RM374 made the message name the stale reading and point at --rederive, but here a re-derivation on the same host writes G,T again. The remedy the message gives does not reach this cause.

Shape of a fix (the builder decides). First measure: compare REST with the snapshot over the reference examples' rsIDs, which takes minutes, to learn whether rs646776 is one site or a class. One site may close as RM376 did, with the fact recorded in ENRICHER.md beside RM271's REST paragraph. For a class, the refusal's remedy should say when the row came from REST, so it can name REST's older build instead of a stale release. The enricher reports, never repairs: no REST answer is widened from another source.

Class. A patch: no schema, column or vocabulary moves (P3), nothing authored (P9). Severity low: one site is known, and the failure is a refusal that names its rsID, never a silent wrong value. No consumer has reported it.

Sized (the pm, 2026-11-17). A patch on main. The measurement is the first step and decides the rest: REST against the snapshot over every rsID the reference examples carry, both read the same hour. One site closes as RM376 did, with the fact in ENRICHER.md beside RM271's REST paragraph and the refusal message unchanged. Two or more sites make it a class: the --strict refusal then says when the stored row came from REST and names the narrower surface instead of --rederive. Nothing is widened from another source either way.

Measured (triage, 2026-11-17, 04:25–04:29 UTC). Every rs<digits> in reference_examples/*/*.csv, 467 rsIDs, was read in the same hour from the split snapshot on this machine (ensembl-variation-2026_07_13-vep116.0) and from Ensembl REST's batch route at release 116 (GRCh38 primary contigs). Each allele was compared with its shared prefix and suffix trimmed. REST answered 454 of the 467; the 13 it did not answer are rs2494… and rs2533… ids the snapshot carries, new in dbSNP 157. Of the 454, 58 differ. In 4 of them (rs33991993, rs34083951, rs34515413, rs34933751, all HBB) the only difference is a placeholder, N in the snapshot and R or Y in REST, which RM271's predicate drops on both sides. That leaves 54 where the snapshot carries alleles REST lacks, and none the reverse: 61 single-base and 2 longer alleles, among them rs646776 (A), rs137852556 (A and G, at both the X and the Y PAR spellings), rs112339338 and rs149436418. A class, so the refusal changes. The builds behind the two sides were read at 04:41 UTC: REST's /info/variation/homo_sapiens names dbSNP 156; the snapshot's manifest.json keeps the dump's header, ##source="dbSNP" … version="157", beside the VEP line's dbSNP="156".

Built (triage, 2026-11-17). allele_checks._stale_reading adds a reading for a row whose source is ensembl-rest (a private _LAGGING_LINKS): the row came from a live link that can serve an older dbSNP build than the snapshot. The remedy is enrich --rederive on a host where the Ensembl snapshot is provisioned. One departure from the sizing, which said "instead of --rederive": --rederive stays, qualified, because with the snapshot present it is the remedy that reaches the row (the cache link answers first). Only a plain one, on a host without the snapshot, asks REST again. The release reading and its pinned phrases stay beside it. A cache-sourced or unsourced row reads as before, and a hand-filled one still gets no reading. The compiler reads a member of ResolutionRow.source, a vocabulary the schema documents, only to word a remedy. It maps no link to a source, so P2 is not reached. A test over a REST row and a cache row is in test_rsid_placements_disagree.py. ENRICHER.md (beside RM271), COMPILER.md (beside RM374) and the CHANGELOG say it.

Residuals won't fix — the enricher widens no REST answer from the snapshot or dbSNP: it reports, never repairs · won't fix — ensembl-graphql is not in _LAGGING_LINKS, because no run measured it and no row in the examples records it

RM446 — a withholding client's retired outlives the run that met the 410, so a later run's outage reads as a retired route

SHIPPED 2026-11-17 on main, cut 2026-11-18 as v0.8.9 — a patch. Severity low · Owner enricher (net.Withholding.note_retired, withheld_reason, the live-Ensembl warning in enrich/orchestration.py) · Motivating case the lead's RM404 build on 0.9 (3e9b993c), recorded by the pm under RM404 in ROADMAP_0_9.md (ad49b85d, 2026-11-16) · related RM361, RM404

What was seen. Withholding.retired is set by the first 410 a client meets and never cleared (note_retired only sets it when it is None). enrich reads it per run: when some rsIDs went unanswered and the Ensembl client's retired is set, the warning says Ensembl "retired the route" and that "re-running will not answer them"; otherwise it says the request failed and a re-run may answer. literature records crossref_unanswered = withheld_reason(crossref) the same way. A client reused across runs carries run 1's 410 into run 2, so a run in which no request met a 410 (a timeout, a 5xx after the retries, a Retry-After hold) is told to upgrade, and told a re-run will not help.

Why it is a question and not only a bug. RM361 chose the stickiness on purpose. The docstring says a retired route is "a fact about the source rather than about one request", so it holds "for the client's life". That premise holds for one route met twice. It does not hold for another route of the same client (EnsemblResolver meets a 410 at two sites, the single-rsID GET and the batch POST), or for a 410 the source stops serving. And it reads "the client's life" as "one run". Before RM404 a host could reuse a client only by injecting a resolver=. RM404 makes a LookupClients bundle, reused across runs, the designed path for every client, so the wrong case becomes the normal one for a long-lived host.

Shape of a fix (the builder decides). The reason must come from what this run met, and RM404's first reading says enrich never alters a caller-given client. So no clearing at the start of a run. Something enrich can compare before and after it asks is enough: a count of the 410s met (new, additive), or the reason that note_retired's True returns, captured per call. The test reuses one client across two runs. Run 1 meets a 410 and run 2 meets only a timeout, and run 2 must give the outage wording. The same holds for the Crossref record.

Class. A patch: no schema, column or vocabulary moves (P3), nothing authored (P9); a client attribute added beside retired is additive. Severity low: the wording misleads a reader about whether to re-run, and no answer is recorded wrongly in a module table. No consumer has reported it.

Sized (the pm, 2026-11-17). A patch on main, not 0.9: the defect predates 0.9 (a reused resolver= met it already), and trial rule 1 sends a pre-existing defect to triage's patch on main. Either capture the builder picks is additive; the test is the one above. Built before 0.9 merges so RM404's docstring can point at it; if it lands after, the merge carries it.

Built (triage, 2026-11-17). The count shape. Withholding counts every 410 in retired_met beside the sticky retired, which is unchanged. net.retired_mark(client) reads the count, or None for a client without one. net.withheld_reason(client, since=mark) says retired only for a 410 met after the mark, and without a mark it reads as RM361 did. enrich takes the mark when it picks the live-Ensembl client and gates its warning on it. literature takes it when it picks the Crossref client and records crossref_unanswered with it. Nothing resets a caller's client. test_a_reused_clients_410_is_not_a_later_runs.py reuses one resolver across three enrich runs: a 410, then only a failed request, then a 410 again. Run 2 gives the outage wording and runs 1 and 3 the retired one; on the code before the fix, run 2 said "retired the route". The same file walks the mark over a CrossrefClient and a host's client that counts nothing. ENRICHER.md (the client-contract section) and the CHANGELOG say it.

Residuals won't fix — a 410 met on one route still names the reason for a run whose other unanswered requests failed otherwise: that is RM361's aggregate rule ("one retired endpoint means the run needs an upgrade"), within one run, and this item is about runs

RM445 — a pull keeps an unrecorded cache's old parquet and places the hub's newer release.json over it, so old bytes carry the new release's label

SHIPPED 2026-11-16 on main, cut 2026-11-16 as v0.8.8 — a patch. Severity medium · Owner enricher (download._provision_snapshot, _keep) · Motivating case the pm's remote-read trial, docs/probes/REMOTE_READS_0_9.md finding 8 (2026-11-15) · related RM339, RM372, RM420

What was seen. This machine's ClinVar cache has a release.json byte-identical to the one on Hugging Face (clinvar_2026-11-01, 4,608,075 records) and a pull record naming all 26 files, both written 2026-11-08 19:19. The parquet files under data/ are dated 2026-08-31, hold 4,431,781 rows and differ in size from the published ones (clinvar-chr1.parquet is 7,038,089 bytes here, 7,302,868 on the hub). lookup_clin_sig answers condition differently from the hub on 12 of 13 alleles. So the cache serves the August release under the November label. The pull record has no release_sha256 key and is older than release.json by 0.3 s. That fits a pull that wrote its record before the first download, kept every file, then fetched release.json, all on RM339's code (74e0e875, 2026-11-04). RM420 (dd900ff3) landed an hour after it, at 20:22.

The mechanism, still on HEAD. A cache with no pull record is RM339's "unrecorded" case: compared with the listing once, missing files fetched, the rest kept. _keep keeps any file whose footer reads when the repo publishes no manifest.json, and only the Ensembl lane publishes one; the ClinVar repo carries release.json, data/ and citations/ and nothing else. The root-file loop then fetches the hub's release.json whatever was kept. So an August cache pulled before the record existed becomes, after one pull, an August cache stating the November release. RM420's hub comparison does not stop it: for an unrecorded cache that states no release, _follow_hub.local is None, so it is not left alone and falls through to the same completion. Reproduced on main at 0cbc937c with test_download.py's fake hub, on both paths. One whole clinvar-chr1.parquet with an old_release column, no record, no release.json; the hub publishes clin_sig and clinvar_2026-11-01. After ensure_clinvar_snapshot(cache) (the enrich path) and again after it with a _FollowHub (the cache pull path), the cache's label is clinvar_2026-11-01 and its file still has old_release, with nothing fetched but release.json.

Why it matters. The label is what every reader trusts: release.json's dataset is the lane's release_label (caches.py, RM303), which cache status reports and cache pull compares with the hub's (_FollowHub). A wrong label is not withheld; it is a confident false answer, the arm the house algebra forbids. It is also sticky. The cache is now recorded and whole, and its label equals the hub's, so every later cache pull reads it as current and returns. Nothing on HEAD will ever repair this machine's cache; the operator has to move it aside and pull.

Shape of a fix (the builder decides). In the completion path, a kept file with no manifest to attest it is of unknown release. Either fetch it again when the hub states a release the cache does not (RM420's refresh, applied to the unrecorded case), or do not place the hub's release.json over files this pull did not fetch, so the cache states no release and is withheld. The first repairs; the second at least stops the lie. The sticky caches already out there need a word too: a pull record without release_sha256 was written before RM420, and is the one marker that the cache may be one of these.

Class. A patch: no public name, schema or vocabulary moves (P3), and nothing authored (P9). Severity is medium because answers are wrong silently, under a label that says they are current. No consumer has reported it; the measurement found it.

Sizing (pm, 2026-11-15): the next patch on main, both fix shapes and the sticky caches. A patch by class, and not blocked: by version-by-omission it goes into the next patch unasked. Of the two shapes, the more complete: never place the hub's release.json over files this pull did not fetch, and refetch a kept file when the hub states a release the cache cannot attest. The first alone would leave every unrecorded cache withheld until someone moves it aside; the second alone leaves the lie possible on the next path nobody thought of. The caches already wrong are in scope: a pull record without release_sha256 (written before RM420) is read as unrecorded for the hub comparison, so the next cache pull repairs this machine's ClinVar cache and any other like it, and no operator has to move a cache by hand. The test is the reproduction above on both paths, plus one with a pre-RM420 record. Open for the builder to say in the changelog line: an enrich run on such a cache between its pull and the fix recorded the new label over old ClinVar answers; nothing here knows which modules were enriched on one, so the line says how to tell (a pull record without release_sha256) rather than claiming none.

Built (builder for the lead, 2026-11-16). Both shapes and the sticky caches, enricher only. _provision_snapshot decides keep-or-fetch for every planned file before the first download (_plan_keeps), and a kept file is attested by the manifest (data only, as _keep already required) or by the record: _kept_release reads the release this repo's own pull says the files on disk are, and it counts only while it equals the release.json the repo publishes now. The hub's release.json is fetched first, staged beside the cache like the manifest, and placed last only when no kept file is unattested; avi_knots.parquet follows it, LICENSE.txt (terms, not a release) does not. Otherwise:

  • cache pull / cache prepare (_follow_hub) re-pull, as RM420's refresh with the refreshed outcome and a note saying nothing attested the files: an unrecorded cache stating no release whose hub states one, a resumed pull past a release boundary, and a whole cache whose finished record has no release_sha256 (_label_unattested), even when its label equals the hub's. A no-digest record with a differing label is re-pulled as before, so RM420's motivating case is unchanged, and a lane with a manifest is never unattested this way, so no Ensembl cache is re-hashed.
  • enrich keeps the file, places nothing and states no release. A whole recorded cache still returns before the hub is read.
  • A local build (a release.json no pull of this repo placed: no record, or one not vouching for it) is never fetched beside, on either path (the pm's call, 2026-11-16). Complete, it is kept as it is (left alone with another label than the hub's, as RM420). Lacking a part the repo publishes, it is left untouched (nothing removed or fetched, its release.json kept, no record written) and every run warns that the part could not be reached, naming the remedies; cache pull reports it kept. A pull's own release.json beside files it no longer vouches for is withdrawn right before the first byte (@snapshot-layout-locations) and the next cache pull re-pulls.
  • The record names the digest of the release.json the pull placed (null when none), so a builder's file is never vouched for. The record written before the first download names the release being pulled (pulling_release_sha256, private) when every whole file under a planned name is already that release's, so a same-release resume still fetches only what it lacks, and a pull killed after placing its label is current.
  • Could-not-ask on release.json (anything but the Hub's absent answer) stops the pull before anything in the cache moves, as for the manifest: it is asked before the manifest is placed. A servable cache is used as it is. A repo publishing no release.json pulls as before (Ensembl now asks for one on every pull). Kept by the pm.
  • A current label is checked against the listing (the pm's 3a, cache pull only). A whole pulled cache with no manifest whose label equals the hub's is compared with fs.ls(..., detail=True) (_differs_from_listing): every file's size, and its LFS sha256 (lfs → sha256, read off huggingface_hub 2.4.0's _cache_info_from_path_info and BlobLfsInfo) up to _LISTING_SHA256_MAX_BYTES, 256 MiB. A contradicted or absent file is fetched again, the label withdrawn first and the record naming no release being pulled, so a refetch cut short states no release and the next pull re-pulls. A listing that cannot be read is unknown. This closes the 0.8.3-0.8.7 caches no marker on disk names. enrich stays network-free for a whole recorded cache; a build is never compared.

STRchive's root-file provisioner keeps no file, so the mechanism does not reach it (class checked); it now withdraws an old release.json before every catalogue it moves in. Tests in test_download.py and test_cache_pull_follows_the_hub.py, each repair with a second lap counted through the fake hub; each arm reverted on purpose turned at least one red, and RM420's eighteen pass unchanged. A high-effort code review of the first build found the two orders (enrich then cache pull, and the reverse) disagreeing over an unrecorded build, a withdrawn description turning a build into a pull, could-not-ask read as absent, and the knots withheld where no label exists; a second read found the withdrawal record catching a pull's own label and release.json asked after the manifest had moved. All are fixed and tested.

Residuals won't fix — a kept file over 256 MiB, or one stored in git rather than LFS, whose size equals the listing's while its bytes differ is not seen by cache pull's listing check, because hashing every large shard on every pull is minutes of disk reads

RM444 — recover_rsid's result text over-claims: a none beside overlapping records says dbSNP records nothing, and a position-only recovered advises authoring whatever record starts there

SHIPPED 2026-11-14 on main, cut 2026-11-14 as v0.8.7 — a patch, text only. Severity low · Owner enricher (grch37.RsidRecovery.__str__, grch37.recover_rsid) · Motivating case S155 (just-module-creator, CONSUMER_SUGGESTIONS_HISTORY.md) · related RM31, RM361

The gap. The anchored match is right and stays: a candidate must start at start and carry the given alleles. What the result says is wrong in four places. All four reproduce through recover_rsid itself against Ensembl's GRCh37 service (2026-11-14), on CFTR F508del (rs113993960, whose GRCh37 record is TCTT/T/TCTTCTT at 117199645):

  1. The none headline contradicts its own note. At 117199644 with ref=ATCT, alts=A (VCF's left-aligned spelling) the text is "GRCh37 dbSNP records nothing here. 5 dbSNP record(s) overlap the position, none starting at it with the alleles given." dbSNP records this very deletion one base to the right. "Records nothing here" is true only when nothing overlaps.
  2. The note names alleles that were never given. At 117199646 with no ref/alts, the note still ends "none starting at it with the alleles given".
  3. A position-only recovered over-claims. At 117199644 with no alleles, the outcome is recovered with rs1801178, an SNV at the deletion's anchor base. That is a different variant, and the text tells the author to "author that rs-number instead of the coordinate". A match on position alone is only as good as the position. At a padded indel's VCF position, the record starting there is the anchor base's.
  4. The ambiguous text names CLI flags ("Narrow it with --ref/--alts") in a __str__ that every library caller passes on. Only just-dna-enricher hint recover has those flags. lookup_old_assembly (lookup.py) and an MCP tool wrapping recover_rsid pass arguments named ref/alts.

The docstring's explanation is also narrower than the case. It says a VCF-padded indel "will not match Ensembl's unpadded record". Here both spellings are padded, at different anchors: Ensembl pads a record whose alleles mix a deletion and an insertion at its own anchor. So the one spelling that matches can be neither VCF's nor HGVS's.

The ask. Text only, no new outcome:

  • When features overlap, none says that no record starts here (with these alleles, when some were given) and that N overlap. It keeps "records nothing here" for the empty answer.
  • The note drops "with the alleles given" when none were given.
  • A recovered with no ref says it matched on position alone. Its advice to author the rs-number is conditional on the variant being the one that starts there; at an indel's padded position, that is the anchor base's record.
  • __str__ names the arguments (ref/alts). The CLI may add its flag spelling where it prints.
  • The docstring says the anchor may differ from both VCF's and HGVS's spellings, and that a none with overlapping records is a reason to retry at a neighbouring anchor, not a statement of absence.

Declined as part of this item: a separate outcome for "none, but records overlap" (S155's candidate 1, second half). It would add a member to outcome, which lookup_old_assembly maps to a level and callers branch on. That makes it a minor, and the overlap count already sits in the note. Honest text closes the report without it.

Sizing facts. Strings and a docstring. No outcome, field or vocabulary moves. Tests pin the four texts against a stubbed overlap answer shaped like the F508del one (a padded record one base right of the queried position, plus an SNV at it).

Built (lead, 2026-11-14). All five asks, text only. RsidRecovery gains a private _overlapping count, so none keeps "records nothing here" for an empty answer and otherwise says no record starts here, counting the overlaps and naming the retry at a neighbouring anchor. "With the alleles given" appears only when some were. A recovered with no ref says it matched on position alone (or on position and alt) and makes the authoring advice conditional on the variant being the one that starts there. ambiguous names ref/alts; lookup_old_assembly's docstring too. The docstring and ENRICHER.md § old assembly state the F508del anchors. Seven tests in test_grch37.py::TestWhatTheRecoveryTextClaims replay Ensembl's real GRCh37 answers at 117199644, 117199645 and 117199646 (recorded 2026-11-14); four were red on the old text. No outcome, field or vocabulary moved.

Residuals none

RM442 — the two AlphaGenome licence rows misstate the terms they quote: the Atlas row's training bar and date, and the AVI row's prohibition 4

SHIPPED 2026-11-14 on main, cut 2026-11-14 as v0.8.7 — a patch, text only. Severity low · Owner enricher (licensing.py) · Motivating case the liaison's re-vendoring of AlphaGenome's live terms, 26db64cb, after the RM433 trial on 2026-11-14 · related RM433, RM195, RM191

The gap. The liaison's ledger (docs/UPSTREAM_ALPHAGENOME.md, verdicts and adoption map) found three sentences in licensing.py that say something the terms do not. The pm checked each against the saved texts in docs/vendor/:

  1. ALPHAGENOME_ATLAS_TERMS.notice understates the training bar for new Output. It says "no training of variant-effect models (restriction 2)". That is the June 2025 Output Terms' wording. The Output Terms effective 2026-10-09 (alphagenome_output_terms_2026-10-09.txt, restriction 2) bar training any model or related technology, except an AlphaGenome-like model under the Model Parameters Terms. A module's consumer has not agreed to the Additional Terms, so the Output Terms are what bind them. Which version applies follows the Output's generation date, which dataset carries.
  2. ALPHAGENOME_ATLAS_TERMS.license dates the Output Terms "(2026-09-08)". That is the Additional Terms' date. The Output Terms' own dates are 2025-06-25 and 2026-10-09.
  3. ALPHAGENOME_AVI_TERMS.notice cites prohibition 4 as binding. Prohibition 4 of the Additional Terms opens "Except for Permissive Use Downloadable Artifacts" in both the 2026-09-08 and 2026-11-06 texts, and AVI is in that class. Under the Additional Terms it does not bind AVI.

No licence axis moves: commercial_use, redistribution and share_alike stay as they are, and no gate reads notice. The liaison says no test change is owed.

The ask. Correct the three strings. For (3), settle which instrument binds a downstream holder of AVI before deleting the bar. The AVI artifact is stamped 2026-08-27, so a holder bound by the Output Terms would be under the June 2025 text, whose restriction 2 has no Permissive carve-out. If that reading holds, the fix is to cite restriction 2 of the June 2025 Output Terms in place of prohibition 4, not to drop the bar. Stating a bar that does not bind is harmless; dropping one that does is not. Also update the comment near licensing.py:912 that quotes prohibition 1a's old "except for the AVI Score" wording. Leave alphagenome_avi_build._default_terms_file on the undated June 2025 file (ledger check 3).

Sizing (pm, 2026-11-14): a patch, build now. These are string constants. No schema, field or vocabulary moves, so P3 allows it in a patch. A module re-enriched after the fix carries the new notice in sources.csv, and its digest moves with it. That is the intended effect, not a reason to defer. Version by omission: it rides the next patch on main.

Built (lead, 2026-11-14), as sized. (1) The Atlas notice states restriction 2 by generation date: the June 2025 bar on training variant-effect models like AlphaGenome, and for Output from 2026-10-09 the bar on training any model except an AlphaGenome-like one under the Model Parameters Terms. (2) Its license names the Output Terms by their own dates, 2025-06-25 and 2026-10-09 from that date. (3) The pm's caution held: a holder of a published AVI snapshot has not agreed to the Additional Terms, so the Output Terms bind them (their opening paragraph), at the June 2025 version in force when the artifact was generated (2026-08-27), and that text's restriction 2 has no Permissive carve-out. So the AVI notice keeps the bar and cites June 2025 restriction 2, naming prohibition 4 only as the carve-out it is. The comment on prohibition 1a gives the 2026-11-06 spelling beside the old. Pinned by three tests in test_alphagenome_atlas_terms.py that read each claim off docs/vendor/ (red before on all three). _default_terms_file is untouched.

Kept as shipped, the maintainer (2026-11-18), relayed by the lead. On the AVI row's training bar, which Google's Additional Terms exempt while the June 2025 Output Terms keep it: "We don't do training here, thus, don't care about the ban. Keep all as is." The cautious notice stays as 0.8.7 shipped it; the contradiction is Google's to fix, and nothing changes here until they do.

Residuals none

RM440 — a re-derivation that drops a back-filled rsID on RM438's no-host arm says nothing at run time

SHIPPED 2026-11-13 on main, cut 2026-11-13 as v0.8.6 — a patch, a log line, no warning code. Severity low · Owner enricher (enrich/orchestration.py, the position back-fill) · Motivating case RM438's build (S151, S152, CONSUMER_SUGGESTIONS_HISTORY.md) · related RM438, RM393

Residuals none

The gap. Since RM438, where the row's alleles refute every rsID at a coordinate-only row's position, enrich writes the row with no rsID (source=authored), as an allele-exact miss already was. On a --rederive that replaces a recorded row which carried a back-filled rsID, the rsID leaves resolution.csv and the run logs nothing about it: the branch that writes the empty row emits no warning. resolve_variants says the same outcome aloud (rsid_without_resolution_label, none there can host the row); the enrich path does not. Today the only ways to see it are a diff of the table or the second exposure query RM438's CHANGELOG entry states. Seen by RM438's builder and left out of that patch as its residual.

For the pm. Whether a re-derivation that removes a recorded rsID on this arm names it, aggregated by reason (@warning-text-is-api), and whether that fits a patch (a log line with no new code) or wants a warning code.

Sizing (pm, 2026-11-12): a patch, unattended, about 30 minutes, a log line. A table a re-derivation shortens in silence is what @rederive-never-shortens exists against. Here the shortening is right, but the reader must still be told, and the registry's three ClinVar panels re-derive on 0.8.5 next, about 51,000 back-filled rows. One warning per run, aggregated by reason (no allele the row states is hosted at the position), with the count and the first few variant keys, and its phrase pinned. No warning code: the enricher's log lines carry none (RM427's ask 3 was declined for the same reason), and none is needed to read a count. In the patch after 0.8.5, so the registry re-derives its panels on 0.8.5 meanwhile and reads the change from a diff of the table or from RM438's second query.

Built (lead, 2026-11-13), as sized. The assembly loop's no-candidate branch counts a key when the run re-derives, some link has rsIDs at the position, and the recorded row carried one; one warning per run after the loop, the first five keys named. Pinned by test_a_rederivation_that_drops_a_recorded_rsid_says_so_once (red before: the rsID dropped and nothing was logged); the re-derive tests and the feature corpus stay green.

RM439 — VariantRow.stat_significance states no threshold either, and RM434's sentence does not fit it

SHIPPED 2026-11-13 on main, cut 2026-11-13 as v0.8.6 — a patch, a description only. Severity low · Owner format (spec.VariantRow) · Motivating case RM434's build (S147, CONSUMER_SUGGESTIONS_HISTORY.md) · related RM434, RM148

Residuals none

The gap. RM434 gave StudyRow.stat_significance a description saying whose threshold a level is: the authors' verdict at the threshold of the study's own test, with p_value_num the column to threshold on one scale. VariantRow carries a stat_significance of its own, and its description is still the bare level list (Statistical significance: significant|suggestive|not_significant|unknown.). It is the module author's verdict across a variant's evidence, not one study's, so RM434's sentence would say the wrong thing there and was left out of it on purpose. A reader of variants.csv meets the same silence S147's reporter met in studies.csv. Filed at the 0.8.5 cut as RM434's residual.

For the pm. Whether the row-level field gets a sentence of its own (whose verdict, across which evidence, and that the per-study grade and p_value_num live in studies.csv), as a description-only patch, or waits for a reader to trip on it. None has yet.

Sizing (pm, 2026-11-12): a patch, unattended, about 10 minutes, built with no reader's report. A reader already tripped on the same word one table over, and readers meet variants.csv first. The sentence says only what is true of the row-level field: the module author's verdict across the variant's evidence, with each study's own grade in studies.csv and the number to threshold in its p_value_num. It names no threshold of its own (@field-description-is-a-claim). It moves no digest.

Built (lead, 2026-11-13), as sized. The description says the module author's verdict across the variant's evidence, no threshold of its own, each study's grade in studies.csv and its p_value_num; schema/tests/test_spec.py::test_a_variants_significance_is_the_module_authors_verdict_across_its_evidence pins it (red before).

RM438 — resolve_variants back-fills a position-only row with the first rsID at its (chrom, start, ref), whatever the genotype, and warns nothing

SHIPPED 2026-11-12 on main, cut 2026-11-12 as v0.8.5 — a patch, one hosting rule on both back-fill paths, declared as a corrected derivation of resolution.csv. Severity high · Owner enricher (resolver._lookup_rsids_by_position, resolve_variants) · Motivating case S151 (CONSUMER_SUGGESTIONS_HISTORY.md) · related RM382, RM381, RM271

Residuals RM440

The defect. Reproduced on main with an in-memory table holding S151's four rows at 22:42128945 (three SNVs under rs3892097, the CYP2D64 SNP, and one insertion C→CGGGTAAGGGGGCGTCT under rs2517910443, new in dbSNP 157). _lookup_rsids_by_position(con, [("22", 42128945, "C")], w) returns {'22:42128945:C': 'rs2517910443'} with w == []. The answer is keyed on (chrom, start, ref) and filled by setdefault over rows ordered chrom, start, ref, id, alt, so the lexicographically first rsID wins. The row's genotype (A/G, which only the SNV can host) is never read. A multi-rsID position is warned about only when the row gave no ref. A coordinate-only CYP2D64 row therefore gets the wrong rsID, silently.

Where it bites. The enrich path is not this code. It builds resolution.csv through _lookup_rsid_candidates, which is allele-aware: 0 candidates leaves rsid empty, 1 attaches, 2 or more picks deterministically and marks the row ambiguous (@rsid-not-per-allele). resolve_variants is the older public function. The compiler reaches it only through the deprecated ensembl_cache path, which warns at use and goes at 1.0. Consumers also call it directly, as just-dna-lite does. That is the reason to fix it rather than wait for the removal, because a wrong rsID on a pharmacogene row is the expensive kind of wrong.

The ask (the reporter's candidate, in the house rule). Narrow a position's rows to those whose ALT set can host the row's genotype (RM382's hosting rule, applied to the back-fill). Attach only when one rsID is left. When more than one is left, withhold the rsID with a rsid_ambiguous warning naming every one. Rows that state alts narrow on them first. A behaviour correction with no new name, so a patch. Pin it with S151's four rows.

Sizing (pm, 2026-11-12): a patch, the next on main, about an hour. A wrong rsID on a pharmacogene row, given silently, by a public function consumers call: that is the expensive kind of silent, and the deprecation does not make it rarer for them. The 0.8.5 cut is paused for RM436 anyway, so it goes in 0.8.5 if it lands first; the lead decides. Conditions:

  • One hosting rule, not two. The back-fill asks the same allele-aware judgement _lookup_rsid_candidates already makes for the enrich path (RM382's rule), through a shared function, never a second copy of it (@roster-is-as-wide-as-the-tables-it-reads: grep for the question).
  • The existing word for the outcome: more than one rsID left is the rsid_ambiguous finding the enrich path already emits (vocab, ambiguous_pick), naming every candidate; no new code. Unlike the enrich path, the back-fill withholds the rsID there rather than picking, since nothing downstream marks its pick.
  • Pinned with S151's four rows (the three SNVs and the insertion), the A/G row getting rs3892097, plus a row with no genotype at the same position getting nothing and the warning.
  • Declared in the CHANGELOG and INTEGRATION_0_8's known-issues list: a row that used to get an rsID may now get none and a warning.

S152 addendum (triage, 2026-11-12): the enrich path's back-fill has the same blind spot, flagged rather than silent, and the sizing's shared rule does not read the genotype yet. just-dna-lite asked whether RM438 reaches catalog modules that the registry's 0.8 upgrade re-derived (enrich(rederive=True)). Checked on main, that path is not _lookup_rsids_by_position. _lookup_rsid_candidates with S151's four rows and no authored ALT returns ['rs3892097', 'rs2517910443']. With alt="A" it returns ['rs3892097']. orchestration.py writes the first candidate, ordered by ALT, with status="ambiguous" and every candidate in rsid_alternates. So no catalog row got a wrong rsID silently. Here the first by ALT order is also the right one, but only because A sorts before C…. Two facts for the build:

  • _lookup_rsid_candidates is allele-aware on the authored ALT (_authored_alt: alts, single-valued), never on the genotype. RM382's hosting filter judges the forward direction (an rsID's loci) only. So the sizing's pin, the A/G row with no alts getting rs3892097, needs the genotype read in the shared rule. Asking today's _lookup_rsid_candidates returns both candidates and would withhold. The shared function has to take the genotype's alleles when alts is absent.
  • Once the shared rule reads the genotype, the enrich path changes too. A row now written ambiguous becomes resolved on the one hosting rsID, or keeps ambiguous when several host it. Published resolution.csv files move on the next re-derivation. That is a corrected derivation, so it ships in any release but is declared (P3). The registry can size the exposure without a rebuild: published rows with status=ambiguous, coordinate-authored, with no single alts, are exactly the set this can change.

Re-sized on the addendum (pm, 2026-11-12): one rule, both paths. The first sizing's "one hosting rule" condition assumed _lookup_rsid_candidates already read the genotype; it reads only the authored ALT, so that condition is replaced by this one. The patch, still the next on main and in 0.8.5 if it lands first:

  • One shared function narrows a position's rsIDs: by the row's alts when stated, else by its genotype's alleles, through RM382's hosting judgement. Both back-fills call it. An allele it cannot read (a missing, symbolic or unparseable genotype) narrows nothing: a candidate is never dropped on an unknown.
  • resolve_variants withholds on more than one rsID left, with rsid_ambiguous naming every one, as sized.
  • The enrich path keeps its pick-and-flag. A row moves from ambiguous to resolved only where exactly one rsID hosts the genotype; several hosting keep ambiguous.
  • Declared as a corrected derivation of published resolution.csv (P3), in the CHANGELOG and INTEGRATION_0_8, with the exposure query above, so the registry can tell which of its re-derived rows can move. Measured 2026-11-12 by the registry on production, read-only, latest version of all 24 modules: 439,752 rows, 0 ambiguous, 0 with rsid_alternates, so nothing published moves. The exposure ahead is three ClinVar panels (cancer, cardio, pathogenic; about 141,000 coordinate-keyed rows) still on pre-0.8 tables, which the registry re-derives after installing RM438; the test registry was not measured. The resolved arm, measured 2026-11-12 by the registry on production, read-only, with the second query below: 7 coordinate-keyed rows carry a snapshot back-fill (source=cache), all in one module (smell 0.1.1), and each row's authored genotypes sit within its own ref/alts, so none is refuted. Nothing published moves on either arm. 51,249 more rows carry a ClinVar back-fill, all in the three ClinVar panels still on pre-0.8 tables (cancer, cardio, pathogenic 2.0.0); their re-derivation on 0.8.5 is where RM438 applies.
  • No rsID hosts it (ruled 2026-11-12, on the lead's build question). Where every candidate's site confidently refutes the genotype, nothing is attached: resolve_variants says none can host, and in enrich that link is a miss, so the next link (ClinVar) is asked. That is @answered-is-not-absent as written, and attaching a refuted rsID is the defect itself; an unreadable allele still narrows nothing. It can move a resolved row too, which the first query does not see, so it is declared beside the ambiguous arm with its own query (a resolved, coordinate-authored row whose genotype carries an allele its single back-filled rsID's site refutes), naming the source moving to ClinVar as a possible effect, and the registry runs it on production before the three panels re-derive.
  • Pinned with S151's four rows on both paths: the A/G row resolves to rs3892097 on each, and a row with no genotype and no alts stays withheld (resolve_variants) or ambiguous (enrich).

Built (2026-11-12). One private rule, resolver._hosting_rsids(candidates, ref, alts, genotypes). It reads the row's alts with its ref when stated, else every genotype the variant's rows author (a pharm or haplotype subject narrows on its own). It keeps each rsID whose loci at the position site_verdicts does not refute (Kleene), and an unreadable allele narrows nothing. The candidates' loci come from the same query, through an out-parameter on _lookup_rsid_candidates and the private resolver._lookup_loci / clinvar._lookup_loci twins, so the public lookup_loci signatures are unchanged. _lookup_rsids_by_position now reads through it, one subject per (chrom, start, ref, alts). It attaches one rsID, withholds several with rsid_ambiguous, and says none can host under rsid_without_resolution_label. The enrich loop takes the first link whose narrowed set is non-empty. Two choices beyond the sizing, for review. (1) Zero hosting is an answer, so an ambiguous row, or a resolved row on a single refuted rsID, gets no rsID. That arm is outside the measured query; the CHANGELOG names it. The pm kept it (ruling above). (2) Every row's genotype narrows, not the first row's, so a C/C row authored first does not keep a key ambiguous; a key whose rows name different rsIDs therefore gets none. RM382's forward filter still reads the first row's genotype. Pinned by enricher/tests/test_a_position_rsid_is_narrowed_by_the_genotype.py (S151's four rows, both paths, and the ClinVar fall-through), red on 0ccd50fe (31 of 37). test_resolver_unit's ref-less pick is inverted, with its reason. The feature scenario and ENRICHER's back-fill section are rewritten.

RM436 — the enricher floors tenacity>=9.2.1, and google-genai caps it below 9.2.0, so a consumer depending on both cannot resolve the 0.8 trio

SHIPPED 2026-11-12 on main, cut 2026-11-12 as v0.8.5 — a patch, candidate 1 (the shim). Severity medium · Owner enricher (pyproject.toml, every retried client's wait) · Motivating case S149 (CONSUMER_SUGGESTIONS_HISTORY.md) · related RM371, RM254

Residuals none

The defect. RM371 floored tenacity>=9.2.1 so the enricher could spell wait_exponential_jitter(multiplier=…). 9.2.1 renamed initial, and 9.1.4 has only the old name. Its entry says just-dna-lite, just-module-creator and the marketplace "all accept 9.2.1". just-dna-lite does not. It depends on google-genai, and every release of that caps tenacity<9.2.0: checked here, 3.2.0, the newest, requires tenacity<9.2.0,>=8.2.3. So uv lock with just-dna-enricher>=0.8.4 fails. Worse, a relock that does not raise the enricher's floor silently kept just-dna-enricher==0.7.3 beside just-dna-format==0.8.4, a mixed trio. The reporter carries a workspace override (tenacity>=9.2.1) and has checked that google-genai's calls are unchanged under 9.2.1.

The two candidates. (1) Accept tenacity>=9.0 again, and pick multiplier= or initial= by what the installed release offers, in one place every retried client calls. RM371's warning stays fixed without the floor, and a consumer capped below 9.2 resolves. (2) Keep the floor and correct RM371's sentence, which leaves the consumer a permanent override until Google lifts its cap. Both are patches. (1) costs one small shim. (2) costs every consumer with google-genai an override, and the trio's own adopters include one.

Sizing (pm, 2026-11-12): candidate 1, a patch, urgent, in 0.8.5. The maintainer: "no 8.5 wo tenacity pin". A floor no real consumer can meet is a defect of ours, not theirs, and (2) would hand just-dna-lite an override for as long as Google keeps its cap. The shim carries no claim of its own: it names one keyword by what the installed release accepts. Conditions:

  • One place decides the keyword, by the installed function's signature, never by parsing a version string; every retried client calls it, and an AST or registry test holds that no client spells multiplier= or initial= itself.
  • The floor is one a run has proved: the tests pass on the floor release and on the newest (a uv lowest-direct resolution, or a pinned run each side), and RM371's warning stays silent on both. If >=9.0 fails on its floor, the floor is the lowest that passes, still below 9.2.
  • RM371's sentence is corrected where it says every adopter accepts 9.2.1, and the CHANGELOG and INTEGRATION_0_8 say the floor moved down and why.

Built (lead, 2026-11-12), as sized. net._jittered_backoff(base=, cap=) is the one place that builds a wait_exponential_jitter; it reads multiplier off the installed constructor's signature (_JITTER_TAKES_MULTIPLIER) and passes multiplier= or initial=. All 22 call sites in 17 modules go through it. The floor is tenacity>=9.0.0. enricher/tests/test_retry_wait_keywords.py replaces RM371's walk: no call outside the shim (mutated on gwas.py and seen red), the keyword matches the signature with deprecation warnings as errors, and the floor equals the proved release and sits below google-genai's cap. The proof: the enricher suite run on tenacity 9.0.0 (uv run --with tenacity==9.0.0) and on the locked 9.2.1: 3,643 passed and 116 skipped on each, with one failure on each, test_a_regex_locator_matches_the_fulltext, a load flake (its regex runs in a killable process with a timeout, and the machine's load average was 60); it passes alone on both releases, as do the three guard tests. RM371's sentence is corrected in its ROADMAP_HISTORY entry; the CHANGELOG and INTEGRATION_0_8 § 4 say the floor moved down and why.

RM434 — stat_significance states no threshold, so a replication that passed its own test reads as a null

SHIPPED 2026-11-12 on main, cut 2026-11-12 as v0.8.5 — a patch, reading 1 (the description); the fifth member declined (the pm). Severity low · Owner format (spec.StudyRow, vocab.VALID_SIGNIFICANCE) · Motivating case S147 (CONSUMER_SUGGESTIONS_HISTORY.md) · related RM148, RM150

Residuals RM439 · won't fix — reading 2, a fifth nominal member, declined by the pm: it puts a threshold convention into a verdict column (P5) and grades what p_value_num already computes

The gap. StudyRow.stat_significance is closed at significant|suggestive|not_significant|unknown, and its description is that list and nothing more. No threshold behind a level is stated anywhere: not in the field, not in vocab.py, SCHEMAS, TABLES or the FAQ. The reporter read suggestive in the GWAS sense (about 1e-5) and so placed a look-up replication at P 0.002 (one discovery SNP re-tested in an independent cohort) in not_significant, beside a failed look-up at P 0.6. A reader sorting a variant's evidence by this column then sees the replication as a null. The number survives in p_value_num, but the verdict column says the opposite of what the study's authors report.

Two readings, and why the first is a patch. (1) The level is the author's verdict at the threshold of the study's own test. A pre-specified single-SNP look-up has no genome-wide multiple-testing burden, so passing its test is significant. Under that reading nothing is missing from the vocabulary: the description fails to say so, and p_value_num is the column a reader thresholds on. A description that says it is a patch, as RM427's rewording was. (2) The level is graded on the genome-wide scale, and a fifth member (nominal, p < 0.05 above the suggestive line) holds a replication. A new member is minor-legal (P3) and lands on the authored layer, so it is full cost (P9). The reporter names the cost of (2) themselves: if the level is derivable from p_value_num, a fifth member adds nothing a reader cannot compute. (2) also carries the threshold convention into the verdict column, a second axis on one field (P5). That is the shape VALID_DIRECTIONS's comment refuses for a member that respells a state the model can already express.

Sizing (pm, 2026-11-12). Reading 1 is a patch, unattended, about 20 minutes: StudyRow.stat_significance's description says the level is the authors' verdict at the threshold of the study's own test, that a pre-specified look-up passing its test is significant, and that p_value_num is the column to threshold on a common scale. The same sentence goes in TABLES.md's studies.csv section if it names the column. A real row was mis-graded because the sentence was missing, and a description moves no digest. It is a claim (@field-description-is-a-claim), so it cites what it rests on: the authors' own test, never a scale we pick.

Reading 2, the fifth member, is declined, not parked. It puts a threshold convention into a verdict column (P5) and grades what p_value_num already lets a reader compute. It comes back only through a new Sn from a reader who needs a genome-wide grade and cannot get it from p_value_num.

Built (lead, 2026-11-12), as sized. StudyRow.stat_significance's description carries the three sentences; schema/tests/test_spec.py::test_a_studys_significance_is_the_authors_verdict_at_their_own_tests_threshold pins them (red before). TABLES.md's studies.csv section does not name the column, so it is unchanged. VariantRow has a stat_significance of its own, still the bare list: it is the module author's verdict across the evidence rather than one study's, a different claim, filed at the 0.8.5 cut as RM439 for the pm to size.

RM432 — two snapshot readers answer an unreadable reference with an empty result, which reads as "nothing found"

SHIPPED 2026-11-11 on main, cut 2026-11-12 as v0.8.5 — a patch, a raise of FileNotFoundError; no new name. Severity medium · Owner enricher (gene_metrics, civic_refutation, civic_citations) · Motivating case S146 (CONSUMER_SUGGESTIONS_HISTORY.md) · related RM361, RM430

Residuals none

The defect. gene_metrics.lookup_snapshot returns {} when _snapshot_parquet(reference) finds no parquet. civic_refutation.civic_snapshot_rows returns [] when the parquet does not exist. Both were checked on main. A caller handed a reference that cannot be read gets the value of a lookup that ran and found nothing. That is the house rule RM361 enforced elsewhere: an unread input is never recorded as a definite answer. Inside the workspace, the two passes mostly guard the reference before calling. resolve_*_reference answers only for a directory that holds a parquet, and compare_refutations reads an empty list as "missing or unreadable" and skips, which is right only because a real CIViC snapshot is never empty. civic_citations._snapshot_variant_ids turns an unreadable given reference into an empty map, so every variant falls through to the curated table. Today a misconfigured path reaches this. With RM430, a failed remote read would reach it too.

The ask. Raise on an unreadable reference (the *Unavailable family, or a plain error), and keep {}/[] for a lookup that ran and found nothing. Or, if a raise would break a caller relying on the empty value, add a sibling flag saying the snapshot was not read. The reporter calls neither reader directly today, so nothing is blocked.

Sizing (pm, 2026-11-11): a patch, unattended, about an hour. The failure is silent: given a mistyped --civic-snapshot, the citations pass falls back to the curated table for every variant and says nothing, so the operator believes the snapshot was read. That alone earns a patch, however rare the mistype.

  • Raise, not a flag. A flag a caller can ignore is the same silence. Raise the built-in FileNotFoundError, which names the path and adds no public name, so it stays patch scope. Neither reader has an error type of its own, and minting one would be a minor.
  • {}/[] keep meaning "read, and nothing matched".
  • The three internal callers catch it and report could-not-read, never empty: gene_metrics at its lookup_snapshot call, compare_refutations, and civic_citations._snapshot_variant_ids. This is the fix's own risk, so a test drives each of the three with a reference that is not there.
  • Declared in the CHANGELOG and INTEGRATION_0_8's known-issues list as a behaviour change for a direct caller.

Built (lead, 2026-11-11), as sized. Both readers raise FileNotFoundError naming the path; the gene-metrics pass catches it and sets the reference to unconsulted (offline it had written a not_found row stamped with the bare lane label for a snapshot it never opened, which the new test showed red), compare_refutations skips with a could-not-read warning (an empty but readable snapshot keeps its own skip, reworded), and civic_citations._snapshot_variant_ids warns that variants map from the curated table alone. Tests: enricher/tests/test_unreadable_snapshot_reference.py, five of six red before the change (the sixth is the read-and-matched-nothing control).

RM428 — the GWAS pass asks the Catalog v2 for a page of 1000, which it now refuses with 400, so the pass fills nothing on any module

SHIPPED 2026-11-11 on main, cut 2026-11-11 as v0.8.4 — a patch, asks 1 to 3; ask 4 declined (the maintainer, desk #252). Severity high · Owner enricher (gwas.py) · Motivating case S143 (CONSUMER_SUGGESTIONS_HISTORY.md) · related RM354, RM361

Residuals won't fix — the maintainer declined an enricher-only 0.7.4 on 2026-11-11 (desk #252); the 0.7 line keeps the retired v1 GWAS API

The defect. GwasClient.association_pages sends size=_PAGE_SIZE on its first request, and _PAGE_SIZE is 1000 on every 0.8 release and on main. The GWAS Catalog's REST API v2 now refuses any size above 500 with a bare 400 ({"status":400,"error":"Bad Request"}, which does not name the limit). So the first page fails for every rsID, before any paging, and the pass fills no gwas_effects.csv row on any module. It reports this honestly as could not ask, not as empty (the S20 shape), which is why nothing else broke. Reproduced on 2026-11-10 at 22:58 UTC against associations?rs_id=rs1421085: size=500 answers 200, and size=501 and size=1000 answer 400.

The Catalog moved, not the code. RM354 measured size=1000 returning all 386 associations of rs4149056 on 2026-11-04, so the ceiling dropped on the server some time in the six days after. The module docstring's premise, "a server that caps the size loses nothing", assumed a server that caps a large page. This one refuses it, so the paging loop never starts.

Ask 1, the page size (a patch). _PAGE_SIZE = 500, the ceiling measured today. The loop already follows _links.next, so a variant with more than 500 associations still comes back whole. Correct the docstring's premise in the same commit.

Ask 2, a guard. The reporter offers a test pinning the constant at or below the documented maximum, and names the problem with it: there is no documented maximum. 500 is measured, and the ceiling has already moved once in a week, so a unit test would pin a number that the server decides. A recorded-response test cannot see it either, since the 400 comes only from the live service. The guard that can see it is a @pytest.mark.network test that asks with _PAGE_SIZE and asserts a 200 (@network-tests-optin). It runs only when someone opts in.

Ask 3, surviving the next drop. On a 400 to the first request, ask once more with a smaller page before giving up. The cost is one request on a failure. This is not the retry @client-exception-contract forbids, which re-sends the same permanent 4xx; it is a different request. The simpler alternative is to send v2's default page size (20), which the Catalog cannot refuse. That costs requests: rs4149056's 386 associations take 20 pages instead of one, all counted in the pass's request total.

Ask 4, the 0.7 line (the reporter's correction, the same evening): a release-line decision, not a size. The 0.7 line fails too, for a different reason. Enricher 0.7.3 reads the v1 API (/singleNucleotidePolymorphisms/{rsid}/ associations), which the Catalog has retired: it answers 410 "This legacy GWAS Catalog REST API is no longer available" (reproduced here on 2026-11-11). RM354 moved the pass to v2 on main after v0.7.3, so no 0.7 tag carries it. The GWAS pass therefore fills nothing on any installable release. The consumer's released plugin stays on 0.7.x until the production registry serves 0.8, and it asks whether we would cut a 0.7.x patch that reads v2. That would be v0.7.4, cut off a branch from v0.7.3 and carrying RM354 and this item's ask 1. A patch off a revived 0.7 branch has been done once before (0.7.2, RELEASE_CYCLE). Whether to do it again is the pm's and the lead's to put to the person. The other way back is the registry moving to 0.8, and nothing here decides when that happens.

Sizing (pm, 2026-11-11). Asks 1 to 3 are one patch, urgent, about 30 minutes, and the next on main: the pass fills nothing on every module on every installable release, and the fix carries no claim of its own. It goes out as 0.8.4 with RM425, RM426 and RM427, which are already on main.

  • Ask 1 as written: 500, and the docstring's premise corrected (a server may refuse a large page, not only cap it).
  • Ask 2, yes, as the opt-in network test only: one request with _PAGE_SIZE, asserting a 200. No unit test pins the number, since the server decides it and has already moved it once in a week.
  • Ask 3, yes, in its narrow form. Only a 400 to the first request of an rsID's paging is retried, once, with no size at all, so the Catalog's own default page decides; the pass logs one warning per run naming the refused size, so the next drop is seen, not silently paid for in requests. A second 400 stays could-not-ask, as today. A 400 on a later page is never retried: by then the size has been accepted. The fix's own risk is one wasted request per rsID that the Catalog refuses for another reason, which the could-not-ask count already shows. Test it with a fake transport that refuses size=500 and answers without it.

Ask 4 is the person's: whether to release an enricher-only 0.7.4 that reads v2, off v0.7.3 (desk #252). The pm's recommendation there is the small form: gwas.py alone moves to v2 with asks 1 and 3, not RM354 whole, since RM354's other half (a *Retired type on every client) fixes nothing a 0.7 user hits, and its format-tier part was docstrings. On silence the lead builds that branch and stops: no tag, no publish.

Ask 4 declined (the maintainer, 2026-11-11, desk #252): "no for 0.7.4". No v0.7.4 will be cut. Enricher 0.7.3's GWAS pass stays broken against the retired v1 API, and upgrading to 0.8.4 is the only fix.

Built (lead, 2026-11-11), asks 1 to 3 as sized. _PAGE_SIZE = 500 with the docstring's premise corrected; GwasCatalogClient._first_page asks a refused first request once more with no size and counts it in size_refusals, which enrich_gwas adds to requests_made and warns on once per run; a later page's 400 is never re-asked. Tests: four on a fake transport (test_rm428_* in enricher/tests/test_gwas.py; three red before the change), and the live guard test_live_rm428_the_catalog_accepts_the_page_size_this_pass_asks_for, run opted in on 2026-11-11 and green, with RM354's live test beside it. test_client_exception_contract.py declares the pair (ASKED_AGAIN_DIFFERENTLY): GWAS on a 400 is asked twice, and every client now also asserts it never re-sends the same URL. Ask 4 was declined the same day (above), so the item closed with the 0.8.4 cut.

RM427 — the ClinVar-pass skip tells the reader to run clinvar pull, and no app registers it

SHIPPED 2026-11-10 on main, cut 2026-11-11 as v0.8.4 — a patch, asks 1 and 2; ask 3 declined (the pm). Severity low · Owner enricher (assertions.py, cli/pass_commands.py) · Motivating case S142 (CONSUMER_SUGGESTIONS_HISTORY.md) · related RM131, RM111, RM414

The defect. With no ClinVar snapshot reachable, the clinical-assertion pass skips, and both of its skip lines name a command no app registers: enrich_clinical_assertions logs "Provision one with just-dna-enricher clinvar pull." (assertions.py), and the assertions command prints "provision one with clinvar pull" (cli/pass_commands.py). just-dna-enricher clinvar has build, citations and publish; the fetch is cache pull --only clinvar. The reporter's walk keyed on the just-dna-* prefix and found only the first; the second is still on 0.8.2 and main. Reproduced on main with a walk of every backticked span in the three src/ trees whose first word (after an optional just-dna-*) is a group of either typer app: four hits, these two, and two pharmvar publish quotes that say on purpose there is no such command (cli/pgx_commands.py, pharmvar_build.py).

Ask 1, the wording (a patch). Name what exists, in the idiom caches.py already uses for a missing parent: cache pull --only clinvar, or clinvar build for an operator building their own. A message rewording is a patch (RM111, RM414). Pin the new phrase (@warning-text-is-api); nothing pins the old one.

Ask 2, the guard (a patch). That walk as a test: every backticked group-and-subcommand span in src/ resolves to a registered command, or sits on a named list of deliberate absences (the two pharmvar publish lines). Walk the unprefixed spans too, since the prefixed-only walk missed the second site. Typer vendors its own click, so a group is found by hasattr(cmd, "commands"), not isinstance (the same trap as the docs generator's, in @a-docs-site-nav-is-a-registry-over-a-directory-that-grows). Prove it by reintroducing clinvar pull and watching it fail.

Ask 3, a structured remedy key (a minor). A field on hints.Finding, and on whatever carries a validate or compile warning, naming the registered command that clears it, so a consumer maps by key rather than by reading the prose. A new public field, so a minor, and main takes patches only. Two facts for the sizing. The compile and validate channel already has a key of this kind: RM131's warning codes, one code per remediation by rule, so a consumer can already map those by code. The gap is the enricher's logger.warning lines, which carry no code, and this skip is one of them. The reporter's own reason against stands: a key covering only part of the remedies may mislead more than an honest text match, and ask 2 keeps the quotes true without it.

Sizing (pm, 2026-11-10). Asks 1 and 2 are one patch, unattended, about 45 minutes, built in one commit so the test is proved red on the old wording before the new one lands. The skip fires on every machine that has no ClinVar snapshot, which is the usual first run, and the command it names fails, so the reader is stuck on the first step. A hand check has also already missed it once: the reporter read the CLI's copy as gone on 0.8.2, when it had moved from cli.py into cli/pass_commands.py unchanged. So the walk earns its place: it is a test only, adds no public surface, and its list of deliberate absences holds the two pharmvar publish lines and nothing else. A new entry on that list needs a sentence saying why the command does not exist. Ask 1 takes cache pull --only clinvar as the remedy and names clinvar build second; the docs quote neither old line (checked with a grep of docs/ and the READMEs), so the change is the two src/ lines and their pins.

Ask 3 is declined, not parked. A remedy key on the enricher's log lines would be a new public field to save one lookup that ask 2 already keeps honest, and the reporter's own objection (a key that covers only some remedies misleads) still stands. It comes back only through a new Sn from a consumer that maps enricher warnings by key and can show a wrong mapping from the text.

Residuals won't fix — ask 3, a remedy key on the enricher's log lines, declined by the pm (2026-11-10), above; it comes back only through a new Sn.

Built (2026-11-10), triage on the lead's hand-over. Both skip lines now name what the apps register: the log line reads "Provision one with just-dna-enricher cache pull --only clinvar, or build your own with just-dna-enricher clinvar build.", and the assertions command prints "skipped: no ClinVar snapshot reachable (provision one with cache pull --only clinvar, or build one with clinvar build)". A test in enricher/tests/test_clinical_assertions.py runs the real pass and the real command with nothing provisioned and pins both phrases. enricher/tests/test_quoted_commands.py walks every backticked span in the three src/ trees, prefixed with just-dna-* or not, and resolves each group-and-subcommand path against the trees typer.main.get_command builds for both apps; its list of deliberate absences holds the two pharmvar publish lines, each with its reason, and the test asserts the list equals what the walk finds, so an exemption whose quote is gone fails too. Proved red on the old wording first: it named exactly assertions.py:254 and cli/pass_commands.py:519. No public name, field or check result moves.

RM426 — GeneLocusConflict's message settles which half of the pairing is wrong, and it guesses the rsID

SHIPPED 2026-11-09 on main, cut 2026-11-11 as v0.8.4 — a patch, the wording only; ask 2 declined (the pm). Severity low · Owner enricher (identifiers.py, GeneLocusConflict.__str__) · Motivating case S141 · related S24, @gene-locus-relationship, @rsid-absent-two-readings, @absence-is-weighted-by-the-base-rate

The gap. The finding's first sentence is the fact: the row pairs a gene with a variant on another chromosome. The last one then names a cause, "a real symbol beside an invented rsID is what a machine-written summary produces", written from S24, where four of one reporter's seven rows were that. S141's probe was the other half: MTHFR beside rs1801394, a real rsID in MTRR, so the gene was wrong. An agent reading the message looks for "the real rsID of MTHFR A66G", which does not exist. The check sees a false relationship and cannot see which member is false; @absence-is-weighted-by-the-base-rate makes naming both readings the floor, and no measurement here says which leads.

What it would be.

  1. The patch (wording). Name both readings and the step that tells them apart: either half may be the error (an invented rsID beside a real symbol, or a real rsID paired with the wrong gene); look the rsID up and see which gene it sits in. No lookup, no field, no code.
  2. The minor (S141's ask 2). When consequences.csv beside the spec lists transcripts for the variant, name their genes ("consequences.csv places rs1801394 in MTRR"), silent otherwise. Read-only and on disk, as _variant_chromosomes already reads resolution.csv; resolution.csv itself carries no gene. The genes have to reach the message through a new field on the public GeneLocusConflict, which is what makes it a minor.

Sized, the pm (2026-11-09): the wording as a patch, next on main; ask 2 declined, not parked.

  • The wording is a patch on one condition: the first sentence stays byte for byte (@warning-text-is-api). It states the fact and is what a reader greps; only the closing sentence, the guessed cause, changes. Under 10 minutes, so urgent: whoever the lead hands it to builds it now.
  • Ask 2 is declined, with its reason, rather than parked under a new number. Once the wording says "look the rsID up and see which gene it sits in", the gene from consequences.csv saves the reader one lookup, and only when that file is beside the spec. A new public field on GeneLocusConflict for that is a minor whose value is one lookup, and a minor takes the zones the maintainer names. It comes back only through a new Sn showing a reader who still picked the wrong half after the new wording.
  • At closure, the **Residuals** line says ask 2 was declined here, so no new item is owed for it.

Residuals won't fix — ask 2 declined by the pm (2026-11-09), above; it comes back only through a new Sn.

Built (2026-11-09), triage on the lead's hand-over. GeneLocusConflict.__str__'s fact sentence is byte for byte what it was; the closing sentence names both readings and the lookup (Either half may be the wrong one: a real symbol beside an invented variant, or a real variant paired with the wrong gene, and a machine-written summary produces both. Look up which gene <variant> sits in, then check the row against the source you took it from.). It says "variant" rather than "rsID" because a variant_key may be positional. The class docstring records S141's case. A test in enricher/tests/test_identifiers.py runs S141's row (rs1801394 beside MTHFR) through check_identifiers and pins the unchanged fact sentence as a prefix, the new phrases, and the old guess's absence. ENRICHER's paragraph on the check quotes both sentences. No code, field or check result moves.

RM425 — ExpressionEffectRow.effect_size's description says "aggregated over the tracks"; it is the single strongest track

SHIPPED 2026-11-09 on main, cut 2026-11-11 as v0.8.4 — a patch, wording only. Owner format (schema/src/just_dna_format/expression.py), severity low. From S140 · related RM111, RM200

The gap. The field's description reads "The magnitude, aggregated over the scorer's tissue tracks for this gene." The enricher's _summarise keeps the single strongest finite track with its sign (max(finite, key=abs)), and both its docstring and SCHEMAS.md ("effect_size and effect_direction answer different questions and may disagree") say so. The description is the one place that does not, and it is the one describe / authoring_reference hand an agent. S140 measured the consequence: 128 of 819 and 24 of 126 rows carry a size whose sign contradicts effect_direction, each correct, each readable as a broken row through "aggregated", and a reader ranking by |effect_size| believes they rank a summary.

What it would be. One sentence in the description, as @field-description-is-a-claim asks: make the string true rather than soften it. The strongest single tissue track for this gene, sign kept; it may disagree with effect_direction, the majority sign, and is real when it does. effect_direction's own description is already right. No field, type, vocabulary or published byte moves (a description reaches json_schemas() and the authoring reference, never an artifact), so a patch, as RM111's description fixes were.

Residuals none

Built (2026-11-09), triage on the lead's hand-over. The description now names the single strongest track, its sign kept and not an aggregate, says it may disagree in sign with effect_direction (the majority sign) and is real when it does, and that ranking by its absolute value ranks each variant's most extreme single tissue. effect_direction's description was already right and is untouched. A test in enricher/tests/test_expression.py ties the phrases to _summarise's behaviour on the nine-up, one-hard-down case (it fails on the old text, which lacks "single strongest"). No field, type, vocabulary or artifact byte moves.

RM423 — record_verification re-signs the records of checks it did not re-run over authored bytes they never saw

SHIPPED 2026-11-09 on main, cut 2026-11-09 as v0.8.3 — a patch. Owner format (merge_records) + enricher (record_verification), severity high.

Residuals RM424 (candidate 2, a per-record module_hash on VerificationRecord; parked, a minor).

Built (2026-11-09), for the lead. The pm's shape, unchanged. merge_records starts from the existing records only when existing_still_binds is true; with False the result is fresh alone, newest-wins among its own records, so the RM72 skip rule needs no change (it already read existing_still_binds). record_verification, when it read a document whose module_hash differs from the binding, logs one warning naming every check it held that this run did not put (… not re-signed over these: <checks>. Re-run the check(s) …), sorted, once per run. The closure rule (RM73) is untouched. Both docstrings now say the RM45 carry holds while the bytes stand still; ENRICHER gained the matching bullet, and features/enricher/verification_checks.feature a scenario. No public name, field, flag or warning code moves. Declared (P3, a corrected derivation): CHANGELOG, and INTEGRATION_0_8 § 4, which also says the fix does not repair a document already written that way (its module_hash matches the bytes, so a later run carries the records on until the bytes move again; re-run the named checks or delete the file).

Two tests, each seen red on the previous main:

  • test_a_check_this_run_did_not_put_is_not_carried_over_bytes_that_moved (format, test_verification.py): with existing_still_binds=False the merge is this run's records only and newest-wins among them; with the default the earlier record stands. Red on main with reference_allele carried through.
  • test_a_later_command_does_not_re_sign_a_check_it_did_not_put_over_moved_bytes (enricher, test_verification_record.py), S139's probe on the real commands: grch37_build plus rs1801394 (MTRR A66G, at its GRCh37 position), check-identifiers --no-traits over HGNC on a mock transport (gene_locus_agreement, subjects 4), then the row removed and enrich --offline run, which never puts that check. bytes_moved: the record is gone, the document is bound to the current bytes, and one warning names every check check-identifiers put and enrich does not, gene_locus_agreement among them. bytes_unchanged: the record stands unchanged and nothing is logged. Red on main for bytes_moved (the four-row record re-signed over three rows); bytes_unchanged green on both, pinning the default.

Filed by triage (2026-11-09) from S139 (just-module-creator's liaison, their F139), reproduced by them on enricher 0.7.3 and 0.8.2. Confirmed in the code: verification.merge_records keeps every record for a check absent from fresh whatever existing_still_binds says (the flag only lifts RM72's skip protection), and record_verification then signs all of them under the binding of the bytes as they are now. The closure is dropped when the bytes moved (RM73); the check records are not. So enrich's own docstring ("an author who edits variants.csv after this ran gets the block dropped at compile with a warning") stops holding after any later run that writes the file.

Severity high (the reporter's reading, and RM45's: a forged pass is worse than silence) · Status open — a patch, the next on main (the pm, 2026-11-09; the patch half only, the minor half parked) · Owner format (merge_records) + enricher (record_verification) · Motivating case S139 · related RM45, RM72, RM73, RM284, RM292

Both directions. A stale finding published (the probe: gene_locus_agreement on rs1801394, after the author removed it), and a stale pass published, the direction nothing shows: a findings=0 record from before rows were added is re-signed over them, so the attestation says a check covered rows it never read. Per-record checked_at survives, and nothing compares it.

Two candidates, the reporter's.

  1. Patch: when existing_still_binds is false, carried records are dropped, plain newest-wins over fresh only; the closure's own rule. No new name. The cost is RM45's argument ("not asked this time" becomes "never asked"), answered by the same docstring's skip paragraph: after an edit, the earlier answer is about other rows. A corrected derivation, so it ships declared (P3), and the dropped checks are logged by name.
  2. Minor: a per-record binding (module_hash on VerificationRecord), each record read as stale on its own. Keeps the history and shows which checks are current. A new field: 0.9 or later.

The reporter leans 2 for the record and 1 as the interim.

Sized, the pm (2026-11-09): candidate 1 as a patch, the next on main; candidate 2 parked.

  • The patch is merge_records' own reasoning, applied to the case it left out. Its docstring already says that once the authored bytes have moved, an earlier answer "describes rows that no longer exist", and on that ground it lifts RM72's protection of a ran record over a fresh skip. A record for a check the new run did not put at all is the same stale answer, so with existing_still_binds=False the result is fresh alone. RM45's argument ("not asked this time" becomes "never asked") does not reach this case: about these bytes, the check was never asked. The default stays True, and nothing changes while the bytes have not moved.
  • Real-run frequency is high. Every second pass meets it: an author edits a table after enrich, then runs any command that writes verification.json. The harm is the worst kind the document can carry, a signed pass over rows the check never read. That puts it first on main, ahead of RM422 and the queued RM400, RM401 and RM403.
  • Declared, never silent (P3, release class is not staleness). A corrected derivation of a public function's output. A CHANGELOG line; an INTEGRATION_0_8 § 4 known issue saying that a verification.json written by format or enricher 0.8.2 or earlier, over bytes edited since an earlier run, may carry records of checks that run never put, and that a record whose checked_at is older than the edit is the sign; the run logs each dropped check by name.
  • The test, the reporter's probe as the fixture: enrich, remove rs1801394 from variants.csv, run one command that writes verification.json without gene_locus_agreement; the record for that check is gone, the log names it, and with the bytes unchanged the same sequence keeps it (both arms, so the default's behaviour is pinned too).
  • Candidate 2 (a per-record module_hash on VerificationRecord) is parked. A new field is a minor, and the maintainer's rule is that a minor takes the zones they name, nothing by default. Unparks when a reader asks to see which checks are current without re-running them, or wants the history the patch now drops. Either can happen while it is parked. At RM423's closure it is the **Residuals** line's item, filed then under its own number (RM424).

RM422 — a resolution.csv row for a variant no authored table names compiles silently, and publishes

SHIPPED 2026-11-09 on main, cut 2026-11-09 as v0.8.3 — a patch. Owner compiler (fact_checks._cross_check_resolution, called from validate_spec), severity low.

Residuals none

Built (2026-11-09), by triage on the lead's hand-over. _cross_check_resolution(rows, subjects, studies) beside the other arms, called once, in validate_spec, over every injected row: compile_module runs that pass and keeps its warnings, so a second call there would publish the count twice. The subject set is validate's module_subjects over every authored row (identities come from authored rows only; the table widens positions, never identities, so a row cannot vouch for itself), plus each study's proxy_rsid, which enrich resolves on purpose (RM331). A row is the module's when its variant_key or rsid is one of them. Withheld when a locus table loaded no row. Counted per identity. The remedy names deleting the rows, not enrich --rederive: a re-derivation never shortens a table. A warning in both modes, the pm's condition. No new code, name or field. Tests in compiler/tests/test_resolution_orphan.py, the first seen red on the previous main: the reporter's shape (cyp2c19_star_alleles, no variants.csv, plus rs1801394's row) names exactly rs1801394 in both modes and never as an error; the compile publishes it once; longevity_studies' proxy row is silent until its proxy_rsid is blanked, then named; and no reference example warns.

Filed by triage (2026-11-09) from S138 (just-module-creator's liaison, their F137), reproduced by them on compiler 0.7.2 and 0.8.2 under compile --strict; trunk has no compiler change since v0.8.2. Confirmed in the code: no check compares resolution.csv's rows with the module's subjects. Every check over the table asks about rows an authored table names (subjects.identity_placements keys off the authored row's variant_key/rsid), so a row whose subject the author removed is read by nothing and hashed into manifest.derived.

Severity low · Owner compiler (fact_checks beside the six derived_row_orphan arms) · Motivating case S138 · related RM43, RM337

The case. enrich writes resolution.csv for three rsIDs in variants.csv. The author drops one (rs1801394), then replaces variants.csv with haplotypes.csv + diplotypes.csv over the other two. Nobody re-runs enrich, so enrich's "delete it first, or stale rows persist" note never reaches them. Strict validate and compile name nothing, and a publish ships a placement for the variant the author removed. The reporter measured the reach: the row reaches no parquet (artifact_digest and content_signature unchanged), only resolution_signature and the derived entry's hash move, so what ships is the sidecar file.

What it would be. One more derived_row_orphan arm: "resolution.csv places N identity(ies) no table in this module names: [...]", a warning in both modes like the other six. The subject set is module_subjects over authored tables only, so a resolution row never vouches for itself, and the PGx tables count (RM43 put them under resolution). It reuses the code, so no new public name and no new code: patch scope, unlike RM337, which needed a new code. Emitted from validate and compile with the message dedupe the other arms use; a COMPILER.md catalogue line, an INTEGRATION_0_8 row, a CHANGELOG line, and the reporter's spec as the fixture (exactly one orphan, rs1801394).

Not in it. The clin_sig_* pair already has its arm (the concordance one, reading variants.csv only, by design). fully_resolved: True (over 0 variant row(s)) beside a three-row table reads variants.csv while resolution reaches the PGx tables; that is a manifest value, so it is a question of its own, not this patch.

Sized, the pm (2026-11-09): a patch, built unattended, after RM423.

  • Triage's reading holds. One more arm under a code that exists, the subject set already computed (module_subjects), the six arms' dedupe. No public name.
  • One condition makes it a patch: it stays a warning under strict, as the other six arms do. A module that compiles under --strict on 0.8.2 must still compile on 0.8.3; a refusal would be a minor.
  • Real-run frequency is moderate and the harm small. Any author who edits tables after enrich and does not re-run it meets it; what ships is a sidecar row for a removed variant, and no parquet moves. Severity low stands.
  • The fully_resolved denominator stays out, as the entry says. It is a manifest value, so changing it is not this patch; it gets an item only if a reader is misled by it.

RM421 — eleven of fourteen bulk downloads set no read timeout, so a stalled connection is never stopped

SHIPPED 2026-11-08 on main, cut 2026-11-09 as v0.8.3 — a patch. Owner enricher (net.stream_to_file and its callers), severity low.

Residuals none

Built (2026-11-08), for the lead. The pm's shape, unchanged. stream_to_file's timeout defaults to a private net._BULK_TIMEOUT = 120.0 instead of None; the signature still reads float | None, a caller's own value wins, and an explicit None is still passed to httpx as no timeout (no caller in the package passes one, and the walk below refuses it, so that way back stays a decision rather than an accident). Not a knob: no environment variable and no setting. The three builders that named 120 s (civic_build, clinvar_gkm_build, mane_build) no longer pass it, so the value lives in one place and none of the three goes stale on the first change. httpx applies the value to connect, read, write and pool; the read half bounds the gap between two chunks, so a slow mirror that keeps sending is never cut off, and a silent one raises httpx.ReadTimeout, a TransportError, which the existing retry takes and the existing arm translates to the lane's error_cls on giving up. No public name, field, flag or warning code moves.

Three tests, each seen red on the previous main:

  • test_a_silent_server_is_given_up_on_by_the_default_timeout (in test_an_interrupt_stops_a_bulk_build.py, beside RM409's): a local server that accepts the connection and sends nothing; a call that names no timeout, with the default shrunk to 0.25 s through the function's __kwdefaults__ (the private seam a keyword-only default has; a module constant cannot shrink it, because the default is bound when def runs), raises OpenTargetsUnavailable whose cause is httpx.ReadTimeout, leaves no .part, and does it inside a 10 s join on a daemon thread, so a regression fails rather than hangs the suite. It first pins that the shipped default is a positive float, which is what the seam stands in for. Red on main there; with the body mutated to pass timeout=None to httpx, it fails on the join bound ("still blocked on a silent server after 10.0s").
  • test_no_bulk_download_runs_without_a_timeout (in test_bulk_download_contract.py): an AST walk over the package resolving each stream_to_file call's effective timeout, its own timeout= or else the definition's default, and refusing a literal None from either side (and a **kwargs spread, which cannot be read). Not escapable by passing the function on as a value: every reference to it (a bare name or net.stream_to_file) must be the callee of a call the walk read, and the walk must read at least one. Red on main with exactly the eleven call sites this item listed plus the definition's own default; red again when one caller is mutated to pass timeout=None, and when a module that already calls it also binds _fetch = stream_to_file (or another binds net.stream_to_file) without a call the walk can read.
  • test_the_default_timeout_reaches_httpx_and_a_callers_own_wins: no timeout= reaches httpx as 120.0, 5.0 as 5.0, and an explicit None as None.

Filed by the lead (2026-11-08) from RM409's build, which named it as a won't-fix residual of its own rather than widen into it. net.stream_to_file's timeout defaults to None and is passed to httpx.stream as is, so a caller that names none gets no connect, read or pool timeout. Only three of the fourteen call sites name one (civic_build, clinvar_gkm_build, mane_build, 120 s each); clinvar_build (twice), constraint_build, drug_labels_build, mitomap_build, strchive_build, clinpgx_build, pubmind_build and opentargets_build (listing and every part) name none.

Severity low · Status open — a patch, unattended (the pm, 2026-11-08; about 20 minutes) · Owner enricher (net.stream_to_file and its callers) · Motivating case RM409's build · related RM409, RM403

The gap. A connection that stalls without sending a byte (a half-open TCP session, a server that accepted and went quiet) blocks the read forever: no retry fires, because nothing raises, and RM403's retry lines never print. RM409 made a pool's workers stop between chunks, but a worker blocked inside a read never reaches the check, so even Ctrl-C cannot end that part. Not seen in a run yet; it is read from the code.

What it would be. A read timeout on every bulk download, so a stall raises httpx.ReadTimeout, which stream_to_file already retries as a transport error and translates on giving up. Either a default in stream_to_file (a read timeout generous enough for a slow mirror, since a timeout bounds the gap between chunks, not the whole download) or each caller naming one. A default changes no signature and adds no name, so it looks like a patch; the value, and whether it is a knob (@retry-attempt-floor), are the pm's.

Sized, the pm (2026-11-08): a patch, built unattended, after RM400, RM401 and RM403.

  • Built although no run has met it, unlike RM419. The fix carries almost no risk of its own, and the failure it prevents is the worst kind for an unattended run: a rebuild that hangs with no line printed, which no retry, no stop flag and no watcher catches. RM419's fix, by contrast, makes claims about services nobody measured.
  • One default in stream_to_file, never per caller: timeout=120.0 instead of None, the value three builders already pass. httpx applies it to connect, read, write and pool alike, and the read half bounds the gap between two chunks, not the whole download, so a slow mirror that keeps sending is never cut off. A caller that names its own keeps it. The signature keeps float | None, so a caller may still ask for no timeout on purpose.
  • Not a knob. @retry-attempt-floor makes a constant a knob when two deployments want different values of it; nobody has asked for a different one, and the three callers agree on 120 s. It becomes a knob on the first such ask.
  • The test: a local server that accepts the connection and sends nothing; stream_to_file, given no timeout of its own, raises the lane's translated error within a bounded time instead of blocking (the test may shrink the default through a private seam so it runs in seconds). And an equality over the call sites: none passes timeout=None by accident.

RM409 — Ctrl-C does not stop opentargets build or its rebuild while parts are downloading

SHIPPED 2026-11-08 on main, cut 2026-11-09 as v0.8.3 — a patch. Owner enricher (net.stream_to_file, opentargets_build.download_release, alphagenome_avi_build.build_snapshot), severity low.

Residuals won't fix — opentargets_build._source_digest hashes the mirrored parts on a pool of eight and an interrupt there still waits for each in-flight part's hash, which is seconds of local disk reads and not a download · RM421 — a part whose connection stalls without sending a byte is stopped only when its next chunk arrives, because stream_to_file sets no read timeout unless its caller names one; filed as a defect of its own rather than widened into this build

Built (2026-11-08), for the lead. The mechanism is confirmed: a test that interrupts the mirror while four parts stream slowly from a local server waited three to eight seconds on the previous main: the in-flight parts streamed to their end first. The fix is the shape the item gave. net.stream_to_file takes a private keyword _stop (a threading.Event), checked before the request opens and before each chunk is written; once set it raises a private _StreamStopped, which the retry does not take for a transport error and which the existing except BaseException arm lets through after removing the .part, so a stopped part never lands. It subclasses BaseException, as GeneratorExit does, because it is a stop and not an error a caller handles: no except Exception may take it for a failed download, and the error roster in ENRICHER.md (what a caller catches, asserted equal to the package's Exception subclasses) stays as it was. A retry's backoff waits on the flag rather than sleeping, so a part that is between two attempts (up to thirty seconds of backoff) stops at once too. Every other caller passes nothing and is unchanged. download_release sets the flag in its except BaseException arm before the shutdown, so the queued parts are cancelled as before and the in-flight ones stop within a chunk; the with exit and the interpreter's own join then find the workers gone. A part that finished before the stop stays on disk and the next run resumes past it.

The flag is set on any exception, not only on KeyboardInterrupt, because the arm's own comment promised that the first failure "surfaces now", and with parts in flight it surfaced only once up to seven of them finished. The cost is that those seven are fetched again on the next run; the benefit is that the failure is reported when it happens.

The class, checked. grep ThreadPoolExecutor over the enricher finds three pools. The AlphaGenome AVI build (alphagenome_avi_build.build_snapshot) had the same shape and worse: pool.map over _build_contig, one contig per worker through a tabix subprocess, so an interrupt that reached only Python waited for every in-flight contig, tens of minutes each on the real artifact (at a terminal, Ctrl-C would also reach tabix through the process group and end the stream sooner, but not a contig already assembling, and assembly is serialised on _ASSEMBLY). It is fixed the same way: a private _stop checked before each block _stream_lines reads and again before the assembly, the pipe closed under tabix on a stop and its nonzero exit not reported as a failure of the file, and the pool driven by submit with the same except BaseException arm. release.json was already withdrawn before the first contig, and a contig's scratch directory is cleared by its next build, so a stopped build leaves nothing a reader believes. The third pool, _source_digest, is local hashing and is named above. The single stream_to_file callers on the main thread are not this class: an interrupt lands in the streaming loop itself. literature's regex worker is a killable process by design (@regex-timeout-process). The lane adapters in caches and the cache commands catch Exception, so a KeyboardInterrupt still ends a cache rebuild rather than moving to the next lane.

Tests: enricher/tests/test_an_interrupt_stops_a_bulk_build.py, three, each seen red: the mirror interrupted mid-part (3 to 8 s on the previous main, under 1 s now, with no part left on disk), the AVI build interrupted mid-contig through a stand-in tabix (≈3 s before), and a stop during a retry backoff (≈2 s before). The interrupt is delivered by the pool's own future.result() once every worker is mid-stream, never by timing. Removing stop.set(), the per-chunk check or the backoff wait each turns its test red.

Open, filed by the lead (2026-11-07) from the maintainer's run: cache rebuild --only opentargets --publish, interrupted about five minutes in (~1 GB of ~22 GB), ignored two Ctrl-C and had to be stopped with SIGTERM to its process group.

Severity low · Status open — a patch (no surface moves) · Owner enricher (opentargets_build.download_release) · related RM333, RM408

Mechanism, read from the code, not yet reproduced in a test. download_release fetches parts on an eight-thread ThreadPoolExecutor. A KeyboardInterrupt in the main thread's future.result() reaches except BaseException, whose pool.shutdown(wait=True, cancel_futures=True) cancels the queued parts but waits for the eight in flight, each a large part streamed to the end by stream_to_file; the with block's exit and the interpreter's exit join the same worker threads again. So an interrupt lands only after every running part finishes. It is the only bulk download in the enricher on a thread pool (grep shutdown(wait=True, cancel_futures=True)).

Shape of a fix. A stop flag the workers' streaming loop checks between chunks (so stream_to_file, or a wrapper around it, owes a cancel hook), set on interrupt before the shutdown; the .part staging already keeps a half-written part from landing under its name. The test interrupts a mirror whose parts stream slowly from a fake server and asserts it returns within a chunk's time.

RM420 — cache pull never fetches a newer published release over a whole cache

SHIPPED 2026-11-08 on main, cut 2026-11-09 as v0.8.3 — a patch. Owner enricher (download._provision_snapshot, download._provision_root_file_snapshot, cache pull, caches.prepare_lane), severity medium.

Residuals won't fix — a STRchive catalogue pulled before this patch carries no pull record, so nothing says it was pulled and it is left alone, named with both labels, until its operator moves it aside and pulls once

Built (the lead, 2026-11-08), to the pm's sizing. cache pull and cache prepare pass a private intent, download._FollowHub, to the lane's ensure as the keyword _follow_hub; every other caller passes none, so enrich still returns a whole cache without reading the hub (a test replaces HfFileSystem with one that fails if touched, and an AST test holds that exactly the three provisioning call sites pass it). The intent carries the lane's own release_label, applied to the cache and to the repo's release.json (then manifest.json, which is where Ensembl states its release) staged in a scratch directory, so no reporter composes a label. Where the labels differ:

  • a cache that came from a pull of the lane's repo is re-pulled down RM372's switched-repo path, not a second one: a file is kept only where the new manifest attests it by sha256, without a manifest none is, sidecars are refetched and a root file the repo no longer has is removed. release.json is withdrawn right before the first byte moves and fetched last (@snapshot-layout-locations), so a refresh cut short states no release and the next pull finishes it;
  • a cache that did not is left alone and printed with both labels and the move-aside remedy. The witness is the pull record, which only the provisioner writes (no builder does; checked, the one writer is download.py). The record now also states the sha256 of the release.json the pull placed, so a builder pointed at a pulled cache, whose commit writes another, is not taken for the pull. A record without the key, from before this patch, is read as the pull it was: that is what reaches the motivating machine, whose constraint record dates from 2026-11-04;
  • an unrecorded cache (RM339's case) with a label of its own that differs is left alone too, where cache pull used to compare it with the listing, write a record and replace its release.json with the hub's, after which nothing could tell the build from a pull. An unrecorded cache that states no release is no builder's, and is completed as before.

A hub that cannot be read, or that states no release, serves the cache as it is. No lane owns an ordering over its labels (CacheLane.release_label reads, it does not compare), so a pulled cache follows the hub whichever way the labels differ, the pm's rule for an unorderable pair; adding a comparator would have been a new name. The class was checked over every lane cache pull reaches: the eleven parquet lanes, Ensembl's (ensure_snapshot, manifest release_id) among them, share _provision_snapshot; STRchive's root-file provisioner had the same shape and no pull record at all, so it is fixed the same way and writes a record from now on (its file list empty, since one parsed rename leaves no unfinished state). The five lanes with no ensure are not pulled. prepare_lane used to call a recorded cache and STRchive present without reaching ensure; both reach it now, and a refresh is reported by the labels, since a re-pulled gnomad_constraint.parquet changes no file name; a re-pull that began and broke is reported as a failure there (it exits 1, as cache pull does), never as "already provisioned". Tests: test_cache_pull_follows_the_hub.py, eighteen: fifteen of the first seventeen run red on the previous main (the two enrich-path ones pin today's behaviour), the eighteenth (prepare's broken re-pull) seen red with its branch removed, and each part of the fix mutated on purpose turned at least one red.

Filed by the lead (2026-11-08) when the maintainer ran 0.8.2's own boundary step on this machine, cache pull --only constraint --only clinvar --only civic --only strchive --only mitomap, after gnomAD 4.1.2 was published: it printed on disk: … and left gnomad_constraint at gnomad_v4.1_constraint (built by 0.7.0) while just-dna-seq/gnomad_constraint serves gnomad_v4.1.2_constraint. STRchive is behind the same way (strchive_v2.26.0 here, strchive_v2.28.0 published). ClinVar, CIViC and MITOMAP matched the hub only because nothing newer had been published since their last pull.

Severity medium · Status open — a patch, the next on main (the pm, 2026-11-08), ahead of RM400, RM401 and RM403 · Owner enricher (download.ensure_parquet_snapshot, cache pull, cache prepare) · Motivating case the 0.8.2 boundary on this machine · related RM410, RM372, RM339, RM411

The gap. ensure_parquet_snapshot returns a cache at once when its parquet files are whole, its pull record complete, its repo unchanged and its manifest covers it, without reading the hub (RM339's "a cache whose pull record says the pull finished is trusted without touching the network"). RM372 re-pulls only when the repository moved. Nothing compares the local release.json with the published one, so once a machine has pulled a lane, no later release of that lane reaches it through cache pull or cache prepare.

What the documents promise instead. Every one of these tells the operator that a pull moves a lane to the newer release, and each is a silent no-op on a machine that already holds the older one:

  • the 0.8.2 GitHub release notes, "What you must do at the boundary", step 2 (cache pull --only constraint --only opentargets; Open Targets is new, so only constraint is affected);
  • docs/INTEGRATION_0_8.md § 4, "cache pull brings 4.1.2 once published", and the upgrade order's step 5, "pull the lane first (cache pull --only <lane>)";
  • the derived-layer Dataset currency (derived tables) warning, whose remedy for a stale snapshot is cache pull --only <lane>; a re-derivation after that pull reads the same old snapshot and repeats the line.

Workaround today: move the lane's directory aside and pull, e.g. mv /data/just-dna-cache/gnomad_constraint /data/just-dna-cache/gnomad_constraint.v4.1 && just-dna-enricher cache pull --only constraint.

What it would be. cache pull and cache prepare, the explicit provisioning commands, read the published release.json and re-pull a lane whose published release differs from the local one (keeping a file only where the new manifest attests it, as RM372 does). An unreadable hub keeps today's answer: the cache serves as it is, with the warning. enrich's own ensure call keeps trusting a whole cache without the network, so a warm cache still serves offline and an enrichment never downloads a new release mid-run. Whether the published release is newer, or only different, is a label comparison the lane already owns (@the-reporter-cannot-compose-a-lanes-label). No public name needs to move, so it looks like a patch; the size, and whether the 0.8.2 release notes are corrected now, are the pm's.

Sized, the pm (2026-11-08): a patch, the next on main, severity medium.

  • Every upgrading machine meets it. The boundary step is written for machines that already hold a lane, and those are exactly the ones the pull skips. It is not a rare path: it is the documented one, and it failed on the first machine that ran it. So it goes ahead of the queued patches (RM400, RM401, RM403), not behind them.
  • The class is a patch. cache pull and cache prepare are asked to do what the release notes, INTEGRATION_0_8 and the currency warning already say they do. No public name moves, and enrich's own call keeps today's trust.
  • The fix's own risk: a pull replacing a snapshot built on this machine. This machine builds snapshots and then publishes them; between the build and the upload the local lane is newer than the hub's. A pull that re-pulls on any differing label would put the older published release back over it. So the build must keep a lane that was built here: a lane re-pulls only when the cache came from a pull of that repo and the published label differs; a lane built here is reported with both labels and left alone. How the pull tells the two apart is the lead's (the pull record, or what a rebuild writes); the test that holds it: build a lane locally, publish an older label to the fake hub, run cache pull, and the local bytes are unchanged and the report names both labels.
  • Newer or only different. The lane's own label comparison decides where it can order the two; where it cannot (a digest label against a dated one, @currency-asks-the-source-not-the-cache), a pulled cache follows the hub, since the operator asked for the hub's release by running cache pull.
  • Not in the fix: enrich never downloads a release mid-run, and an unreadable hub serves the cache as it is (both as the entry says).

Corrected now, before the fix (the pm, 2026-11-08):

  • The 0.8.2 GitHub release notes get a correction line under step 2: on a machine that already holds the constraint lane, cache pull leaves it at 4.1 (RM420); move the lane's directory aside, then pull. The release is published, so this edit is outbound: the lead's if its grant covers editing a published release's notes, otherwise the person's.
  • INTEGRATION_0_8 § 4 gets an RM420 known-issue line with the same workaround, and its RM410 line, "cache pull brings 4.1.2 once published", is corrected to name RM420 for a machine that already holds the lane. The lead's edit, on main.

RM418 — every NCBI client builds its own pacing gate, so two in one process pace against two budgets

SHIPPED 2026-11-08 on main, cut 2026-11-09 as v0.8.3 — a patch. Owner enricher (eutils.EutilsClient, net._service_gate), severity low.

Residuals RM419 (the same class beyond NCBI: the two Ensembl REST clients first, and every other client that builds its own gate); RM404 (a host running enrichments as separate processes still needs to pass one client in, 0.9; the registry was asked which it does on 2026-11-07, unanswered here).

Built (the lead, 2026-11-08), to the pm's sizing. net._service_gate(service, interval) hands out one PacingGate per (service, interval) per process, made under a lock on first use. EutilsClient built without a gate takes _service_gate("ncbi-eutils", interval); a gate handed in is used as handed. The service is in the key, where the item said "one gate per min_request_interval", because keyed NCBI and Ensembl's LD endpoint both pace at 0.1 s and are unrelated budgets; and so RM419 can reuse the registry. Every new name is private. A shared gate's spent now counts every default-built client's attempts against NCBI, which is what a host metering egress per upstream wants (S95). The enricher conftest resets the registry before every test (_fresh_service_gates), so no test waits on a slot another one claimed. Tests: test_one_ncbi_gate_per_process.py, five; on the previous main two default clients held different gates.

Filed by the pm (2026-11-07) from the registry lead's ask (agent-chat, 638423336, via triage): RM404 in a 0.8.x patch, because the registry runs an upgrade sweep's online modules one at a time while the dbSNP merge check builds an unshared client per run. RM404 stays in 0.9, since a new public parameter never lands on main; this is the part a patch can carry.

The gap. EutilsClient.__post_init__ makes a fresh PacingGate whenever it is not handed one, and both callers build their own client (identifiers.check_rsids, and the literature pass). NCBI limits requests per API key or per address, not per client, so two clients in one process each pace to the full rate and together exceed it. A host running enrichments in parallel must serialize them, or be throttled. Since RM398 the same client is also the placement witness's.

What it would be. A client that builds its own gate takes the process's gate for its interval instead: one private, module-level gate per min_request_interval, made under a lock on first use. The gate already locks the bookkeeping and not the sleep (@shared-pacing-gate), so threads share it safely. No public name moves, and a gate handed in explicitly is still used as handed. Test: two clients built without a gate share one, and requests from both, run on two threads, are spaced by the interval.

What it does not do. It helps only inside one process. A host that runs enrichments as separate processes keeps its lock until RM404 lets it pass one client in; the registry was asked which it does (2026-11-07). The sequence proxy's missing timeout stays RM404's.

RM415 — bins_ungrounded said "no bin pmid" on a module whose bin carries one

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.2 — a patch (S137, just-module-creator's liaison). Owner compiler, severity low.

The class: a clause written for one arm of a count, printed for every arm. The warning's numerator is right (the rows with no pmid), but the sentence after it, "the module records no grounding evidence at all (no studies.csv rows, no bin pmid)", was fixed text written for the case where every bin is uncited. On the plugin's four-bin HTT module, whose 36-39 bin cites 27335115, it said "3 of 4 … no bin pmid", so an author could read it as the pmid they set not being read.

Instances (one): compiler/binning_checks._check_binning_grounding now chooses the clause by whether any bin cites: none keeps the old sentence; otherwise "carry no grounding evidence of their own (no bin pmid, and no studies.csv rows; N other bin(s) do cite one)". Both keep the phrase grounding evidence, which a reader of a published manifest greps for. The code, the count and the remedy are unchanged.

The mechanism: test_binning_grounding.py: one cited bin among four reads "1 other bin(s) do cite one" and never "at all", and none cited keeps the old clause. The scenario corpus is unchanged: its scenario is the none-cited case.

Residuals none

RM414 — the repeat-count warnings reasoned about RUC/CIRUC when the module declares another source_field

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.2 — a patch (S136, just-module-creator's liaison). Owner format (binning.measurement_shape_warnings), severity low.

The class: a check keyed on a kind when the row names the thing the check is about. RM55's fractional finding and RM56's spanning finding key on measure_kind alone and name VCF 4.4's own field for it (RUC, CN) and its interval (CIRUC, CICN). source_field is the module's pointer to the field a consumer reads, and nothing read it. So a module reading ExpansionHunter's FORMAT/REPCN (a whole number) was told the field it reads is a Float, and sent to CIRUC, a field it does not use. The shipped reference_examples/htt_repeat_expansion is such a module.

Instances (both findings, both kinds): _foreign_source_fields returns the declared pointers when every row of the kind names one and no alternative of any is the spec's field (namespace stripped, |-alternation read). Then both findings name the declared field. The fractional one says the format cannot type it, states VCF 4.4's typing of its own field beside it, and holds "if can carry a fraction". The spanning one says the caller's field may come with an interval of its own. With no pointer, a row without one, or a pointer naming the spec's field, the wording is as before. This tier still holds no opinion on a caller's field types (Principle 2): it asserts nothing about REPCN, and the finding is not dropped, since a caller may write a fraction. Codes, tiling and firing conditions are unchanged, and both published fragments (FRACTIONAL_MEASURE_PHRASE, SPANNING_MEASUREMENT_PHRASE) stay in both forms.

The mechanism: schema/tests/test_vcf_measure_shape.py: the reporter's HTT bins on FORMAT/REPCN name the field, speak conditionally and never say (RUC) or "A RUC call travels with CIRUC"; no pointer, RUC, INFO/RUC and an alternation including RUC keep the spec wording; one row without a pointer keeps it; the copy-number kind scopes the same way. The HTT reference example's validate output now names FORMAT/REPCN.

Residuals none

RM417 — the live gnomAD API's constraint is v4.1.1 or later, and its rows were labelled gnomad_v2.1.1_constraint

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.2 — a patch, a corrected label declared (the pm's sizing). Owner enricher, severity medium.

Residuals none

Built (the lead, 2026-11-07), to the pm's list. gnomad.API_CONSTRAINT_DATASET_LABEL is gnomad_api_constraint; the old label is _RETIRED_API_CONSTRAINT_DATASET_LABEL, read only, in enrich_gene_metrics's done set, so a re-run over pre-RM417 API rows adds nothing and nothing rewrites them. The two warnings no longer say "serves v2.1.1"; the 0.5.0 note in gnomad.py, the pass's docstring, the gene-metrics help, @constraint-two-releases and the user docs are corrected; CHANGELOG and INTEGRATION_0_8.md § 4 declare what an old row holds. The CLAUDE.md headline for @constraint-two-releases still reads "are different releases": that file is the maintainer's to edit on a seat's request, so the line was handed to them. Tests: test_rm417_… (a fresh API row's label; a v2.1.1 row re-run is byte-identical) and the provisioning-failure warning, both failing on 21f59761.

Filed by the lead (2026-11-07) while building RM410; sized by the pm the same evening: "a patch in 0.8.2, severity medium (a consumer reading v2.1.1 applies v2-era LOEUF cutoffs to v4 numbers)", the label a route label claiming no release.

Owner enricher (gnomad.API_CONSTRAINT_DATASET_LABEL, gene_metrics.py) · related RM410, RM373, RM33

What was measured. The 0.5.0 note in gnomad.py (2026-08-01) read the live API's BRCA1 numbers (pLI 5.52e-38, LOEUF 0.928, mis_z 1.734) as "the widely-cited v2.1.1 LOEUFs" and labelled every API row gnomad_v2.1.1_constraint. gnomAD 4.1.2's bulk file gives BRCA1 exactly 5.5171e-38 / 0.92759 / 1.7336 and MYH7 6.6432e-21 / 0.66247 / 7.3787, the note's MYH7 pair; and on 2026-11-07 the live API answered DMD, a chrX gene that no release before 4.1.1 has constraint for, with pLI 1, LOEUF 0.23540 and mis_z -5.4326, 4.1.2's values to every digit (HFE and MYH7 matched too; BRCA1's call returned 502). So the API serves 4.1.1 or later (the two share their metrics; 4.1.2 changed only ranks), and the v2.1.1 label is false. The 0.5.0 reading was a recall, not a measurement: 4.1.1 had been out since 2026-03-25.

What it touches. Every gene_metrics.csv row a module took from the API fallback says v2.1.1 for 4.1.1+ numbers; dataset is in the fact set, so correcting it moves those modules' fact hashes. After RM410 the snapshot's 4.1.2 rows and the API's rows hold the same numbers under two labels, and @constraint-two-releases ("the routes must stay distinguishable") rests on the false premise. The API names no release, so the honest label is a decision: the release its numbers match today (gnomad_v4.1.2_constraint, which needs re-checking whenever gnomAD moves), or a route label that claims no release. RM410 does not depend on it.

Sized, the pm (2026-11-07): a patch in 0.8.2, severity medium. A consumer who reads v2.1.1 applies that release's LOEUF cutoffs to v4 numbers, and the two releases' recommended cutoffs differ. Nothing a reader of the schema sees moves: a constant's value, a warning's text and a test. The relabel is a corrected derivation, so Principle 3 lets it ship in any release, declared.

  • The label claims a route, not a release (gnomad_api_constraint, or the builder's spelling). The API states no release in what it returns, and it has already changed release without notice. The 0.5.0 label was a recalled release, and so would a measured 4.1.2 be: true until gnomAD next moves the API. Rejected: naming the release its numbers match today.
  • Old rows are counted, not rewritten. The pass counts gnomad_v2.1.1_constraint as its own, so a re-run adds no second row. Deleting the sidecar regenerates it under the new label. There is no automatic relabel: an old row holds whatever the API served on its fetched_at date, and no label can name that release.
  • Declared, not silent: the CHANGELOG and INTEGRATION_0_8.md's known issues say that a row labelled gnomad_v2.1.1_constraint holds the live API's numbers as of its fetched_at date, v4.x and never v2.1.1.
  • The premise goes with it: @constraint-two-releases in AGENT_NOTES, the test that pins the two routes as different releases, and the fallback warning's "serves v2.1.1" text. CLAUDE.md's headline line is the maintainer's to change; the lead hands it over.

RM416 — nine rebuild adapters ignored --pin, so a pinned build built the default and said nothing

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.2 — a patch (the maintainer: "But why is version of publication hardcoded into release?" and "do the whole thing + pinning fix into 0.8.2"). Owner enricher, severity medium.

Residuals RM412 — a probe per lane for the source's newest release, so a default can follow it

What happened. cache rebuild --pin lane=release reached every adapter in RebuildRequest.pin, and only six read it (acmg, civic, clinvar_gkm, mane, opentargets, strchive). The other nine (clinvar, constraint, clinpgx, drug_labels, cpic, pharmvar, pubmind, mitomap, mitomap_miss) built their default, so --pin constraint=4.1.2 built 4.1, and RM411's dry run printed "would build 4.1.2" for it. A flag the callee never sees (@off-switch-needs-a-probe, @flag-means-same).

What changed. caches._PINNABLE names the lanes whose adapter reads the pin, held equal to them by an AST walk; constraint joins it (RM410). A pin for any other lane is refused at the command line before the run starts (cache rebuild, cache prepare), and _rebuild_blocked refuses it as a failed lane for a host calling rebuild_lane or prepare_caches, so the dry run predicts it too. The answer to the maintainer's question is recorded with it: a default release in code is how two unattended rebuilds name the same bytes, and the pin is the override that needs no code; the defect was that most lanes had no override.

Tests. test_a_pin_is_taken_or_refused.py (with RM410's): the set equality, the CLI and Python refusals, the constraint pin choosing URL, file name and label. All eight non-parametrized tests fail on f5d7170b.

RM410 — the gnomAD constraint snapshot was pinned to 4.1, and 4.1.2 recomputes the metrics

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.2 — a patch (sized by the pm; built on the maintainer's "do the whole thing + pinning fix into 0.8.2").

Residuals RM417 — the live API's constraint is 4.1.1+ and is labelled v2.1.1, which the snapshot's 4.1.2 now makes visible

Built (the lead, 2026-11-07). constraint_build takes a release: _constraint_url and _constraint_filename (.tsv for 4.0 and 4.1, .tsv.bgz after), a reader that tells gzip by its bytes, and a label read from the file's name or the URL, gnomad_v<release>_constraint, where it was the constant gnomad_v4.1_constraint. The default is 4.1.2; the adapter takes --pin, and refuses a --source whose name states another release. gnomad.CONSTRAINT_DATASET_LABEL, the label used before a snapshot is provisioned, moves to 4.1.2. The pm's re-run guard: enrich_gene_metrics counts a row under any snapshot release label as its own, so a 4.1 module re-enriched against 4.1.2 comes back byte-identical. Built from the real file (md5 ecec6974…, the bucket's own): 19,511 genes from 221,898 transcript rows (4.1: 18,111), 127 without a MANE or canonical Ensembl row, chrX and chrY present, LOEUF moved for 17,214 of 4.1's 18,111 genes; under a megabyte, inside the lane's declared approx_mb=1.

Found while building it: RM417. 4.1.2's BRCA1 and MYH7 are the numbers the 0.5.0 note attributed to the API as "v2.1.1", and the API answers chrX's DMD with 4.1.2's values.

Filed by the lead (2026-11-07) from the liaison's data-source table and adoption note (docs/UPSTREAM_DATA_SOURCES.md, "Adoption note: gnomAD constraint 4.1 → 4.1.2"). Class and severity: the pm's to size.

Severity low · Status open — a patch, the next on main; its publish waits on the maintainer, as RM408's does · Owner enricher (constraint_build.py, the constraint lane; gene_metrics.py) · related RM229, RM408

What the note found. 4.1.1 recomputes pLI, LOEUF, o/e and the z-scores (low-coverage coding loci by AN, chrX and chrY for the first time, a revised LOFTEE END_TRUNC); 4.1.2 fixes only the rank and bin fields 4.1.1 got wrong, so 4.1.2 is the one to take. Every column _COLUMN_MAP reads is present in 4.1.2, but the file is gnomad.v4.1.2.constraint_metrics.tsv.bgz (bgzip, 574.5 MB) where 4.1 was a plain 95.5 MB TSV.

What a move carries. The URL and a gzip read; the lane's declared size (RM229) and label; every module's gene_metrics.csv drafted from the old snapshot then reads as stale against the lane, which is a content change consumers see, not a relabel; and @constraint-two-releases: which release the live API route answers must be checked before the snapshot moves past it.

Sized, the pm (2026-11-07): a patch. Nothing a reader of the schema sees moves: a URL, a gzip read, the lane's label and its declared size. Principle 3 sizes it by the schema and leaves the content to its staleness clause, so it may ship in a patch, declared in the CHANGELOG and not silently. A new release upstream is not a defect of ours, so severity is low. What it buys is chrX and chrY metrics for the first time, and gnomAD's corrected LOEUF.

  • The live-route question is already answered. The live gnomad_constraint API serves v2.1.1 (API_CONSTRAINT_DATASET_LABEL), not 4.1, so moving the snapshot to 4.1.2 crosses nothing. The two routes keep different labels, as now. Corrected, the pm (2026-11-07, the same evening): this line was false. The pm took it from @constraint-two-releases without asking the API. The lead measured that the API serves 4.1.1 or later, so its rows' gnomad_v2.1.1_constraint label is the false one. That is RM417. RM410's build did not rest on the line.
  • The build must also handle one thing the note did not name: a re-run over a module that already holds 4.1 rows. enrich_gene_metrics counts a gene as done only when its row carries one of the pass's two current labels (pass_datasets, gene_metrics.py). Once the snapshot says 4.1.2, a 4.1 row is no longer the pass's, so the gene is fetched again and a 4.1.2 row is appended beside the 4.1 one. The module then states two pLI values for one gene, and a consumer joining on gene gets both. The fix stays in patch scope: the pass counts a row from any release of the constraint snapshot lane as its own, so a default re-run adds nothing. Moving a module to 4.1.2 is then the author's choice, made by deleting the sidecar (@sidecar-authoritative). Its test: a sidecar with a 4.1 row, re-enriched against a 4.1.2 snapshot, comes back unchanged.
  • The note says modules "read as stale" against the new lane, but nothing reports that today. gnomAD has no release probe (currency.default_probes asks ClinVar, the PGS Catalog and ClinVar-GKM only). A probe is not part of this item. It is a residual, to be filed if a consumer asks to be told.
  • For the build, not a decision: the 4.1.2 file is 574.5 MB compressed, with 113 columns, some of them arrays. Select the columns _COLUMN_MAP reads while streaming the file, rather than decompressing all of it into memory.

RM413 — no gate kept a lane with a builder and no repository out of a release

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.2 — a patch, tests and the release rule (the maintainer: "Add a prerelease checks: idempotency check (on the interfaces expected to be such) and cli-parity for all these build/publish/download. This time 0.8 got a dough instead of opentargets. No hf publish thus blocks release"). Owner enricher (tests), the lead (RELEASE_CYCLE), severity medium.

Residuals RM412 — the source's newest release is still asked by hand (the liaison's table), and two lanes publish only through a rebuild

The class. A lane's three stages (build, publish, pull) were each checked to exist where declared (test_every_publishable_lane_can_actually_be_published, the unpublished reason test), and none was checked against the others or against the hub. So Open Targets shipped in 0.8.0 with a builder, an unpublished reason that named no bar ("nothing bars a snapshot, but no repository holds one"), and a registry told it was unpublished. A dry run that wrote 22 GB (RM411) was the same class from the other side: a command that promises to change nothing, never checked for it.

What was added. test_prerelease_gates.py, three gates walked off CACHE_LANES and the Typer tree: parity (a lane built here and published nowhere must open its reason with refused:, unestablished: or derived,; publish implies pull and pull implies a publisher; every publish* command has --dry-run unless it only refuses, which is pubmind publish); idempotency (cache status, cache rebuild --publish --dry-run over every lane, and each of the ten publish --dry-run commands against a minimal snapshot, each run twice with the hub faked: same disk, same output); and the published release, @pytest.mark.network, per lane with a repository, could not ask counted red. RELEASE_CYCLE § Patches makes it a cut gate for patches and minors and records the maintainer's grant that the lead uploads reference snapshots on the pm's sign-off.

Shown red. The parity rule, evaluated on the code before RM408 (9d118dd8), names exactly opentargets. The published-release gate ran live on 2026-11-07: all eleven lanes with a repository state a release.

RM411 — cache rebuild --dry-run downloaded and built every lane, skipping only the upload

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.2 — a patch (the maintainer: "dry is idempotent, thus it is not expected to change stuff, yet it downloads (and overwrites) the sources. Thus maybe 1"). Owner enricher, severity medium.

Residuals RM412 — a dry run that rehearses the download itself, opt-in, and the source's newest release asked per lane

What happened. The maintainer ran cache rebuild --only opentargets --publish --dry-run to rehearse a publish and it began mirroring 22 GB from EBI. --dry-run reached only _publish_rebuilt; the rebuild ran whole before it. The help said "With --publish: show what would be uploaded, send nothing", which was true of the upload and silent about everything before it.

What changed. A dry run now never calls an adapter. caches._rebuild_blocked is the half of rebuild_lane that decides on disk alone (no adapter, a derived lane's parents missing), so the dry run's not run is the real run's; the declared-use gate is predicted with caches._gate on CacheLane.terms, which is the object each gated adapter passes (clinpgx, cpic, drug_labels, pharmvar, pubmind; checked by grep, and pinned for CPIC by a test comparing the two runs' line). The published release is read from the repo-root release.json alone, three-valued. The upload's checks (allowlist, orphaned sidecar) are rehearsed only against a snapshot already in <out>/<lane>, since they need the bytes; that keeps the two rebuild-route lanes with no publish command of their own (opentargets, clinvar_gkm) rehearsable: build, then dry-run.

Considered and left. A new --headers-only flag was the maintainer's first wording; a new flag is minor scope on main, and making --dry-run dry changes behaviour only where it was a bug. The opt-in inverse, --rehearse-download, is RM412 in 0.9.

Tests. test_a_dry_run_rebuild_takes_nothing.py: the opentargets dry run with every outside host fenced leaves <out> absent; nothing published and could not ask print differently; a built snapshot is rehearsed and its tree's mtimes are unchanged; CPIC's gated line is the same in both runs. The first three fail on the previous main (931215fb).

RM408 — the Open Targets lane had a builder and no repository, so every deployment cut its own ~5.5 GB snapshot from ~22 GB

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.2 — a patch (the maintainer: "Fix the code then, unless unspecified public dest is some kind of decision I missed"). Owner enricher, severity medium.

Residuals none

What happened. The registry's server reported opentargets and clinvar_gkm unpublished. clinvar_gkm has a repository and a rebuild adapter, so cache rebuild --only clinvar_gkm --publish publishes it and only the publish itself was missing. opentargets had neither a repository nor a pull route: CacheLane.publish_repo was None, and unpublished said "the release is marked CC0, so nothing bars a snapshot, but no repository holds one". Nothing in RM333's record, the 0.8 scope or the proposals decided to keep it unpublished; the OPENTARGETS_SUBDIR comment named the missing repository and the missing ensure as the gap.

What changed. locations.SNAPSHOT_REPO_IDS["opentargets"] = "just-dna-seq/opentargets", which derives the lane's pull prefix; download.SNAPSHOT_FILE_GLOBS["opentargets"] = "*.parquet" (six tables, four in numbered parts, so the glob is the whole data/, as CIViC's is); a private download._ensure_opentargets_snapshot on _provision_snapshot; and the lane's publish_repo and ensure set, unpublished dropped. The lane keeps its rebuild adapter as its one publish route, which test_every_publishable_lane_can_actually_be_published requires.

Why private. A new public function is minor scope on main (RELEASE_CYCLE), and nothing outside CACHE_LANES needs to call it: cache pull and cache prepare reach it through the lane. A standalone opentargets publish <dir> for an already-built snapshot was left out for the same reason (a new CLI command), so publishing means a rebuild, which also stamps the current builder version into release.json (the shared cache's says 0.7.3).

The cost a deployment sees. cache pull with no --only now pulls this lane too, ~5.5 GB, once the repo holds a snapshot. Until then cache prepare reports nothing published yet for it rather than building it, as for clinvar_gkm, so this should be cut only after the first publish.

Tests. test_download.py::test_cache_pull_reaches_the_opentargets_lane_and_brings_every_table pulls a fake repo holding all six tables through cache pull --only opentargets and asserts the prefix it asked and the file set it landed; on the previous main it fails (nothing is asked). The lane-registry walks (test_cache_lanes.py, test_snapshot_repo_ids.py) pass unchanged. A read-only rehearsal against the shared cache lists 428 parquet files and release.json for just-dna-seq/opentargets.

RM398 — placement_agreement had no witness at dbSNP scale, and its third witness cost a cold REST request per indel

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.1 — a patch, candidate 0 (S132, just-dna-registry's lead; the maintainer's ask). Owner enricher, severity medium.

The class: a record the run already holds, read for one field and discarded for the one a check needed (@dont-discard-computed). The rsID merge check fetches esummary db=snp for every rsID an online run carries and kept only live, merged or absent. The same record carries dbSNP's GRCh38 SPDI, the placement the third placement witness was buying from live Ensembl REST one cold request per indel (S133).

Instances (the witness, the run's order, the roster):

  • placement._dbsnp_placements reads the record's spdi (comma-separated, accession:position:deleted: inserted, 0-based): an accession off the GRCh38 primary assembly is no locus, a two-sided allele sits at position + 1, a one-sided one is anchored on the base at position (anchor_indel, REST's interbase convention), each ALT is handed on alone (per_alt_loci). A missing record is the answered-empty []; an indel with no readable anchor base is not asked (RM268's rule). A merged id's record is the current id's, served under the asked uid, and is compared as the asked rsID.
  • The witness reads before the merge check, through _RecordedEutils, an EutilsClient that remembers each uid it fetched; the merge check is handed the same client (check_rsids(asked, client=…)) and asks only what the witness did not. So the run asks dbSNP nothing it did not ask before, and asks REST nothing as a witness. Same subjects as REST had (live_witness_subjects: snapshot indels no loaded witness holds), the same gate as the merge check (verify_rsids and not offline). The merge check off leaves every subject counted as not asked, with that reason.
  • The witness is dbsnp, its own authority, so the licence join stays true (@source-vs-authority), with a public-domain terms entry (_DBSNP_TERMS). Independence keeps REST's reading: _UPSTREAM_OF names the authorities a witness is upstream of, and dbSNP's agreement with an Ensembl placement is self-consistent, not independent, since the snapshot is built from dbSNP 157. The record names no dbSNP build, so its release is withheld. ENSEMBL_WITNESS stays in the roster (a recorded row may name it); RestWitness, ask_live_witness and REST_RETIRED_REASON stay as 0.8.0 shipped them; nothing asks them. No public name is added.

The measurement the pm asked for, bounded (2026-11-07). Over the 169 snapshot indels of the reference examples (5 modules, the 0.8 split snapshot), each witness compared with the snapshot by compare_placements: dbSNP and REST disagreed with the snapshot on none, so no locus is withheld differently. Verdicts were identical on 157; on 11 dbSNP confirmed alleles REST left unplaced; on 1 (rs1569493663, a PAR insertion) dbSNP's record places the Y copy only, so the X copy reads unplaced. S117's rs8176719 is still caught (live, unmocked: dbSNP's SPDI anchors to ClinVar's 9:133257521 T>TC).

The mechanism: test_placement_witness.py's REST-witness tests became dbSNP-witness tests over recorded esummary records behind the run's patched client: S117 withheld with dbsnp as the witness and the merge check asking no uid twice, an agreed indel written dbsnp/same_event and counted self-consistent with its licence row, an outage counted not asked with its reason, the merge check off counted not asked, a resolver with resolve_rsid alone needing nothing, offline asking nothing, the witness's release withheld, and a run using REST as a link asking it nothing as a witness. A network test reads the live record for S117.

Residuals RM406 — dbSNP witnesses only REST's old subjects, and the count over the registry's 46-module replay, which RM406 waits on, is the registry's re-measure; this build measured the reference examples only · won't fix — an offline dbSNP witness (a snapshot lane, the entry's candidate 1) is not needed while the merge check's record is online-only and free · won't fix — the snapshot keeping VEP's SPDI field belongs to prepare-annotations, the snapshot builder outside this repository

RM407 — minting an indel's VRS id reads the reference a slice at a time over HTTP, about a dozen reads per indel

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.1 — a patch (the maintainer, reading the registry's replay log). Owner enricher, severity low.

Residuals RM404 · RM385

The class: a read per step where one read per locus serves every step. vrs-python's normalize wraps the data proxy it is given in its own SequenceProxy, and every slice it takes while trimming and rolling through a repeat is one get_sequence, one HTTP GET of seqrepo; the proxy's own lru_cache hits only an identical (start, end), which each step does not ask. The registry's replay (46 modules, enricher 0.8.0) made 2,472 sequence reads, about 354 s, roughly ten per indel. Our sequences.SequenceProxy already read one window and memoized it for _left_align (RM273); the VRS path did not go through it.

What changed. VrsMinter._mint_normalized hands normalize a private _WindowedReference: 1,024 bases on each side of the locus, clipped at the contig's ends, read once through the run's SequenceProxy. A slice inside the window comes from memory; any other read goes to the proxy unchanged, so an id never changes, only how often seqrepo is asked. Each sequence's metadata is read once per run, and the run's one minter keeps the ids it normalized, so the placement comparison (RM267) and the minting pass never normalize an allele twice. No public name, no field, no warning code.

Test. enricher/tests/test_vrs_window_reads.py, over a synthetic reference on chromosome 1's real refget accession with a homopolymer, a dinucleotide and an 8-base repeat: six indels (insertions and deletions in each repeat, one in unique sequence) mint the ids the raw proxy mints, with one read each, where the raw path took 65 reads; an allele minted twice is read once; a locus at either contig end mints what the proxy would. Run against the code before the change, the read counts went red (65 and 46) and the ids held.

What is left. The request under the proxy has no timeout; that is vrs-python's (requests.get in its seqrepo REST proxy), and RM404 names it. A local reference, which removes the HTTP reads altogether, is RM385.

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.1 — a patch, after its probe (S133, just-dna-registry's lead). Owner enricher, severity medium.

The class: a per-item loop against an API that takes a batch. Both REST callers, the live link and RM267's placement witness, sent one GET per rsID. The registry measured one module (178 rsIDs) at 11 s offline and 672 s online, 599 s of it on 59 GETs. A cold GET takes seconds and an abandoned one warms nothing, and POST /variation/:species takes up to 200 ids.

The probe came first (2026-11-07), because the omission's meaning was the fix's own risk. By hand against rest.ensembl.org: a batch of rs1801133, an impossible rsID, a malformed id and two real ones answered 200 with the three real ones only, and no failure field; a batch of only unknown ids answered 200 {} (58 s); the merged rs8192284 came back keyed rs2228145, the asked id only in synonyms, while its GET answers 200 with that record and the impossible id's GET answers 400; /variation/human works as /variation/homo_sapiens does. Timings that day: batches of 10 cold ids 13 to 32 s (the registry measured 13.9 s), cold single GETs 20 to 58 s with one 503, so the client's 15 s read timeout would have abandoned most batches.

Instances (the resolver, two callers):

  • EnsemblResolver._resolve_rsids_rest (and _resolve_rsids, its resolve_rsid twin) yields (rsid, answer) per rsID in asked order, _REST_BATCH_SIZE (20, capped at _REST_BATCH_CEILING 200) per POST, each POST through _rest_batch under the GET's own retry policy and with _REST_BATCH_TIMEOUT (120 s) as its read timeout. _batch_records matches an asked rsID by name, then by the one record whose synonyms list it; none or two, and the rsID is asked by GET. The asked rsID stays the key (@ncbi-merge-oracle). A failed batch, a POST 400 included, is (None, None) for every rsID in it, with no GET fallback. The per-rsID rules (RM268's anchor, RM271, RM400) moved into one _rest_answer both routes call, and the throttle hold into _held / _hold_for.
  • The next batch is asked only once every answer of the one before is taken, so the live link still journals each answer before the next request: a kill loses at most one batch.
  • The live link and the witness batch only through the private _BatchResolver / _RestBatchWitness Protocols, so only EnsemblResolver batches and an injected resolver is asked one rsID at a time. placement.ask_live_witness keeps 0.8.0's signature (one rsID per call) and the run asks through the private _ask_live_witness, which takes a many-rsID callable.
  • No public name is added, by the pm's ruling (2026-11-07). As first landed (6837e66a) the item added two EnsemblSettings fields, two resolver methods and two Protocols, and changed ask_live_witness's signature. RELEASE_CYCLE.md keeps a new public name off main, so every one went private and the signature went back; 0.9 publishes the knobs and the capability with RM404.

The mechanism: enricher/tests/test_ensembl_rest_batch.py answers in the probe's shapes. It asserts a batch answers each rsID exactly as the off-switch's GETs do (one POST plus one GET for the left-out rsID, against one GET per rsID), the order and key, the RM271 collection, the ambiguous-synonym fallback, could-not-ask on a failed POST (503, 400, 429) and on a timeout, the cut and the ceiling (by patching the private constant), the lazy next batch, the throttle hold, the POST's own timeout, and end to end that the live link sends one POST for its misses while a host resolver without the capability is asked one at a time. Reading an omission as "no record" fails three of them; one is an rsID the batch leaves out that its GET places. The tests that mocked REST by GET alone answer the POST too: the witness's _Rest natively, three others through the conftest's rest_batch, which answers what a GET answers 200 for and leaves out the rest, so each per-id failure still reaches the resolver through the GET.

Residuals RM404 — a host cannot tune the batch: 20 ids and 120 s were chosen on one slow day (2026-11-07) and are fixed private constants in the 0.8 patch line; RM404 makes them settings and the capability public in 0.9. RM402 waits on this item and the registry's re-measure, which says whether the fixed numbers hold.

RM400 — the REST rung wrote placements on GRCh38 patch and alt contigs, which no snapshot carries, so a re-derivation reported a lost allele that did not move

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.1 — a patch, both halves (S132, just-dna-registry's lead). Owner enricher, severity low.

The class: one link keeps what every other reader of the tier drops. _loci_from_rest kept any mapping whose assembly_name is GRCh38 and never looked at seq_region_name, so a substitution REST mapped onto a patch or alt contig was written as a locus (an indel there was already withheld, since its anchor base has no refget accession). No Ensembl snapshot carries such a contig, a primary-assembly VCF never joins one, and gene_spans, pharmvar and the ClinVar-GKM build drop them. So which link answered decided an rsID's loci. The registry met it as 11 lost_allele subjects in 4 modules: 0.7 tables REST had answered, re-derived from the 0.8 snapshot, whose primary placement had not moved. Its gate holds lost_allele, so those 4 modules were refused.

Instances (two halves):

  • The write half. _loci_from_rest drops a mapping whose contig is not in contig_length's GRCh38 primary table, before any anchor read, and returns the count as a fourth value. resolve_rsid_rest logs it (WARNING when no primary mapping is left, and the rsID is the answered-empty [], as the snapshot answers it; INFO otherwise).
  • The design half, the pm's default taken as is. The fix alone would not clear the registry's 4 modules, since their tables already hold the patch loci. _rederived_drift reads the recorded side through _primary_rows: a locus on a patch or alt contig of a tabled build is left out, the survivors are renumbered in their recorded order (locus_index is a fact field, and HSCHRX_… sorts before X), and the third return value counts what was left out per variant_key. The orchestration logs one WARNING with the count, the subjects and the denominator, since the committed table is that many rows shorter. A subject with nothing on the primary assembly is compared whole, as before. Neither a new drift arm nor a carry reason was added, so RM394's vocabulary is unchanged.

The mechanism: test_ensembl_non_nucleotide.py asserts the patch, alt and unplaced mappings are dropped and counted with no anchor read, every primary contig kept, and an off-primary-only rsID answered [] with its line. The test there that pinned a patch-contig locus as kept now uses a primary one. test_rederive_off_primary.py asserts the comparison on its own (the left-out count, the renumbering, a real move still reported, the off-primary-only subject compared whole, another build untouched) and end to end: an offline --rederive over a table holding a patch row beside the primary one reports no drift, one RM400 line, and commits the primary row only. Without the recorded-side filter that test reproduces the registry's lost_allele.

Residuals none

RM403 — a retried request left no log line, and a give-up said neither how many attempts nor how long

SHIPPED 2026-11-07 on main, cut 2026-11-07 as v0.8.1 — a patch (S133, just-dna-registry's lead). Owner enricher, severity low.

The class: a retry that is silent until it gives up, and a give-up that cannot say what it gave up on. No tenacity policy in the enricher set before_sleep, and httpx logs responses only, so an attempt that timed out wrote nothing. The registry's sweep met 26 ReadTimeouts at 15.2 s and five rsIDs that spent all three attempts, about 48 s each, and the only line was the caller's give-up warning naming the error. An operator could not tell attempts timing out from a slow server, and RM402's re-measure needs to.

Instances (every policy, 21 at the fix): each @retry in the package now names two shared hooks in net. _log_retry (before_sleep) writes Client.method(subject): attempt n of m failed (Type: message); retrying in w s. _log_give_up (retry_error_callback) writes …: gave up after n attempt(s) over s s (Type: message), then raises exactly as tenacity would have, read off the policy: reraise=True re-raises the attempt's own exception, so every caller's except still sees what it was written against (@client-exception-contract), and a policy without it raises RetryError from it. Tenacity calls the callback only once the stop fires, so an error the policy does not retry (a 400, a 404) writes neither line. The ceiling m is read the way attempt_floor reads it, so a raised $JUST_DNA_HTTP_RETRY_ATTEMPTS shows. The type is always named, since a bare ReadTimeout stringifies to nothing. Both lines are at WARNING: nothing in these tiers configures logging, and Python's last-resort handler drops anything lower.

The hooks are private (_log_retry, _log_give_up): first landed public (4a07f4ec), renamed by the pm's ruling of 2026-11-07, since RELEASE_CYCLE.md keeps a new public name off main.

The mechanism: enricher/tests/test_retry_logging.py walks the package's source and refuses any retry(, Retrying( or AsyncRetrying( that names neither hook; dropping one keyword from one site makes it name that site. Its behaviour half runs the real REST route (EnsemblResolver._rest_rsid) against a transport that times out every time and asserts the two retry lines, the give-up line, and that the caller still withholds ((None, None)), plus the raised-floor ceiling, the RetryError path and the not-retried path. The rule is in ENRICHER.md's rate-limit rules.

Residuals none

RM397 — the enricher wheel shipped its Atlas build input beside the generated tree

SHIPPED 2026-11-05 on main, cut 2026-11-07 as v0.8.1 — a patch (found by the lead while scripting the dist build). Owner enricher, packaging, severity low.

The class: a build tree that is input to a later step was shipped beside that step's output. The build hook passed two trees to hatchling as artifacts: _atlas_protos/, the fetched pinned sources, and generated/, which atlas_protos.generate writes from them (the bindings, a staged copy of each .proto with its imports rewritten, the service config and upstream's Apache-2.0 notice). The wheel needs only generated/, so 0.8.0's wheel carried the service config, the notice and tensor.proto byte for byte twice, and atlas_service.proto/dna_model.proto twice in two spellings (about 50 KB). The sdist does need the sources: a build from it then needs no network.

Instances (one): enricher/hatch_build.py (AtlasProtoHook.initialize): both trees for every target → generated/ for every target, _atlas_protos/ for the sdist only. enricher/pyproject.toml [tool.hatch.build.targets.wheel] gains exclude = ["src/just_dna_enricher/_atlas_protos"], because a wheel built from an unpacked sdist (what uv build does) has no .gitignore to hide the tree. The format and compiler wheels build with uv_build from tracked files only, and carry no build input.

The mechanism: scripts/build-dists.sh now refuses (exit 3) any wheel holding the same bytes under two names, beside its non-.py share alarm; reverting the hook fix makes it list the three identical pairs. enricher/tests/test_wheel_contents.py builds the wheel and sdist through the real backend and asserts the wheel has no source tree, has every file the runtime reads, and that the sdist has every fetched source; reverting the fix fails its first test. A clean venv with the fixed wheel plus [atlas] imports atlas_client and the bindings, and client_absence() is None.

Residuals won't fix — two remainders, both by design: the wheel test is network-marked (a fresh checkout fetches the sources and resolves the build backend), so the default suite and CI skip it; build-dists.sh at each cut is the always-on half. The staged .proto copies inside generated/ still ship; they differ from the sources by their import lines and are kept as the readable form of what the bindings were generated from.

The 0.8 PT2 build round

The schema round PROPOSAL_0_8_PT2.md decided on 2026-11-04, built on the 0.8 branch lane by lane. Newest first.

RM395 — commands the user guides run fail or misreport

✅ SHIPPED 2026-11-05 on 0.8, uncut — a minor (the 0.8 docs pass). Owner compiler + enricher, docs, severity low. related RM202, RM176

Residuals none

The class. A guide command whose behaviour the guide states and the code does not do. The 0.8 docs pass re-ran every command in the four user guides and found three, each there since 0.7.3. The guard is that the guides' commands are re-runnable: the docs pass re-runs them before a cut (RELEASE_CYCLE.md), and each instance below has a test that went red first.

Instances, before → after. All three fixed in code, each well inside the pm's thirty minutes, so no guide was rewritten to work around one.

  • D1, just-dna-compiler keygen --out ./keys/private.pem (COMPILING.md) raised a FileNotFoundError traceback when ./keys did not exist, where compile and reverse create their missing parents. keygen now creates the parent after the overwrite refusal. test_keygen_creates_a_missing_parent_directory_as_compile_and_reverse_do.
  • D2, just-dna-enricher draft-repeats ./my_module --gene FMR1 (ENRICHING.md) skipped with No STRchive catalogue was provisioned on a machine holding the lane, though its --help says the lane is read and check-repeat-bands read it. draft_repeat_loci now resolves the lane with resolve_strchive_reference, as check_repeat_bands does, before the nobody-asked skip. test_draft_repeats_reads_the_provisioned_strchive_lane_as_check_repeat_bands_does, through the CLI.
  • D3, cache status and cache pull --only clinvar_gkm (ENRICHING.md) described the lane registry, not the disk. cache pull closed with caches available: and every lane with a pull route, so a run that found nothing published for clinvar_gkm named it available; it now names what the run left on disk and which lanes had nothing published. A parquet lane's pull that found nothing left an empty data/, which the next cache status called occupied and cache prepare refused to build over; it is now made only once there is something to put in it. A root-file lane (STRchive) left an empty directory, harmless to both checks, and now removes the one it made. cache status said provision with cache pull for a lane whose repository is empty; it reads only and cannot see publication, so a lane with a pull route and a builder names both. test_cache_pull_names_only_what_is_on_disk_as_available, test_an_absent_lanes_line_names_every_route_that_can_provision_it.

Found while building, outside the three and reported to the lead for a number: a builder named on a status line writes to its own --out default (data/repro/<lane>), never the place the lane is read from, so provision with clinvar-gkm build (and every build-only lane's line, as before this item) leaves the lane absent unless the operator passes --out.

RM394 — the re-derivation's report had fewer arms than the cases it describes, so its words named what had not happened

✅ SHIPPED 2026-11-05 on 0.8, uncut — a minor (the 0.8 audit, round 3), a cut blocker (audit 3 and the docs pass, D4, D5 and class 4's carry instance). Owner enricher (enrich/outcome.py, enrich/orchestration.py, events.py, currency.py), severity medium. related RM375, RM373, RM382, RM393

Residuals none

The class. A report with fewer arms than the cases it reports (@answered-is-not-absent: a verdict with several arms owes a reason with the same arms, pairwise distinct), on the enrich --rederive migration step 0.8 tells every consumer to run. Each sentence was true of one case and printed for all of them, so a migrating operator read a cause that had not happened and a remedy that did not apply.

The instances, on 64c835b9.

  • D5, enrich/outcome.py:57–64 (SubjectDrift.__str__, three arms) and :79–95 (_same_events, any rsID difference → False): an allele the source added (A → A,T, or a row that had no ALT) and an rsID newly named both printed "moved: the source names a different event". Measured by the examples' 0.8 regeneration: 94 subjects gained an allele, 10 gained an rsID. → seven arms, rederive_words.DRIFT_CASES: respelled, gained_allele, lost_allele, gained_rsid, renamed, moved, undecided, carried as SubjectDrift.case; the drift warning counts by arm. Re-measured on the pre-regeneration apoe_klvs_meta and hfe_compound_het against the split snapshot (offline): all four drifts now read "gained an allele", none "moved".
  • D4, enrich/orchestration.py:2087–2092: the derived-layer currency line always said "Re-derive with enrich --rederive". When the release that is behind is the local snapshot, a re-derivation reads it and prints the same line. → one line per rederive_words.CURRENCY_CASES member, read against the label of the snapshot the run read (clinvar, clinvar_gkm): table_behind_snapshot → --rederive; snapshot_behind → cache pull --only <lane> (or cache rebuild) first; both_behind (the snapshot is neither release) → both; snapshot_unread (none read, or a label in the other form) → cache status, naming no lane. One line per case and source, so two lanes behind are two pulls (the code review). test_source_release.py::test_a_source_publishing_past_the_snapshot_never_makes_strict_refuse had pinned the wrong remedy for the snapshot_behind case; it now asserts the pull.
  • Class 4's carry instance, enrich/orchestration.py:1595–1602: "kept the recorded rows for N subject(s) no source could be asked about" was said about subjects a link answered and the hosting filter rejected (RM382's carry) and about ones whose request failed. → each branch that writes no row declares why (no_row_reason), and the warning groups the carried subjects by rederive_words.CARRY_REASONS: not_asked, off_build, no_reverse_map (RM393's subjects), unreachable, rejected, and not_re_answered, the default for a subject no branch declared, which claims no reason.

The hunt over the other sentences the --rederive path prints found each true of every case it is printed for: releases.run_label's "enrich --rederive re-answers them" (rows another release answered, which this run's snapshot does re-answer), the drafted-layer currency line, the undecided-drift line, and unchecked_sentences (one per skip reason already). Two neighbours stay out by the pm's sizing: the S85 "recorded as unresolved" warning, and net.py's "upgrade just-dna-enricher" for a hand-picked release, both parked by the pm on 2026-11-05 without a number (the audit findings list in main's ROADMAP.md).

The mechanism. One module, enrich/rederive_words.py, holds each report as a closed vocabulary (frozenset, P6) and a map from case to sentence, with the decision beside it (drift_case, currency_case); the run and SubjectDrift read nothing else. The drift reads the event judge in each direction through events.covers (same_allele_sets is now the two directions combined, unchanged in answer), so a gain is decided by the one judge and an unmatched indel stays undecided. SubjectDrift.respelled is read off the arm and keeps its meaning exactly: an rsID or build change whose events are not the same is moved, as before.

The guard, enricher/tests/test_the_rederive_report_names_each_case.py: for each of the three registries, the map's keys equal the cases and the sentences are pairwise distinct (no one contained in another); every drift arm is what _drift_case answers for a real pair of rows; every currency case is reached by its labels, and each sentence names its remedy and not the other's (only table_behind_snapshot lacks the pull); every carry reason names its remedy, an AST walk over the run asserts the reasons the branches write equal the registry less not_re_answered, which is only the default, and the hfe run with no snapshot prints the not_asked and no_reverse_map groups apart. test_source_release.py adds the end-to-end other side: a table behind its snapshot is sent to --rederive, and after one the line is gone. test_authored_event.py's judge registry now names _drift_case and covers. Mutated once each: the gained arm returned as moved (two tests red), the currency decision sending every non-recorded snapshot to --rederive (both_behind red), the positional carry declared not_asked (the AST walk and the hfe run red).

RM393 — a re-derivation that read no position→rsID map erased a back-filled rsID, and the artifact shipped it null

✅ SHIPPED 2026-11-05 on 0.8, uncut — a minor (the 0.8 audit, round 3), class 1, a cut blocker. Owner enricher (enrich/orchestration.py), severity high. related RM98, RM382, RM375, RM394

Residuals won't fix — a snapshot that was read but lacks the subject's chromosome (Not fixed below): no real snapshot is built that way, so it waits for a run that meets it. The same run's report called the erased rsID "moved: the source names a different event", which is RM394's.

The class. Nobody-asked read as an answer (@unreachable-not-absent), on the one path --rederive re-opens: a re-derivation replaces only what was answered, and could-not-ask keeps its rows (@rederive-never-shortens). A positional subject's rsID is back-filled from a position→rsID map, and only the two snapshot links fill one (rev_candidates, from the Ensembl snapshot and the ClinVar snapshot); no live link answers a position. With neither snapshot read, an empty candidate list meant nobody asked, and the branch wrote rsid=None, source=authored all the same. fresh_keys then counted the subject answered, so the carry-forward never put the recorded row back.

The instance, on 64c835b9. enrich/orchestration.py:1512–1513 (the positional branch): no candidates → rsid=None, status=resolved, source=authored, whatever the run read → under --rederive, with no map read and a recorded row for the subject, no fresh row; the carry-forward restores the recorded one. The only instance: every other branch that cannot ask already writes nothing (RM98, S20, RM382), and a first enrich keeps the authored row, since with nothing recorded the coordinate is the whole identity. Measured by the audit on a copy of hfe_hemochromatosis with every cache empty: both ga4gh:VA.* rows lost rs773443949, source and source_release, and the recompiled weights.parquet and annotations.parquet carried rsid=null. Since 0.7 (main:enrich.py:1546); the 0.8 migration step, --rederive after a 14.5 GB pull that may fail, is the realistic way in.

The mechanism. reverse_maps_read, the set of position→rsID maps this run read, by the link name a back-filled row records in source (cache for the Ensembl snapshot, clinvar), filled where each snapshot's position lookup returns. Narrower than rsid_links_consulted on purpose: that one is true for any run allowed to go live, which back-fills nothing. Under --rederive, a positional subject with no candidate whose recorded rsID came from a map not in the set writes no row, and the carry-forward keeps it. Per link rather than per run: the pm sized the item narrow with a run-level predicate, and the code review found the realistic way in is per link, a failed 14.5 GB Ensembl pull beside a 300 MB ClinVar snapshot that pulled, where ClinVar's map is read and has nothing at an Ensembl back-fill's allele.

The guard, enricher/tests/test_a_rederive_with_no_reverse_map_keeps_the_backfill.py, on the example itself under no_ambient_caches (an empty base): rederived with no snapshot, the positional rows keep rsid, source, authority, status, source_release and rsid_alternates, nothing is reported as drift, and the module compiles to the same artifact.digest as the untouched copy, with no null rsID in weights.parquet. Shown red before the change (the row came back rsid='', source=authored). Its second test is the other half: with an Ensembl snapshot that holds chromosome 6 but not the locus, the map was read and said nothing is there, so the rows go out authored and the drift names them. Its third is the per-link case: a ClinVar snapshot read with nothing at the allele, and the Ensembl back-fill kept. Mutated: with the Ensembl link not marking its map read, the second test went red; with the predicate per run, the third did.

Not fixed. A snapshot that was read but lacks the subject's chromosome (a hand-built or partial one) answers "no rsID here" for every subject on it. Telling "the chromosome has no rsID at the allele" from "the map holds no such chromosome" needs the snapshot's coverage, which locations.manifest_coverage reads for the split release; it waits for a run that meets it.

RM384 — the Ensembl lane's repository has no public name on 0.8, and every pulled lane spells its repository twice

✅ SHIPPED 2026-11-05 on 0.8, uncut — a minor (S130, the tail of RM372). Owner enricher (download.py, upload.py), severity low. related RM372, RM278, RM202

Residuals none

The class. A registry fact restated beside the place it is defined, with nothing asserting the two agree (@registry-completeness, derive, never restate). Here the fact is which HuggingFace repository a lane lives in: written as a repo id in upload.py, again inside an fsspec prefix in download.py, and a third time as CacheLane.publish_repo, which happened to read the first. RM372 renamed the Ensembl repository by hand, which is the edit a pair lets go wrong; and the Ensembl lane, pulled and never published here, had only the private prefix, so a consumer pinning ManifestCompilation.ensembl_reference (org/repo@<rev>) spelled the string or stripped datasets/ and /data off download._ENSEMBL_HF_PREFIX (S130, the registry's 0.8 adoption).

The instances, on 5b1b73b8.

  • download.py:64–66, 90–91, 101–102, 110, 118, 124 — ten _*_HF_PREFIX = "datasets/just-dna-seq/<repo>/data" literals → removed; each ensure_* reads SNAPSHOT_REPO_PREFIXES["<lane>"], as it already read SNAPSHOT_FILE_GLOBS["<lane>"].
  • download.py:161–172 — SNAPSHOT_REPO_PREFIXES, a hand-kept dict of those ten → a comprehension over SNAPSHOT_FILE_GLOBS, datasets/<repo id>/<SNAPSHOT_DATA_DIRNAME> (the format tier's name for data, no longer a third literal).
  • download.py:129 — _STRCHIVE_HF_REPO = "datasets/just-dna-seq/strchive" → derived as datasets/<repo id>; STRchive's payload sits at the repo root, so it has a repo id and no prefix.
  • upload.py:114–152 — ten DEFAULT_*_REPO_ID literals → working aliases (P3) of the map's entries.
  • cli/clinvar_commands.py:79, cli/civic_commands.py:284, cli/gene_reference_commands.py:85, cli/module_commands.py:84 — --repo help text writing Default: just-dna-seq/<repo>. by hand → an f-string over the alias, as cli/alphagenome_commands.py:458 already did. Found by the walk, not by the entry. The fourth is the module repo (DEFAULT_REPO_ID), not a lane's, and is the same restatement.
  • upload.py:219 — LayoutShift.repo_id's comment said a lane→repo map "would be a second copy of CacheLane.publish_repo" and could not live there → points at the map.

caches.py and locations.py spell no repository: every publish_repo reads an alias, and the pull record's repo is the derived prefix, byte-identical to before, so no cache on any machine reads as pulled from elsewhere.

The mechanism. One public map, locations.SNAPSHOT_REPO_IDS (lane → org/repo, eleven entries: every lane in CACHE_LANES with an ensure), the only place a repo id is written. In locations.py, not beside SNAPSHOT_REPO_PREFIXES in download.py where S130 asked for it: the publisher reads it too, and locations is the leaf both import, while upload importing download loaded the resolver, duckdb and httpx (about 330 ms measured) to name a repo. The module repo just-dna-seq/annotators stays the one other literal, DEFAULT_REPO_ID.

The guard, enricher/tests/test_snapshot_repo_ids.py, equalities over the walked map with the expected side spelled in the test: the map's keys equal the pulled lanes; the prefix map's keys equal the map's minus the root-payload lane (STRchive, named with its reason) and each prefix equals f"datasets/{id}/data"; STRchive's root equals f"datasets/{id}"; every non-None publish_repo equals its lane's entry; each DEFAULT_<LANE>_REPO_ID equals its own lane's entry (per alias, since a subset check passes DEFAULT_DRUG_LABELS_REPO_ID = SNAPSHOT_REPO_IDS["clinpgx"]). And an AST walk over the three source trees refuses the organisation just-dna-seq/ inside any string literal but a docstring, the map's own assignment and DEFAULT_REPO_ID's, so a repo composed from pieces is refused as well as a whole one. Shown red before the change (7 of 7, no map); mutated once each after it: a literal DEFAULT_CPIC_REPO_ID failed the walk (upload.py:126 spells just-dna-seq/cpic); the CPIC lane's publish_repo pointed at the ClinPGx alias failed the publish-repo equality; the drug-labels alias pointed at ClinPGx's entry failed the alias equality; "just-dna-seq/" + "cpic" added to download.py failed the walk. test_ensembl_split_release.py::test_every_provisioned_lane_states_its_repo (prefix keys equal the globs' keys) is removed: the prefixes are now a comprehension over the globs, so it could not fail (@tautology-zero); the new test's key equality replaces it.

Observed, not fixed (outside the item). download.pulled_from_elsewhere keys on SNAPSHOT_REPO_PREFIXES, which STRchive is not in, so a STRchive cache pulled from a renamed repo would never be re-pulled. STRchive's root-file provisioner writes no pull record, so there is nothing to compare yet; it matters only if that repo ever moves.

The reporter's other question. A reproducibility pin wants the repository and a revision, the shape ensembl_reference documents; the release label (locations.ensembl_release_label) names which data, not which bytes. Recording both is a separate question this item did not open.

RM389 — a "reproduced, so withhold" comparison over a hand-kept subset of the columns its own registry says are rebuilt

✅ SHIPPED 2026-11-05 on 0.8, uncut — a minor (the 0.8 audit, round 2), class 4. Owner compiler, severity medium (a P7 loss, introduced in 0.8 by RM364 and widened by RM380).

Residuals none

The class. A predicate that decides a stored value is "reproduced" by something else, and withholds it, while comparing a hand-kept subset of the columns a registry beside it names as reproduced. A column the registry lists and the comparison leaves out is neither compared nor kept, so a value only that column holds is withheld and lost.

The instance. parquets.withhold_reproduced_loci nulls a key's resolution_loci wherever the row's own cells rebuild the table's rows exactly, and reverse then writes the table back from those cells. _CELL_REBUILT names the carried columns the cell rebuild writes, vrs_id/vrs_spec among them, and _locus_holds_more_than_cells keeps a locus holding any other carried column (RM380). The comparison over the rebuilt columns was _locus_fact, a hand-kept tuple of six (rsid, chrom, start, ref, alts, locus_index). A locus stating vrs_spec=2.0 with no id, legal because ResolutionRow does not pair the two, matched on its coordinate and was withheld, and reverse wrote vrs_spec empty, since the cell lookup (VrsIds) copies a version only beside an id. The same held for an id on a table row with no ref, which the lookup skips. Re-verified on 5b1b73b8: with provenance stripped so the withhold is reachable, every one of the 16 reference examples carrying a resolution.csv lost the vrs_spec of every withheld key (2 to 328 keys each), and hfe_hemochromatosis with ref blanked lost the id of all 10 keys it records one for. An enriched table carries provenance, so its loci were kept anyway; the loss needed a hand-filled, reversed-from-old or deprecated-path table.

Every instance hunted (compiler, enricher, format):

  • compiler/.../parquets.py:481 _locus_fact(rsid, chrom, start, ref, alts, locus_index) → cell_fact(cells) (:497) over CELL_FACT_FIELDS (:446), which is _CELL_REBUILT in the carried order. The comparison (:544) and both callers read through it: the weights builder from the record it just built (:236, so the cell vrs_id list and vrs_spec are the parquet's), the positional builder by row.get over the same columns with locus_index 0 (:566), which is how reverse's _resolution_record reads them. cell_fact indexes rather than .gets, so a caller missing a rebuilt column fails instead of comparing it as empty.
  • Checked, not an instance: reverse.py:879 dedupes the weights cell rebuild on (key, rsid, chrom, start, ref, alts). vrs_id/vrs_spec were looked up by exactly that key, coordinate and allele set, so two rows equal there hold the same pair, and locus_index is left out so one locus is emitted once (_reverse_locus_index). A comment there now says so.
  • Checked, not an instance: studies.parquet.proxy_loci (parquets.py _build_studies) is never withheld; the reverse positional pass dedupes by key alone, the documented one-row-per-key fallback for a pre-0.6 parquet; reverse._carries_a_filled_cell compares _FILLABLE_IDENTITY, but is reached only when no table was read, and a parquet holds vrs_id only when one was. The enricher and format tiers carry no locus struct and no reproduction withhold.

The mechanism. The compared columns are derived from the registry, CELL_FACT_FIELDS, and with _LOCUS_ONLY they partition every carried column, so each one is either compared or keeps the locus whenever it holds a value.

The guard (compiler/tests/test_reproduced_locus_compares_every_rebuilt_column.py). The equality set(CELL_FACT_FIELDS) == _CELL_REBUILT, no exclusions, each a carried column. The walk: on a locus the cells reproduce, perturb each carried column alone, and the set that keeps the locus must equal RESOLUTION_LOCUS_FIELDS. The round trip: every reference example with a resolution.csv, provenance stripped and vrs_spec=2.0 with no id on every positioned row, reverses to a table still saying 2.0, and lap 2's artifact.digest, content_signature and resolution_signature equal lap 1's; plus the id-with-no-ref case on hfe_hemochromatosis. Red on 5b1b73b8 (all 17 round trips); mutating CELL_FACT_FIELDS to drop vrs_spec turns 18 of the 20 red.

RM386 — a publish plan was not tied to the bytes it sent or the revision it read

✅ SHIPPED 2026-11-05 on 0.8, uncut — a minor (the 0.8 audit, round 2). Owner enricher, severity medium. Class 1 of the second 0.8 audit (one run of four saw it; each instance re-verified on 0.8 at 5b1b73b8 and demonstrated against a fake hub before the fix).

Ships as built, with no practice publish to a throwaway Hugging Face repo before the cut (the maintainer's decision). The next real snapshot publish, likely a year away, is its first live run; if it fails, suspect this code first; the fix is a patch then.

Residuals won't fix — a payload the hash check or the history walk refuses has already landed, and the previous release.json stays over it until a re-run, which is what any failed second commit has always left · won't fix — the hub's pipelined uploader retries a commit whose response was lost with the same parent_commit, and the 412 that answers it is re-raised as the hub's own error rather than a refusal, because the walk finds only this write's commits; the re-run finds the hashes matching and completes

The class. A publisher plans, checks and writes, and RM368 made the module send one reading of the disk. The other publish paths still acted on names: what the hub sent was whatever the paths held when the hub got round to reading them, and what was committed landed on whatever the repo had become since the plan read it. Each instance needs a concurrent writer (a rebuild of the snapshot directory, a second publisher, a prune run from another machine), which is why no test without a repository with a head saw one. RM368 had recorded the snapshot half as a residual (no attestation a re-read could defeat, and two reads of 32 GB); the audit's scenario is the attestation: release.json describes the payload, and the second upload read it off the disk after the first had sent the payload.

Instances (file:line on 0.8 at 5b1b73b8 → after):

  1. enricher/src/just_dna_enricher/upload.py:1562, :1585 — publish_reference_snapshot's two upload_folder calls each read the directory. A rebuild landing after the payload commit put the next release's release.json over this release's rows (reproduced: R1's parquet under R2's description), and one landing while the hub read the folder sent bytes nothing hashed → every planned file is hashed once (_read_once: the sha256: and the git blob id, from one read) and stated on SnapshotPlan.sha256; the payload stays one upload_folder (RM199's resumable uploader), then _check_on_the_hub compares the tree at the payload commit with the plan (lfs.sha256 for an LFS entry, the blob id for any other) and withholds the description on a difference (PlanChangedError); release.json is sent as the bytes read with the rest, through create_commit.
  2. upload.py:1265, :1273 — upload_module's two create_commits passed no parent_commit, and the versioned-path check read the remote with no revision (:1066 file_exists, :1068 hf_hub_download), so a version another publisher landed after the check was overwritten without --force → the head is read once (_head), the check reads at it, the flat commit is pinned on it and the versioned commit on the flat one.
  3. upload.py:1562 (again), :1368, :1524 — the snapshot payload commit had no parent, and the orphan check's and the retirement's listings read the head at their own moments → both listings read at the pinned revision (check_publish_orphans_no_sidecar(…, revision=)), the payload commit is pinned on it and the description commit on the payload commit.
  4. upload.py:1450, :1489 — plan_prune listed the head and prune_repo deleted by pattern on whatever the head had become, so a file republished under a listed name after the plan was shown was deleted unseen → PrunePlan.revision is the commit the listing was read at; the deletion is one CommitOperationDelete per listed path in one commit pinned on it (no pattern reaches the hub, so RM353's escaping has nothing to escape there). A plan stating no revision refuses.
  5. enricher/src/just_dna_enricher/cli/cache_commands.py:346 — cache prune --yes called prune_repo outside any handler, and RM368's guard read only the try blocks that exist → the call sits in a try naming PublishRefused and prints PRUNE REFUSED; prune_repo joined the guard's entry list, and a second test asserts every publisher call in the CLI is inside such a try, the one allowlisted bare plan aside.

No hub write exists outside upload.py, in any tier; schema/ and compiler/ reach no hub.

The mechanism. One helper, _commit, is the only way the tier writes to the hub, and it always passes the plan's revision as parent_commit. That alone does not hold, as the code review of the first cut found: the library skips a write that changes nothing and answers with the current head without sending the precondition (a byte-identical republish took another writer's head as its own and described over that writer's sidecar), and the multi-commit uploader pins its first part only. So every write carries a per-write token in its commit description, and after the write _commit walks list_repo_commits from the answered head back to the parent: a commit without the token is another writer's, and the write is a RemoteMovedError (a new PublishRefused) that counts both kinds and names what the publish already landed (the flat path, the payload). A hub error takes the same walk from the head, so the translation rests on the history rather than on the status code; an error with no foreign commit behind it is re-raised. Every remote read after the pin names the revision. A snapshot's payload is held to the hashes of the one local read on the hub itself, which costs one full read of the snapshot beside the hub's own and holds nothing in memory. The guards, in enricher/tests/test_a_publish_is_pinned.py: test_every_hub_write_goes_through_the_one_pinned_helper (an AST walk over the package: every call to an HfApi method that takes parent_commit, the roster read off the library's signatures, is inside _commit and passes it) and test_every_remote_read_in_the_publisher_names_its_revision (every call in upload.py to an HfApi method taking revision, writes aside, plus hf_hub_download, passes one, _head aside). Mutated once each (a create_commit without parent_commit, a stray delete_files, the versioned check's file_exists without a revision, the hub check removed): each went red. The tests run against FakeHub (enricher conftest, fake_hub fixture), a git-backed repo in memory with a head, parents, a tree per revision and a hub-side refusal of a stale parent_commit; the snapshot and prune tests that used a MagicMock moved onto it.

Decisions taken. The payload stays on upload_folder, not a create_commit of paths: RM199 chose the hub's resumable multi-commit uploader for a 32 GB lane, and checking on the hub afterwards ties the bytes without giving that up. The hash runs in the real publish, not in the plan: a dry run reads no bytes, so SnapshotPlan.sha256 is empty on a rehearsal. A rehearsal reads the head and pins nothing, since it commits nothing. test_a_publish_never_reaches_for_the_deprecated_large_uploader and test_a_retirement_still_rides_the_payload_commit_at_any_size no longer build a 6 GiB sparse snapshot, which the hash would read twice per run (measured: 12 s a read); the first asserts the deprecated uploader is named nowhere in the package instead, which holds at every size. The check assumes the hub states an LFS (or Xet-backed) file's lfs.sha256 in its tree listing and a plain file's git blob id, as huggingface_hub 2.0 documents; a file stated by neither withholds the description rather than passing. The walk assumes list_repo_commits answers a commit's description as its message, as the library documents; were it not, every write would refuse rather than pass. FakeHub models the empty-write skip and a two-part upload_folder, and the module tests that kept a MagicMock give it a linear history (_linear_hub).

RM391 — the test network fence covered one client, so 31 tests asked remote services and passed on the refusal

✅ SHIPPED 2026-11-05 on 0.8, uncut — a minor (the 0.8 audit, round 2). Owner enricher (tests), severity medium.

Residuals none

The class. A rule of the suite (@network-tests-optin: network tests are opt-in with JUST_DNA_NETWORK_TESTS=1) enforced per client, by name, so the one client fenced was the only one held to it. RM372's _fenced_hub (enricher/tests/conftest.py:147-153 at 5b1b73b8) replaced HfFileSystem and hf_hub_download; nothing stood between any other test and the network.

Re-verified on 5b1b73b8, with the fence below installed and before any test was changed: 31 tests in 7 files reached a remote host (the audit counted 8 files; the same 31 ids). Each refused at its first reach, so a test whose first host was refused could have had a second behind it; the fixes were re-run under the fence until none remained.

File (tests) Host Before → after
test_civic_draft.py (15) reg.clinicalgenome.org the drafter's default ClinGen client asked live for the slice's CAID-only rows → the enricher conftest's clingen_registry_down, used through pytestmark, gives that client a 503 transport: the real client and its real unchecked, the state the tests had passed in offline
test_civic_draft_licence_row.py (3) reg.clinicalgenome.org the same → the same fixture
test_answered_call_shift.py (3) rest.ensembl.org _run said "every network-touching pass off" and turned off four passes, but the chain's live-Ensembl link has no flag of its own → _run passes offline=True
test_enrich.py (7: six functions, one parametrized twice) services.genomicmedlab.org, eutils.ncbi.nlm.nih.gov verify_ref (seqrepo) and verify_rsids (eutils) are on by default and incidental to tests about the chain, the resolver and a dbSNP outage → turned off in each call, verify_rsids kept where the outage is the subject
test_dataset_currency.py (1) services.genomicmedlab.org the CLI run's reference pass and VRS mint → the test's enrich wrapper turns both off beside its existing download=False
test_literature_terms.py (1) eutils.ncbi.nlm.nih.gov the PMCID/PMID disagreement case left eutils and Europe PMC live → scripted, as its sibling test already does
test_meta_member_rsids.py (1) services.genomicmedlab.org the reference pass → verify_ref=False; dbSNP's oracle is the subject

None was a test whose point is the live call, so none became network-only, and none lost its assertion. compiler/tests and schema/tests reached nothing, and their source trees import no transport.

After: 0 of the enricher, compiler and schema suites reach the network with the opt-in unset, outside test_the_network_is_fenced.py's own deliberate example.org provocations, which it takes itself. Measured at the branch's final conftest for the enricher suite (four chunks); compiler and schema reached nothing at the first fence, and nothing since touches them.

The mechanism: one fence at the transport, in the root conftest.py. socket.getaddrinfo, socket.socket.connect/connect_ex and gRPC's secure_channel/insecure_channel, sync and grpc.aio, over every target form gRPC names (its C core opens sockets no Python patch sees), refuse every host but this machine (loopback, unspecified, localhost, Unix sockets) unless JUST_DNA_NETWORK_TESTS=1, from import on, so collection is covered too. That covers httpx (sync and async), requests (ga4gh.vrs's seqrepo proxy), urllib, huggingface_hub and gRPC in one place. Three choices, each with the alternative it refuses:

  • It raises NetworkReachedInTests, a RuntimeError, never an OSError: every client translates a refused connection into its own unreachable, which is how all 31 passed under the audit's ConnectionRefusedError probe.
  • It records the reach, and the autouse _fenced_network fails a test at teardown when the body passed anyway: SequenceProxy.proxy() catches broadly, and seven of the 31 swallowed even the RuntimeError. A test that already failed or xfailed is not failed twice (pytest_runtest_makereport marks it). Each reach is filed under the test that made it, so a late one (a module fixture's finalizer runs after its last test's teardown) fails the run at session end under its own name and never the next, innocent test.
  • The error names the test (PYTEST_CURRENT_TEST) and the host, and says how to arrange the test. JUST_DNA_NETWORK_GUARD_LOG=<file> appends one line per refusal, which is how the 31 were listed.

_fenced_hub stays: it refuses before any socket with the hub's own remedy, and its real-cache-base half holds under the opt-in, where the transport fence steps aside.

The guard. enricher/tests/test_the_network_is_fenced.py drives each transport into the fence and asserts the refusal names the test and the host; proves the teardown net in a child pytest carrying the real root conftest (a swallowed reach is a teardown error, a raised one fails once, an xfail stays an xfail, a late reach fails the run and not the next test); keeps loopback open and steps aside under the opt-in; and holds, by an import walk, the transports the enricher imports equal to the set it drives less two named with a reason (requests, a dependency's; grpc.aio, fenced ahead of use), and the format and compiler trees to none. Mutated five times, each red: _is_local answering True (9 of the then 13), no already-failed check, no xfail check, a teardown taking every test's reaches, and grpc.aio left unfenced.

Decided without a contract, the smaller choice: the fence opens on JUST_DNA_NETWORK_TESTS=1 exactly, as _fenced_hub and the rule do. Four live tests skip on any truthy value (test_strchive_draft.py, test_strchive_bands.py, test_gnomad.py, test_drug_labels.py), so =true runs them into the fence, which refuses them loudly and names =1. The CIViC fixture is one clingen_registry_down in the enricher conftest, used by both files through pytestmark.

Out of the class, observed: test_literature.py::test_a_regex_locator_matches_the_fulltext failed once in the enumeration under load and passes alone (its regex timeout runs in a killable process). And the shape behind most of the 31: enrich() has no switch for its live-Ensembl link but offline, and verify_ref/verify_rsids default on, so an enrich() test meaning "no network" must remember them; the fence now says so the first time one forgets.

RM392 — a count in prose beside a registry or table drifted from it, in the docs and in code comments

✅ SHIPPED 2026-11-05 on 0.8, uncut — a minor (the 0.8 audit, round 2) · Severity low · Owner compiler + format + enricher (comments), docs · related @registry-completeness, RM218, RM223, RM359, RM364, RM365, RM367, RM380

Residuals won't fix — CHANGELOG.md's "Ten online … Six offline" paragraph is left to the examples regeneration, which rewrites it when it regenerates the last two examples · won't fix — the code guard reads a registry's own comment block for its own noun, so a count in a docstring, a count of a different registry, or a number with no noun after it is out of its reach and those instances were repaired by hand

The class. A number spelled in prose (a doc, a comment above a registry) beside the list or registry it counts, or a description of a behaviour beside the code that implements it, with nothing walking the two together. The registry grows, the sentence does not. The audit (round 2, class 8) found the instances below not marked "(hunt)"; the hunt across docs/ root and the three packages' comments found the rest. Re-verified on 5b1b73b8, every one held.

Instances, file:line on 5b1b73b8, before → after:

  • schema/.../overrides.py:119 "Nine, and the number is a decision rather than a count" over OVERRIDABLE_TABLES (12) → "Membership is a decision rather than a count", no number; :158 "The ninth" → dropped.
  • enricher/.../clingen_allele.py:54 "Three, and the third is not padding" over VALID_CAID_OUTCOME (5) → "unchecked is not padding". (hunt)
  • enricher/.../grch37.py:69 "Four, and the fourth is not padding" over VALID_RECOVERY_OUTCOME (5) → "unchecked is not padding", and skipped_offline named. (hunt)
  • compiler/.../tables.py:423 "the ten that carry … the seven derived-fact tables" (_FACT_TABLES is 14) → "weights plus one per table kind … every _FACT_TABLES parquet".
  • compiler/.../pipeline.py:225 the two resolution ladders "are compile-only" → since RM367 both refuse on both paths, save under the deprecated ensembl_cache, which the pre-flight is not handed. compiler/.../validate.py:410 ("what stays compile-only is a check that needs resolved rows") and :516 ("its three position-keyed cousins stay compile-only") said the same → the exemption is named as retired. (review)
  • compiler/.../binning_checks.py:24 "Today that is the four binning kinds plus pharm_variants.csv" over seven (the two 0.8 non-kind tables) → names the kinds without a count. (hunt)
  • compiler/.../fact_checks.py:235 "all five orphan checks … through five tables" (six emit the code) and schema/.../vocab.py:1658, COMPILER.md:2033 "the five orphan fact tables" → no count. (hunt)
  • enricher/.../civic_vcf.py:264 "three exceptions in twenty members" over 28 → no count. (hunt)
  • enricher/.../identifiers.py:776 "eleven authored tables carry the column" (ten carry trait_efo_id) → "every table _id_bearing_tables names"; :793 "while eleven carry the column" → "while many carried". (hunt, review)
  • schema/.../vocab.py:1149 "gnomAD v4's ten ancestry groups plus global": true, but read by the new guard as a total of RECOMMENDED_ANCESTRY_GROUPS (11) → no count.
  • SCHEMAS.md:1958 "for the seven where overriding is the intended feature" → "every table in overrides.OVERRIDABLE_TABLES".
  • SCHEMAS.md:1977-1989 the overlay key table, nine rows over twelve → adds locus_to_gene.csv, colocalisations.csv, consequences.csv.
  • SCHEMAS.md:1991 "Two derived sidecars sit outside the set … minus those two" (three do) → each named, ld_pairs.csv added, no count.
  • SCHEMAS.md:134-151 the authored roster had no meta.csv and carried gwas_effects.csv, a derived sidecar the paragraph above it says the table leaves out → meta.csv in, gwas_effects.csv out.
  • COMPILER.md:1286-1288 reverse "contributes at most one row per key" and "provenance is discarded" → the RM364/RM380 behaviour: resolution_loci written back as stored, every column but RESOLUTION_LOCUS_EXCLUDED, the cell rebuild only for a null locus.
  • COMPILER.md:2037 "the eleven an author cannot clear" → names CARRIED_WARNING_CODES. (hunt, correct but beside a table test_warning_codes.py already walks)
  • ENRICHER.md:1502 "the fourteen names" (18) and :5946 "four of the nine that carry gene" (ten) → no count. (hunt)
  • INTEGRATION_0_8.md:647, :756 "the eight RESOLUTION_LOCUS_EXCLUDED names" (seven); :724 "0.8 adds eight parquets" over a list of seven; :883 "the eight new parquets"; :722 "30 entries at 1007a26d" → no count. (hunt)
  • Not instances: CHANGELOG.md:66-68 (skipped, see Residuals); reference_examples/longevity_studies/README.md:50-55 sits in a historical section; SCHEMAS.md:3214 "the seven module_stats facets" is correct (nine AUTHORED_ROW_DERIVED_FIELDS, two unconditional).

The mechanism. Drop the count where the list is beside it (name the registry or its rule), and compare the list to the registry as a set — the hash roster's shape (test_counted_prose.py).

The guards. test_source_counted_prose.py walks every module-level sized registry in the three packages and reads the comment block directly above it; a total stated there must equal the registry's size (keys or distinct values for a mapping). A total is recognised in two shapes only: a number, bold or not, before the last word of the registry's name with only other words of its name between ("ten ancestry groups" over RECOMMENDED_ANCESTRY_GROUPS, "two parquets" over SNP_CORE_PARQUETS), and the headline idiom the stale instances used, a bold number and a comma opening a sentence (**Nine, and). Equality rather than absence, unlike RM223, because a comment on a literal often states a correct, load-bearing total and rewriting them all is a larger diff for no gain; a proximity draft flagged about fifty sub-counts. The walk's reach is an equality too: the AST walk must reach exactly the registries a plain line scan finds. Red on 5b1b73b8 with four hits (overrides, clingen_allele, grch37, vocab); reinserting "Nine," or "four** parquets" turns it red again. test_counted_prose.py adds three set equalities against the registries (the authored roster against _INPUT_FILES plus resolution.csv, the overlay key table against OVERRIDABLE_TABLES with each subject and member, the exclusions sentence against _FACT_TABLES minus OVERRIDABLE_TABLES), the reverse paragraph pinned to resolution_loci, and five more paragraphs on the rule-never-total list; all red on 5b1b73b8's docs, and reinserting "0.8 adds eight parquets" turns the list red again.

RM380 — a hand-kept struct mirrored ResolutionRow with nothing asserting the two agree, so reverse dropped every 0.8 provenance column

✅ SHIPPED 2026-11-05 on 0.8, uncut — a minor (found building RM375). Owner compiler, severity medium.

Residuals won't fix — rsid_alternates, rsid_current and rsid_status stay out of the locus, statements about dbSNP at a moment that re-running the enricher recovers (@rsid-alternates-closed), so a reversed ambiguous row's lap-2 warning names no candidates · won't fix — reverse still stamps source=reversed and an empty fetched_at, its own provenance as the link that wrote the row

The class. A column list or struct dtype written by hand beside the pydantic model it mirrors, with no test asserting the two hold the same names (@fieldnames-from-model, @registry-completeness). A column added to the model later reaches every reader of the model and silently misses the copy.

The instance that bit. parquets.RESOLUTION_LOCUS_DTYPE is the struct a parquet carries a resolution.csv row in (resolution_loci on every variant parquet since RM364, studies.parquet proxy_loci since RM331), and reverse_module rebuilds the table from it. It named ten of ResolutionRow's 24 columns, so each 0.8 column the enricher began to write — placement_witness/ placement_verdict (RM267), left_aligned (RM270), source_release (RM373) — and the 0.5 authority and caid reached the table and were dropped by the first round trip. Measured on 9becd9ad over the corpus: shox_par1 lost all four 0.8 columns on 11 rows, cpic_gene_pairs the witness, verdict and left_aligned on one, and nine examples lost authority (56 rows in cpic_gene_pairs). It mattered past the bytes: the next compile reads several of them. sources_in_use derives the used-source set from authority and the witness, so lap 2 named a declared ensembl or clinvar source unused, and placement_disagreements withholds a left_aligned true/false pair, which lap 2 could no longer see.

The re-read of RM373's choice. RM373 made reverse write no source_release, "the same way it treats authority", and RM33 gave authority the reason that a reversed row's facts came out of parquet. That conflates the link with the source: source names the link, and the link that wrote a reversed row is reverse, but the facts are still the snapshot's, answered by that release. Outside a signature (@provenance-beside-a-claim-is-outside-content-identity) is not dropped. Decided per column, the reasons in RESOLUTION_LOCUS_EXCLUDED:

  • Carried (17): the facts and locus_index; vrs_id/vrs_spec (RM270), caid (the same kind of cross-reference); authority, status, placement_witness, placement_verdict, left_aligned, authored_event, judged_coordinate, source_release. status because reverse wrote resolved for every locus, so a best-effort ambiguous pick came back resolved: lap 2 dropped the warning, the placement check stopped withholding the row, and strict built on lap 2 what it refused on lap 1.
  • Excluded (7): variant_key (the key the loci are filed under), genome_build (the module's); source, fetched_at (reverse's own stamps); rsid_alternates, rsid_current, rsid_status (time-varying statements about dbSNP, RESOLUTION_LOCUS_NOT_WRITTEN, which reverse does not write).

Every instance, file:line on 9becd9ad, before → after:

  • compiler/.../parquets.py:386 RESOLUTION_LOCUS_DTYPE, ten names by hand → derived from ResolutionRow minus RESOLUTION_LOCUS_EXCLUDED (RESOLUTION_LOCUS_FIELDS, model order; start keeps UInt32 through the one override).
  • parquets.py:436 resolution_loci's dict literal → one comprehension over RESOLUTION_LOCUS_FIELDS.
  • parquets.py:481 withhold_reproduced_loci kept a key's loci only for an authored_event → for any carried column no row cell rebuilds (_LOCUS_ONLY) holding a value other than what the cell rebuild writes (resolved for status, empty otherwise), so left_aligned=false counts. Without this the struct would have carried the columns and the withhold would have thrown them away on every cleanly resolved module.
  • compiler/.../reverse.py:839 _write_resolution_csv's header, 15 names by hand → REVERSED_RESOLUTION_FIELDS, derived (the model minus RESOLUTION_LOCUS_NOT_WRITTEN, in model order).
  • reverse.py:1114 _resolution_record's dict literal, status hardcoded resolved → every carried column read off the locus (status falling back to resolved for the cell rebuild), the stamps beside.
  • reverse.py:1159 _write_variants_csv and reverse.py:1331 _write_studies_csv headers: agreed with their models, unguarded → hoisted to VARIANTS_CSV_FIELDS/STUDIES_CSV_FIELDS (kept by hand for a readable column order) and held to authored_field_names by a parametrized equality test.
  • enricher/.../frequencies.py:52 and gene_metrics.py:59 _FIELDNAMES: agreed with FrequencyRow/ GeneMetricsRow, unguarded → held to model_fields by test_sidecar_writer_columns.py.

Not instances: enrich._FIELDNAMES (already held to ResolutionRow in test_enrich_transaction), meta._MATCH_STRUCT (mirrors no model), clinvar_gkm_build's structs and the source builders' column tuples (they mirror a source's file, not ours).

The mechanism and the guard. One exclusion map with a reason per name; everything else is derived. test_resolution_locus_carries_the_row.py asserts the model's fields equal carried ∪ excluded (disjoint, each reason five words or more), that the struct is the carried list, and that the reversed header is the model minus the not-written three and that the record reverse builds names exactly the header; that no carried column is list-typed (the scalar renderer would write a repr); it is red on 9becd9ad (the struct lacked 14 names with no exclusion stated). Its behavioural half compiles and reverses every reference example with a resolution.csv and asserts each reversed key's rows equal the original's on every carried column, plus a stamped table exercising the columns no example records yet (caid, source_release), and an ambiguous row whose warning lap 2 must repeat and whose lap-2 strict must refuse. Mutated once each: restoring the authored_event-only withhold turned nine examples and the stamped table red; a stale exclusion name turned the walk red; restoring the resolved stamp turned the ambiguous test red. RM373's test_source_release_moves_no_identity_and_reverse_writes_none is now …_and_survives_reverse.

The refusal text. _verify's strict refusal for an authored rsID↔coordinate pair the table contradicts still said the table's position "does not survive a reverse", false since RM364 carried it. It now says the position is carried beside the authored value, so the next compile reaches the same finding, and that strict builds only on a pair the table agrees with. The new phrase is pinned in features/compiler/mode_ladder.feature and test_one_channel_under_strict.py; COMPILER.md § Resolution and three enricher comments that gave the old reason were corrected.

What it moves. artifact.digest of 20 of 22 reference examples on lap 1 (every parquet carrying resolution_loci or proxy_loci widens its struct, null or not; hla_alleles and htt_repeat_expansion carry neither); nine of them also carry loci where they carried none. Lap 2 equals lap 1 on all 22. content_signature and resolution_signature move nowhere. A table that records a different source_release or authority now compiles to different bytes with the same identities.

RM381 — a reader regrouped a source's per-ALT rows under their shared padded ref, and no ALT was ever spelled alone

✅ SHIPPED 2026-11-05 on 0.8, uncut — a minor (found regenerating the reference examples). Owner enricher, severity high.

Residuals won't fix — not in this item: a position→rsID reader joins snapshot rows at the probe's own start, so an allele whose trim moves it right of its row (9,954 of 44.5 M chr16 rows, mostly one base, a substitution or delins sharing the site's leading base) is matched only as the row spells it, and a ref-less authored coordinate at such a row's padded start reads as a different event from the trimmed substitution, which it is. The helper does not close it cheaply: the row sits k bases left of the probe, k being the shared leading bases, bounded only by the row's ref length (18 at most on chr16), so an exact answer needs a range join DuckDB runs as a per-contig scan or a k-fold equality probe under an invented bound · won't fix — an rsID-only genotype that is both a ref/alt pair of the deletion and of the duplication (C/CAAAG) is written on both pieces, RM270's either-reading rule; pathogenic_clinvar also authors 11:5226762 C>CAAAG positionally, so re-derived it has one (variant, genotype) twice, which is the examples-regen unit's data decision

The class. A reader that turns a source's rows into loci grouped them by the source's own (chrom, start, ref). The split Ensembl repo (ensembl_variations_split, RM372) pads every ALT of a site to one shared ref, so that group is a multi-ALT frame no caller writes: rs1555461597 read as 16:23635706 GTT>G,GT,GTTT, rs267607291 as 11:5226773 TGG>T,TG, SHOX's rs1569493663 as X:634689 CAG>C,CAGAG. Nothing then spelled an ALT alone. Offline RM270's fill cannot left-align an indel, so the padded locus was written whole; online _filled_pieces split it but read the genotype in the padded frame, so G/GT was a compound het of two deletions (locus kept whole, left_aligned false) and SHOX's C/CAG named the deletion alone, dropping the duplication RM270 had written. The position→rsID readers compared an authored allele with the padded row, so a caller-spelled 16:23635706 GT>G back-filled no rsID. Re-deriving hboc_palb2 and pathogenic_clinvar cost test_every_row_clinvar_carries_joins six alleles, and shox_par1 lost an ALT.

The mechanism. One trim, alleles.trim_allele (drop the bases both sides end with, then those both start with, while each keeps one: bcftools norm's trim, pure string work, so offline gets it), and one regroup, sequences.per_alt_loci (each ALT trimmed, loci keyed by the trimmed (chrom, start, ref), alts and loci sorted, P7). left_normalize's substitution branch now calls trim_allele, so there is one spelling-trim. trim_allele lives in the format tier (just_dna_format.alleles), because the genotype side needs it too (@one-normalizer-two-spellings): just_dna_compiler.resolution.site_verdicts reads an authored genotype in its site's frame by trimming each allele against each locus's ref with the same helper, so a genotype authored from an unnormalized multi-ALT record keeps behaving (P3). A padded genotype (GTT/GTTT, AGA/AGAGA) names the one piece its event is, and the site's other pieces do not host it; a compound het no single piece hosts (G/GTTT) names one piece per allele. Otherwise the per-locus hosting_verdict stands, so a caller-spelled G/GT keeps RM270's either reading and a homozygote keeps the one-to-many expansion. Both resolvers, the compiler's expansion (_hostable_loci) and its membership check (_resolved_allele_verdict) ask it. Left-alignment past the trim still reads the reference (left_normalize, RM270/RM375's judge), so each piece is decided apart: a substitution left_aligned true offline, an indel unknown offline and checked online. events._trimmed is a comparison key that strips to empty, not a VCF spelling, and is left as it is.

Instances (before → after), re-verified on 1007a26d.

  • enricher/src/just_dna_enricher/resolver.py:483 _lookup_positions_by_rsid — SQL string_agg(DISTINCT alt) … GROUP BY id, chrom, start, ref → raw rows, RM271's _placeable_alleles per row, then per_alt_loci per rsID. Serves enrich, lookup_loci/lookup_variant, the deprecated DuckDB path and its _check_rsid_coord_consistency.
  • enricher/src/just_dna_enricher/clinvar.py:163 _lookup_positions_by_rsid — the same SQL group → raw rows through per_alt_loci. ClinVar's VCF is one minimal ALT per record (0 of 16,568 multi-base records of the 2026-06 snapshot move under the trim), so this closes the shape by mechanism, not a live miss. A record with no ALT places nothing and is no longer reported "not in the injected ClinVar snapshot" (it used to produce the locus alts="None").
  • enricher/src/just_dna_enricher/ensembl.py:339 _loci_from_rest — an anchored allele_string (TCTT/T/TCTTCTT) passed through as one locus → per_alt_loci over every mapping's alleles at once, so RM267's REST witness and the live fill compare the same per-ALT spellings the snapshot readers give, and two mappings spelling one allele give one locus.
  • enricher/src/just_dna_enricher/gnomad.py _loci_from_variant_ids — its own copy of the regroup, by the id's raw ref → per_alt_loci. gnomAD's ids are one minimal allele each, so this closes the copy, not a live miss; the review found it, because it reads no SQL.
  • enricher/src/just_dna_enricher/resolver.py:386 _lookup_rsid_candidates (also ClinVar's back-fill) — rref != ref against the padded ref → each nucleotide ALT matched as spelled or as trimmed at the probe's start (_names_allele).
  • resolver.py:821 _lookup_rsid_sets_by_position and :848 _lookup_rsids_by_position — WHERE … ref = ? against the padded ref → rows fetched by (chrom, start), each answering its own ref and every ALT's trimmed ref at that start (_refs_named).
  • The genotype side of the same class: orchestration (enrich's hosting filter), resolver.resolve_with_ensembl (the deprecated path), resolution._hostable_loci and allele_checks._resolved_allele_verdict each asked hosting_verdict per locus → site_verdicts over the key's loci. Before RM381 the padded frame and the padded genotype met by raw membership; after the readers trimmed, G/GTTT found no locus and AGA/AGAGA was read as both pieces, until the genotype was trimmed by the same helper.
  • Not instances: resolver._connect's view is SELECT *; clinvar.lookup_clin_sig and clinvar.select_by_gene read one ClinVar record at a time in its own spelling; the ClinVar-GKM witness is one gnomAD-spelled allele per row and regroups nothing (0 of the slice's 13 rows move under the trim).

The guard. enricher/tests/test_split_snapshot_per_alt.py, on the real rows (assets/ensembl_split_multialt/, both repos' bytes at the three sites) with ClinVar's per-ALT records in the consumer-join slice as the oracle: enrich offline writes each ALT in ClinVar's spelling with left_aligned unknown; the position back-fill meets a caller-spelled coordinate; online the split rows and the old pipe-joined rows write the same caller spelling (the old one was right only online, being right-shifted); a registry of the seven readers, each held to ClinVar's records; an AST walk asserting the set of functions whose SQL reads a snapshot's alt equals that registry plus two named non-readers, that every reader reaches trim_allele/per_alt_loci, that no SQL aggregates alt, and that the only functions building a locus whose alts joins several alleles are per_alt_loci and normalize_locus (the walk that found gnomAD's copy). Red on 1007a26d (23 of 25 at first writing). Dropping the trim's suffix loop turns 12 red; routing ClinVar's reader around the helper turns its two red. Genotype side, on both sides' raw tokens: a padded genotype against the split rows (offline and online) and against the old pipe-joined rows names its event alone (GTT/GTTT and TT/TTT → G>GT; CAG/CAGAG and AGA/AGAGA → C>CAG); the trimmed genotype names the same set on both snapshots; the compound G/GTTT is enriched and compile --stricted on its two pieces. With the frame reading switched off, six of them go red. Three tests pinned the padded spelling and now read the per-ALT one: test_enrich.py's RM31 SHOX row (634690 AGA>A), test_ensembl_indel_anchor.py's REST strings, test_ensembl_non_nucleotide.py's rs33946775 (11:5225643 T>A,C,G, three substitutions padded with a leading base).

What it moves. Re-derived offline against the split snapshot, hboc_palb2, pathogenic_clinvar and shox_par1 pass test_consumer_join (the examples-regen unit's tables miss 6 alleles there); SHOX's rs1569493663 is X:634689 CAG>C and C>CAG again. Several rsIDs gain the duplication beside their deletion where the genotype fits both (rs587776418 T/TTA), as ClinVar records both, and pathogenic_clinvar's positional 11:5226762 C>CAAAG back-fills rs80356821. A filled coordinate is outside content_signature, so no authored identity moves; resolution_signature and artifact.digest move where a fill did. No new column, code or vocabulary member.

RM387 — a check compares a hosting-narrowed answer as if it were the source's whole answer

SHIPPED 2026-11-05 on 0.8, uncut — a minor (the 0.8 audit, round 2). Owner format + enricher + compiler, severity medium. Blocked the 0.8 cut (the pm's sizing).

Residuals won't fix — a table recorded before the column still reads a sibling as two placements, since an empty source_loci cannot tell "nothing was dropped" from "never recorded"; --rederive writes the column and clears it, which is the remedy the finding already names · won't fix — not in this item: the left_aligned true/false exemption in placement_disagreements assumes one release and does not compare the two rows' source_release (the audit's class 2, Sol alone, no demo)

The class. A check comparing two sets where one was filtered before it was written and the other was not. The enricher writes the rows under an rsID's own key after the hosting filter (only the loci the authored genotype can sit on), after RM267's disputed placements are withheld, after the pseudoautosomal choice and after RM270's left-aligned respelling; it back-fills a positional row's rsID from the source's unfiltered reverse map. RM374's placement_disagreements read the rsID-keyed rows as the source's whole answer. For an rsID the source places at two loci, a positional row authored at the locus the rsID-keyed subject's genotype cannot host was a second placement: rsid_placements_disagree, compile --strict refused a valid module, and enrich --rederive wrote the same table again, so the remedy the finding names did not clear it. The audit's probe (audit2-probe/sibling.py) re-ran red on the base (cad26510), and so did the same shape written by the real enricher, rederive included.

Instances (re-verified on cad26510, before → after).

  1. compiler/src/just_dna_compiler/resolution.py:1299 placement_disagreements (was :1292): the full answer was the rsID key's places → those places plus the source_loci its rows record, a Y pseudoautosomal place read as its X partner (_folded_place, shared with _place). A row with no source_loci is the whole answer, so RM374's stale case (Q_mixed's rs761191455) still fires.
  2. enricher/src/just_dna_enricher/enrich/orchestration.py:1193 the forward branch (was :1155), and the authored fallback row at :1371: wrote only the hostable loci → also record, through _wider_answer, every place the links offered this run (the link's answer before placement.keeps, plus every answer RM382 set aside), on each row written under the rsID's key, only where it holds a place the rows stand for nowhere: a respelled piece stands for its source locus (RM374 already reads a respelling apart, by left_aligned) and a Y pseudoautosomal twin for its X partner, folded as the compiler folds it.
  3. compiler/src/just_dna_compiler/resolution.py _answer_label: the sentence named only the kept loci → it also names the offered places, (the source offered …), so the author sees what was compared.

Checked and not in the class: subjects.identity_placements / module_subjects (RM362) ask where the module sits, which is the hostable set by definition, and a positional row contributes its own position; subjects.row_positions looks the row up under its own key too, so a sibling sees itself before the rsID's answer; allele_checks._check_allele_membership compares the genotype that was the filter's input; resolution._verify is a pair whose key is the rsID, one answer; parquets.resolution_loci (RM364) is a round-trip carrier keyed by the row's own key; RM382's _rejected_by_every_subject reads the link's whole answer; resolver.check_rsid_coordinates does a fresh unfiltered lookup.

The mechanism. One recorded set and one pair of helpers: ResolutionRow.source_loci (0.8.0, outside RESOLUTION_FACT_FIELDS), spelled by just_dna_format.resolution.source_loci_cell and read by split_source_loci, which both tiers import and the field validator calls. It rides the parquets' RESOLUTION_LOCUS_DTYPE and reverse's resolution.csv, and withhold_reproduced_loci keeps a key's loci whenever one records it, so the second lap reads the answer the first did. Written only where wider, so a cleanly resolved rsID carries nothing and test_offline_enrich_then_compile_matches_duckdb_digest holds. Guarded by an equality over ResolutionRow.model_fields: every column is a field of RESOLUTION_LOCUS_DTYPE (and so of reverse's table) or in a declared not-carried set, so the next column a compile reads cannot be dropped by the round trip unnoticed (@fieldnames-from-model).

Decided here (the smaller choice where the contract is silent). The offered set includes a locus RM267 withheld as disputed and an answer RM382 set aside: a link did put the rsID there in this run, so a positional row there is not a stale answer, which is what RM374 exists to catch; the pm accepted silence for an rsID the source places at two or more loci as the floor. A subject carried by an ordinary run never gains the column, so adding a positional sibling to a module enriched before RM387 still refuses until --rederive (which, on the base, did not clear it).

The guards. enricher/tests/test_a_narrowed_answer_is_not_the_sources_whole_answer.py: the probe's shape from the real enricher (rs999 at 5:500 A>T and 6:600 A>C, A/T by rsID and A/C by position) compiles under strict, reverses with the column and recompiles to the same artifact.digest and content_signature; a table stripped of the column refuses, a plain re-run still refuses, and --rederive clears it; a property over every one-run table of a three-locus rsID (which locus the genotype keeps × which loci are authored by position, twelve tables) is silent under validate --strict; RM382's HBB rs613985 records the rejected snapshot locus; a PAR twin and a respelled piece are not "wider". compiler/tests/test_rsid_placements_disagree.py gains the probe's rows with and without the column, a place outside the recorded set, and a Y place in it; its walk over every reference example stays silent. schema/tests/test_source_loci.py: one string per set, malformed cells refused. Mutated six times, each red: the enricher writing no column (both e2e tests, nine of the twelve property tables and the HBB case), the check ignoring it, the parquet withholding a locus that records it (the round trip), the rejected answers left out of the offered set (the HBB case), no PAR fold in the enricher, and the struct losing the field (the carrier equality).

RM383 — a re-derivation leaves a licence row for a source that no committed row names any more

SHIPPED 2026-11-05 on 0.8, uncut — a minor (found regenerating the reference examples). Owner enricher, severity low.

Residuals won't fix — the nine merge passes (frequencies, gene metrics, gene validity, clinical assertions, ClinGen dosage, GWAS effects, expression effects, LD pairs, Open Targets) have no --rederive, so nothing declares that their table is the whole answer, and a licence row one of them stops earning stays until the table is deleted and the pass re-run · won't fix — a plain enrich that prunes a variant the author deleted can leave its source's row, since a merge never retires · won't fix — a concordance record deleted by hand and found uncontested writes no table (RM370), so no commit runs to retire its authorities' rows

The class. A derived pass's licence row for a source that no row of the committed table names any more. merge_sources_file never clobbers and nothing removed a row, so once a pass stopped earning a source the row stayed, and the compile warned source_row_unused about a row the pass wrote itself. Measured regenerating reference_examples/mt_common_deletion: its two point variants were back-filled from ClinVar before and from the split Ensembl snapshot after, and enrich --rederive kept clinvar,resolution (its dataset blank).

The choice: remove, by declaration. @write-the-sourcerow's converse makes the row a false statement in a published artifact (this module uses this source). Keeping it with a reason was refused: SourceRow has no field a gate could read, and an exclusion stated in prose is @one-side-only-has-two-causes. @licence-row-inside-the-commit puts the removal inside the table's commit, and @a-publish-may-not-orphan-the-bytes-it-stops-describing wants deletion by declaration, never as a side effect: the declaration is --rederive (the operator saying every row is re-answered), or a record rewritten whole on every run that writes it. A routine merging run retires nothing: its committed table may name no row of a source just as truly, but merge-not-clobber is that run's contract, and a deletion it makes without being asked is the side effect the rule forbids.

Instances, before → after. Every call of licensing.record_table_sources (RM373's one route): enrich/orchestration.py (the resolution layer: retired nothing → retires under rederive), concordance.py (the clin_sig_authority_call layer, rewritten whole: retired nothing, and recorded nothing when no authority was consulted → retires on every write; this closes RM379's second residual), and the nine merge passes in assertions.py, clingen.py, expression.py, frequencies.py, gene_metrics.py, gene_validity.py, gwas.py, ld_pairs.py, opentargets.py (unchanged, now stated answered_every_row=False).

The mechanism. record_table_sources takes answered_every_row, keyword-only, default False so a host's existing call keeps its behaviour (P3), and every call in the package passes it. When true, a row with the pass's layer and a source in TERMS_BY_SOURCE that the committed table does not name is removed (the relabel's own ownership filter, so a curator's row for a source with no terms constant is never touched), the licence table is rewritten, and an info line names each source,layer. Keyed on the committed table, so a subject nobody could ask carries its rows forward and its source stays.

The guards. enricher/tests/test_a_rederive_retires_an_unused_licence_row.py, on a copy of the example with an Ensembl cache holding its two loci as the split release does: --rederive retires clinvar,resolution, keeps ensembl,resolution, logs it, and the compile raises no source_row_unused; a plain enrich keeps both; an offline --rederive that could ask nothing keeps ClinVar's; a curator's row for an unknown source survives; and an AST walk asserts every record_table_sources call under just_dna_enricher passes answered_every_row by keyword. Red on b712a2fc (the retirement test, and the walk, which named every call); the filter forced empty turns the retirement test red, dropping the keyword from gwas.py turns the walk red, ignoring the declaration turns the plain-enrich test red, and dropping the terms-constant ownership check turns the curator test red.

RM382 — a resolution answer the hosting filter rejects ends the chain, and the row is written not_found about an rsID the sources have

SHIPPED 2026-11-05 on 0.8, uncut — a minor (found regenerating the reference examples). Owner enricher, severity medium.

Residuals won't fix — an rsID one subject hosts and another rejects keeps the first link's answer, and the rejecting subject gets no row and an AlleleMismatch rather than a later link's placement: the placement comparison (RM267) takes one authority per rsID, and a per-subject fall-through would make the authority per row · won't fix — a pair (rsID and coordinate authored) is never a reason to ask on, because no link is asked live for a pair (S104); it keeps its authored row · won't fix — the deprecated DuckDB path (resolver.resolve_variants) has one link and no chain, and is removed at 1.0

The class. Every place one link's rejected answer is written as the identity's absence. The resolver chain is first-hit-wins and every link asks only about rsIDs not yet in rsid_to_loci, while the allele-aware filter runs after all of them, in the assembly loop. So an answer whose every locus the authored genotype cannot host ended the chain, and the row-writer's last branch wrote it not_found (this source has no record of the rsID) beside the S85 warning that says the source HAS it. Measured regenerating reference_examples/pathogenic_clinvar against ensembl-variation-2026_07_13-vep116.0: HBB rs613985, authored C/CATAACAGCATCAG, has one snapshot locus, 3:159434329 T>G; ClinVar 2026-06-27 holds the authored 13 bp deletion at 11:5226724 (VCV 4074263) and was never asked.

The contract allowed the fall-through. ENRICHER's chain says a snapshot miss falls through and gives one reason for the order, digest stability: a variant both caches know keeps the Ensembl alts. A variant none of whose Ensembl loci a subject can host never compiled with an Ensembl locus, so asking on moves no digest that was not already unresolved. RM267 already routed an all-withheld rsID as unresolved with no row, in the same loop.

Instances (all in enricher/src/just_dna_enricher/enrich/orchestration.py), before → after. 1. The ClinVar cache link's gate (cv_rsids, rsid not in rsid_to_loci): a rejected cache answer counted as answered → set aside, so ClinVar is asked. 2. The staged-answer seeding: same gate → same. 3. The live Ensembl link's missing: same gate → same (and deduplicated per rsID, so one rsID costs one request and records one rejection). 4. The gnomAD link's missing: same gate → same. 5. The row writer's elif genome_build == "GRCh38" branch: reached with every answered locus rejected and wrote status=not_found → a new elif all_loci branch writes no row; the key is unresolved and named in hosting_unresolved for strict's refusal.

The positional fill and the witnesses were hunted and are not instances: the compiler's _hostable_loci reports rsid_no_hosting_locus and leaves the subject unresolved without asserting an absence, and a placement witness's unplaced describes the witness's alleles, not the subject's identity.

The mechanism. One predicate, orchestration._hosting (hosting_verdict, settled against the reference by RM274 where it withholds), read by the assembly loop and by withdraw_rejected, which runs on each link's answers as they arrive and sets aside an answer every subject of the rsID rejects, where one is rsID-only (_rejected_by_every_subject; a pair that hosts keeps the answer). The gates are untouched: withdrawing the answer reopens them. An rsID no link places gets its first answer back before the loop, so the loop sees what it saw before (its per-locus warnings, its finding), and the finding now names every link's answer (AlleleMismatch.links, loci in the same order). A later link's placement is recorded in EnrichmentResult.superseded_answers (placed_by) and logged at info. The sequence proxy and minter are built before the first link (both are lazy) so the predicate can settle an indel with the reference. Four consequences, each from the review: a withdrawn staged answer leaves staged_rsids, so a later link's row records its own release (RM373); a link whose staged answer was set aside is not asked again on resume; the rsid↔coordinate check is handed the snapshot's own answer, since it reports a snapshot comparison; and --rederive keeps a recorded placement when this run's links answered only at loci nothing can host (a link it did not reach placed it, @rederive-never-shortens) and drops a recorded not_found. A key whose live link could not be asked stays in the refusal's could-not-ask arm, not RM382's.

Departure recorded. S85 kept the not_found row on two grounds; the new-status refusal still binds (VALID_RESOLUTION_STATUS is shared with literature.csv and clinical_assertions.csv), and the signature refusal was measured against a written table. The addendum is under @answered-is-not-absent in AGENT_NOTES, and the S85 test that pinned the byte-identical rows is inverted with that reasoning in its docstring.

The guards. enricher/tests/test_a_rejected_answer_is_not_the_chains_last_word.py, real bytes of rs613985 (the snapshot row, ClinVar's two records): ClinVar places it and the compile passes strict; the snapshot alone writes no row and names the mismatch; two rejecting links are both named; strict names the rejection, or asks for the link when live Ensembl was unreachable; --rederive keeps a recorded placement and drops a recorded not_found; a subject that can host keeps the answer; and a test parametrized over the three later links (ClinVar cache, live Ensembl, gnomAD) asserts each is reached past a rejected answer. Red on 1007a26d (the 8 written first all failed); with _rejected_by_every_subject forced False the parametrized guard and three more go red. test_enrich.py::test_a_dbsnp_outage_does_not_sink_a_finished_enrichment authored its genotype on the other strand of its fixture, so the fall-through reached live Ensembl; it now authors the fixture's strand. E2E: a copy of pathogenic_clinvar, enrich --offline --rederive against the split release, records rs613985 from ClinVar and passes validate --strict.

RM376 — one rsID, three ALTs offline and one online on the same snapshot: not a misread, RM270's reference-dependent spelling rule

✖ CLOSED 2026-11-04 on 0.8 — not a defect, no code change (the 0.8 Ensembl migration probe). Owner enricher, severity low.

Residuals won't fix — offline cannot left-align without reference bases, and RM270 refuses half a respelling, so an offline fill stays whole with left_aligned unknown · won't fix — resolution_signature moving between an offline and an online fill of one snapshot is that same rule, and enrich --rederive online is the documented migration

What the probe saw. On ensembl_variations_split@ee964d71, rs746071566 (NUDT15, genotype A/AGGAGTC) was written 13:48037782 AGGAGTC>A,AGGAGTCGGAGTC,AGGAGTCGGAGTCGGAGTC offline and 13:48037782 AGGAGTC>A by --rederive online. alts is a RESOLUTION_FACT_FIELDS member, so the module's resolution_signature depended on how the run was made. The mechanism was not traced.

The three readings the probe offered, each checked against its source.

  • The offline reader merges ALTs from different positions or rows. No. The snapshot holds three rows for the rsID, all at one (13, 48037782, AGGAGTC) (row_idx 16692972–16692974: ALTs A, AGGAGTCGGAGTC, AGGAGTCGGAGTCGGAGTC), and resolver._lookup_positions_by_rsid groups on id, chrom, start, ref, so no group crosses a position.
  • REST reports one allele. No. Ensembl REST /variation/human/rs746071566 (read by hand 2026-11-04) gives 13:48037783-48037801 with allele string GGAGTCGGAGTCGGAGTCG/GGAGTCGGAGTCG/GGAGTCGGAGTCGGAGTCGGAGTCG/GGAGTCGGAGTCGGAGTCGGAGTCGGAGTCG: three ALTs. And REST never answered in the probe's run at all: the online row records source=cache.
  • The snapshot carries alleles REST does not. No. dbSNP 157 (/variation/v0/refsnp/746071566, build 157) places the same three on NC_000013.11: g.48037784GAGTCG[2], [4] and [5] against the reference's three copies, so one copy deleted, one inserted, two inserted.

The snapshot, Ensembl REST and dbSNP agree: one site with three alleles. Both readers read it right.

The mechanism: RM270's fill, which needs reference bases. The only thing that differs between the two runs is whether SequenceProxy can read GRCh38. orchestration._filled_pieces hands the locus to sequences.normalize_locus, which left-aligns each ALT on its own:

  • Offline the window reads None, so normalize_locus returns the locus unchanged with aligned=None, as RM270's "whole or not at all" says. The row is the link's locus, whole, with left_aligned blank.
  • Online the window reads CGGGCGGCGGCCAGGAGTCGGAGTCGGAGTCGTGGTGACCA (48037770–48037810). The deletion stays 48037782 AGGAGTC>A, and both insertions land on 48037782 A>…: two references, so two pieces, the split bcftools norm -m -any makes. The genotype A/AGGAGTC, in the source locus's own frame, names only the deletion, so the deletion piece is written, left_aligned=true. A genotype naming the insertions (AGGAGTC/AGGAGTCGGAGTC) gets the insertion piece; one naming both (A/AGGAGTCGGAGTC) gets the source locus whole and left_aligned=false.

So the two answers are the same snapshot read under two reach conditions, and both rows say which they are. The online row is the more precise one; the offline row is the honest unknown. The cost the probe found is real: resolution_signature moves between the two, because alts is a fact field while left_aligned is not. RM270 chose that when it refused a partial respelling, and the stamped column is what tells a reader which kind of row it holds. enrich --rederive online respells an offline-written row (@sidecar-authoritative).

Already pinned. enricher/tests/test_placement_witness.py: test_rm270_offline_a_fill_keeps_its_links_spelling_and_says_unknown (the offline half) and test_rm270_a_split_writes_the_piece_the_genotype_is_about (the online half). This case adds no new shape, so no test was added.

Next to it, owned elsewhere. The probe's --rederive online log lists this row as one that "now answer[s] differently from the recorded table", with no respelled marker. The offline row has no vrs_id, so outcome._same_events returns False for an unknown; that is the migration probe's class 4, already reserved as its own item.

RM374 — one identity answered twice in a merged sidecar, and nothing checks that the answers agree

SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 Ensembl migration probe). Owner compiler, severity medium.

Residuals RM275 · RM390 (the enricher runs the placement check too; parked) · won't fix — one key repeating a locus_index and positional-only answers are withheld, because the table cannot tell them from a legitimate one-to-many rsID · RM387 — a positional row at a locus the rsID's own answer dropped for its genotype read as two placements; the dropped locus left no trace in the table · won't fix — not in this item: a merged rsID's own key (rs_old, rsid_current naming rs_new) is not joined with a positional row back-filled rs_new, so that pair is not compared · won't fix — not in this item: the check reads every row of the table, including a subject the spec no longer names, which the next ordinary enrich drops · won't fix — not in this item: one event in two spellings within one release (an old snapshot read online) is the sibling item on authored-versus-resolved spellings

The class. A merge-not-clobber sidecar keeps every subject it already has and fills only the new ones, so after a source moves, one identity can be answered twice, by two runs against two releases, under two keys, and nothing compared the answers. The probe (Q_mixed): rs761191455 placed at 13:48041104 G>GG under its own key and at 13:48041103 T>TG under a positional key; a consumer's positional join matched 2 of 4 records, 4 of 4 after a fresh enrich; validate, compile and strict were silent. And a stale allele set (rs646776, G,T) made --strict refuse a correct A/C with a message blaming the author or ClinVar.

Instances (before → after).

  • compiler/src/just_dna_compiler/compiler/resolution_step.py read_resolution — self-checked VRS ids and coverage, never whether two subjects placed one rsID two ways → asks placement_disagreements over the active rows and routes it as a ladder (errors under strict). Both compile_module and _validate_spec call it, now with genome_build and strict, so test_check_paths's roster did not move.
  • compiler/src/just_dna_compiler/resolution.py placement_disagreements (new) — one key is one answer (_KEY_RULE = "subject", a re-run replaces it whole); two keys carrying one rsID are two answers; the finding is a positional answer whose (chrom, start) is outside the rsID-keyed answer, a Y PAR locus read as its X partner, alleles not compared. Uses _usable_loci and par_partner.
  • compiler/src/just_dna_compiler/compiler/allele_checks.py _check_allele_membership, resolved branch — two readings (the genotype, or the source's allele list) → a third, "resolved against an earlier snapshot release", naming the release the row records (row_release, read by name so RM373's ResolutionRow.source_release is picked up when it lands) or release not recorded, with --rederive.
  • schema/src/just_dna_format/vocab.py — rsid_placements_disagree in VALID_WARNING_CODES.

The mechanism and its guards. One predicate (placement_disagreements) asked in the one reader both commands share, so validate and compile cannot disagree. compiler/tests/test_rsid_placements_disagree.py builds the red case from the probe's real Q_mixed372/resolution.csv (embedded verbatim): strict validate and compile refuse with the same errors, best-effort warns once (warnings_summary 1), the finding is lap-stable across compile → reverse → compile, a fresh table is silent, and it walks every reference example's table (an equality: the code is absent from each), pinning that the walk holds shox_par1's split. Negatives: a positional answer inside the rsID's answer, a split's pieces, a PAR partner, positional-only answers, a repeated locus_index, another build, an ambiguous pick, a row with no start, and two spellings the enricher judged left_aligned true and false (one release, one event; a review of the first cut found it refused a correct module that --rederive could not clear). The stale reading is given only on rows an external source answered (authority set). test_one_channel_under_strict.py gained the case test_every_ladder_code_has_a_case demanded, and features/compiler/resolution.feature the @ladder scenario. Mutated twice: dropping the subset test sent four negatives red; routing with strict=False sent the two strict refusals red. The release-named tests skip until RM373's column exists; run against a simulated column they pass.

2026-11-05, RM387 (the 0.8 audit, round 2): the residual above was a false refusal, not a limit. The rsID key's rows are what the hosting filter kept, so for a one-to-many rsID a positional row at the sibling locus refused a valid module under strict, and --rederive wrote the same table. The rsID-keyed rows now record the source's whole set of places (source_loci) where it is wider, and this check compares against the union; a table recorded before the column still fires, and --rederive clears it.

RM375 — two spellings of one indel were judged two events wherever a comparison held no reference

SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 Ensembl migration probe). Owner enricher + compiler + format, severity medium.

Residuals won't fix — an offline run never settles a respelled indel, because the reference is read through the seqrepo service and no local reference is wired into SequenceProxy; offline the verdict is undecided, never agreement · won't fix — an indel ALT one table keeps and the other does not reads undecided on --rederive rather than moved, because an offline table keeps ALTs an online hosting filter drops (rs746071566); that costs sharpness, never truth

The class. An indel can be anchored anywhere inside its repeat, and two releases of one source, two sources, or an author and a source pick different anchors: NUDT15's rs761191455 is 13:48041104 G>GG in the old Ensembl snapshot (and in reference_examples/cpic_gene_pairs/haplotypes.csv) and 13:48041103 T>TG in ensembl_variations_split. Every place that compared two spellings of a position for event identity answered on its own terms, and where it held no reference it answered "different" rather than "unknown": the house algebra's None read as False.

The instances (re-verified on the base, 65410522 + 0.8).

  1. compiler/src/just_dna_compiler/resolution.py:468 _authored_conflict (now :509): compared start and ref by string, so the cpic row drew positional_identity_contradicted and its fill was withheld. Reproduced: re-enriched against the new snapshot, cpic compiled with the warning, and lap-1 resolution_signature moved on the bare RM372 tree (RM364's resolution_loci, merged in, holds the signature; the false warning stayed). → reads the recorded verdict; same_event is agreement and fills only rsid/chrom; undecided is left alone in non-accusing words.
  2. compiler/src/just_dna_compiler/resolution.py:1128 _verify (now :1187): the SNP core's pair, by chrom:start:ref key, refused under strict. → the same predicate, recorded_verdicts.
  3. enricher/src/just_dna_enricher/resolver.py:587–630 _is_substitution / coordinate_verdict: a locus whose ref is one base read as a substitution, which an insertion's anchor is, so the cpic pair was a confident disagreement in rsid_coordinate_agreement (the probe's "0→1 finding"). → _is_substitution removed; the verdict asks events.names_event against the reference.
  4. enricher/src/just_dna_enricher/enrich/outcome.py:70 _same_events: False whenever an allele had no vrs_id, so --rederive reported every offline respelling as the source moving (the probe's rs761191455 and rs1457579126, and RM376's rs746071566). → three-valued; SubjectDrift.respelled is bool | None and the undecided ones are warned apart.
  5. enricher/src/just_dna_enricher/placement.py same_event (RM267, ClinVar-GKM through it): already three-valued, and the model the rest now share. → moved to events.py, unchanged.

Checked and not in the class: the allele-membership union and hosting_verdict (allele sets, not positions; parsimony_reduce already reconciles G/GG with T>TG), RM270's spelling_verdict (a spelling against a convention, not two spellings against each other), and the exact-spelling archive joins (ClinVar clin_sig, PubMind, frequencies), which are join recall rather than an event-identity judgement. module_subjects' resolved placements are RM362's (merged, not redone).

The mechanism. One judge, enricher/src/just_dna_enricher/events.py: same_event for two whole alleles, names_event for an authored coordinate that may be partial (its anchors are walked by sequences.indel_spellings, one implementation shared with RM274's _indel_payloads), authored_event for a written row, same_allele_sets for a drift. The enricher judges, compile trusts: the verdict is recorded per row as resolution.csv authored_event (same_event / different_event / undecided, outside resolution_signature), written where the authored chrom/start/ref differs from the locus, bound by judged_coordinate (the coordinate it judged, authored_coordinate_key): the key is the subject's, so a verdict outlives a later edit of the coordinate and is shared with every other table's row under the rsID, and the compiler applies it only to a row still authoring that coordinate (found by the review). Both ride resolution_loci through reverse, so lap two reads what lap one did. A per-row column rather than verification.json (rewritten per run over the subjects asked; the probe's Q2 shows that record read as a module fact) or placement_verdict (who else places the rsID: another axis, P5). A derived-sidecar column, half cost (P9); additive (P3).

The guards. enricher/tests/test_authored_event.py registers every judge of two spellings (authored_event, coordinate_verdict, _same_events, compare_placements), runs each over one corpus (the cpic row, its half coordinate, offline, outside the footprint, another contig, a padded ref), and an AST walk asserts the registry equals every enricher function calling the judge. Mutating the judge to answer False with no reference turned 6 red; mutating the compiler's predicate to answer nothing turned 8 red. compiler/tests/test_authored_event.py runs both compiler comparers over every positional kind and variants.csv × the four cell states, and three rows joined test_resolution_matrix.

Not done here. reference_examples/cpic_gene_pairs/resolution.csv is not regenerated (the maintainer's decision 3: a later unit regenerates every example against the new snapshot); online, its re-derived row will read authored_event=same_event. The same online re-derive judges the example's second respelled row, NUDT15 *1 rs1457579126, authored at 13:48040982: the event is a one-base deletion in G AAAAA T (977–983), whose VCF anchors are 977–981, so 982 is the HGVS deleted-base position, inside the event and no VCF anchor. It reads undecided and compiles under the code without an accusation; the authored start is the row's to correct, by a later unit.

RM379 — enrich consults PubMind and ClinVar for the concordance record and writes no licence row for either

SHIPPED 2026-11-05 on 0.8, uncut — a minor (the 0.8 Ensembl migration probe, RM373's review). Owner enricher + format + compiler, severity low.

Residuals won't fix — CIViC writes no licence row, correctly: its two checks compare authored cells and write no row of any table, so it contributes nothing (@write-the-sourcerow's second half) · won't fix — the compiler does not corroborate this layer, so a stale row there warns nothing · RM383 (a licence row an authority stops earning is retired by the record's whole rewrite, 2026-11-05)

The class (RM373's, one rule over). A pass that consults a source writes its SourceRow, and one that contributes nothing writes none. enrich read the pubmind lane (and ClinVar's) for the clinical-significance concordance, wrote clin_sig_authority_calls.csv naming each authority per row, and recorded no licence row for either at any layer. RM373's guard listed ("enrich", "pubmind") as an exemption with that reason; this removes it.

What shipped. VALID_SOURCE_LAYERS gains clin_sig_authority_call (P5 audit: named for the table whose rows the licence row describes, singular as every layer is; no collision; fact class, so it never taints). concordance.write_concordance_tables records one row per authority a written call row names with a status other than unchecked, inside the calls table's atomic commit (before_commit, @licence-row-inside-the-commit) and through licensing.record_table_sources (RM373), so dataset is the release every such row states, read through net.stated_release. A manual authority has no terms constant and gets no row. The compiler adds the layer to _UNCORROBORABLE_LAYERS: the table's authority column is open and admits manual, so a string match cannot tell a licensed authority from a hand's, and a PubMind row would otherwise read as source_row_unused on every module carrying one.

The guards. test_producers.py's lane walk is grouped by command (the checks walk beside it already was): enrich reads PubMind's lane in enrich/ and writes its row in concordance.py, one run. The concordance producer declares release_lanes for ClinVar and PubMind, and the walk's equality holds with only CIViC exempt. test_pubmind_concordance.py asserts the two rows and their releases equal each lane's release_label, that a run with no PubMind snapshot writes no PubMind row, and that the compile raises no source_row_unused for them (watched red with the compiler line removed). test_licence_row_inside_the_commit.py names concordance.py among the passes that commit their row with their table.

SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 Ensembl migration probe). Owner format + enricher, severity medium.

Residuals won't fix — the hand-typed --ensembl-reference flag stays unchecked: it names the superseded DuckDB injection path, and the per-row column now carries the release · won't fix — an answer seeded from an interrupted run's journal records no release, because that run never wrote one down, and --rederive re-answers it · won't fix — the enricher never writes fetched_at on a resolution row: the cell says when a pass wrote a row, an axis apart from which release answered, which source_release now records, and no check reads the time · won't fix — the ensembl licence row of a table the snapshot and live REST both answered names no release: REST spells Ensembl's release ensembl_116 and the snapshot …vep116.0, and no published mapping equates them · won't fix — frequencies.csv keeps the constant gnomad_v4.1_joint: the gnomAD API states no release, and the constant names the release its numbers describe

The class. The record of which source release answered a derived fact was missing, blank, or the current run's, so an old-release answer and a new-release answer looked identical to every tier. The probe (scratchpad/rm372_migration.md, Q2/Q3 and error classes 1–2) measured it on build/RM372: a module whose resolution.csv was every row the Oct-11 snapshot's, re-enriched against ensembl_variations_split without deleting the file, kept every old row and stated the new release in rsid_coordinate_agreement.release. Two rules were broken at once: a pass that consults a source records which release it drew from (@write-the-sourcerow, @currency-asks-the-source-not-the-cache), and a record describes what it binds (@a-record-written-in-two-passes-drifts-between-them).

Every instance, re-verified on 65410522 (before → after):

  • schema/.../resolution.py ResolutionRow: no release column → source_release, optional, since 0.8.0, outside RESOLUTION_FACT_FIELDS. P5 audit: named for what it records, the release of the source that answered (the link is source, the licensed source authority); no collision with any ResolutionRow field, the reserved namespace, or SnapshotRelease.source_release (ClinVar-GKM's upstream release, the same meaning one tier over); a future per-witness release would be its own column, never a member squeezed in here. P9: a derived sidecar column, half cost; no parquet.
  • enrich/orchestration.py:1881 the ensembl/clinvar/gnomad/clinvar_gkm licence rows at resolution: record_source_terms(...) with no datasets= → record_table_sources, labelled by the committed rows (the ClinVar row was blank on every probe arm too).
  • enrich/verification_records.py:440 rsid_coordinate_agreement.release: the run's snapshot label over any table → the label only when every row the snapshot answered carries it, else null with a counted reason in detail (enrich.releases.run_label).
  • assertions.py:406, gene_metrics.py:458, frequencies.py:419, gene_validity.py:576: licence rows with a blank dataset although every row records its release → labelled from the rows' dataset.
  • gwas.py:778, expression.py:542, clingen.py:305, ld_pairs.py:517, opentargets.py:871: a label written on the first run and never revisited (merge_sources_file and record_source_terms never clobber), so a re-run against a newer release kept the old label over a mixed table → stamped from the committed table. Open Targets' tables carry no per-row release, so a row this run answered states this run's and a kept row states the label recorded before the run.
  • ensembl_reference (hand flag) and fetched_at (blank everywhere observed): re-verified, left, see Residuals.

The mechanism. One helper, licensing.record_table_sources(releases, layer, spec_dir): releases maps each source to the release every committed row it answered states (licensing.table_datasets for a table with a dataset column, enrich.releases.table_releases for resolution.csv), the label is table_release — the one release they all state, else withheld — and the cell is stamped, re-labelled or withdrawn, because merge_sources_file never fills a row an earlier run wrote blank. That is stamp_draft_digest's precedent rather than withdraw_stale_dataset's: a drafted table holds rows from releases nobody recorded, while a derived table's rows each name theirs. On resolution.csv enrich.releases.LinkReleases stamps each row this run answers with its link's release, read the way the lane states it (ensembl_release_label for the cache, snapshot.release_label for ClinVar and ClinVar-GKM, the CacheLane.release_label each declares), REST's from /info/data asked once per run (EnsemblResolver.data_release; read by hand on 2026-11-04: /info/data → {"releases":[116]}, /info/rest → {"release":"15.12"}, the software's version, so the brief's /info/rest was not used), gnomAD's from the client's dataset id. Carried and pre-0.8 rows keep what they had, --rederive stamps every row it answers. A placement witness has no column, so a carried row speaks for it through the recorded label, which was computed over every row then in the table — without that, a no-op re-run withdrew a true label.

Inside or outside the signature: outside, by @provenance-beside-a-claim-is-outside-content-identity. It says which release answered, beside the claim; two releases agreeing on a placement hash equal, and a release that moves a fact moves a fact column the signature already reads. Reverse writes none, for authority's reason: a reversed table's facts came out of parquet, so no source answered them.

The guards. DerivedProducer.release_lanes names, per pass, the lane whose release reaches its licence row; test_producers.py asserts, per command (per module until RM379), that the lanes its code reads (an AST walk over each CacheLane.resolve) equal that field plus LANES_READ_WITHOUT_A_LICENCE_ROW (CIViC's, with its reason; PubMind's was the second until RM379 gave it its row), and that no derived pass writes a licence row except through record_table_sources. Each declared lane has a behavioural test asserting the licence row equals LANES_BY_NAME[lane].release_label of the snapshot the pass read (test_source_release.py, test_placement_witness.py, test_clinical_assertions.py, test_fact_passes.py, test_opentargets.py). The probe's case is test_reenriching_an_old_table_keeps_its_rows_unlabelled_and_withholds_the_runs_label.

A derived table's release moving is not a strict matter. A filled clinvar/clinvar_gkm licence row is a release --verify-datasets compares. A source publishing past it is the source working and no authored edit clears it (@a-source-recuring-is-not-a-strict-matter), so on every layer but annotation (licensing.DRAFTED_LAYERS) the finding warns in both modes and names enrich --rederive (or deleting the derived table); only a drafted layer refuses and says re-draft.

The review round (2026-11-05), each finding with a red test first (data/rm373/red_4.txt): run_label counts only the rows the snapshot's link answered (a REST row beside a cache row no longer withholds the snapshot's label); ClinVar's label is clinvar_dataset_label, the one spelling every ClinVar reader computes (a digest-only snapshot was None here); record_table_sources stamps only rows of a source with a terms constant, so a curator's manual row is never touched; an Open Targets row this run kept states no release, because the recorded label may be a pre-0.8 first run's; a gnomAD answer records none (gnomad_r4 names a release line); data_release is asked only of this tier's own EnsemblResolver, so a host's resolver cannot abort a finished run for a label. Two more instances of the class: gwas and alphagenome expression labelled their rows by the run's date, now by the source's own release (GwasCatalogClient.release, the Catalog's /api/search/stats date, read by hand on 2026-11-05) or the bare lane when none is stated (net.release_dataset, RM361), and a licence row reads a row label through net.stated_release, so a bare lane is no release; assertions.snapshot_dataset was a second spelling of the ClinVar label and is now clinvar_dataset_label (unstated: clinvar, no longer clinvar_unknown); gene-metrics stamped the constant gnomad_v4.1_constraint on a snapshot row and now reads the snapshot's release.json. Mutated: the drafted/derived split collapsed and stated_release passing a bare lane through, each watched red.

2026-11-05, found merging block 3: the witness release map predated a witness. witness_release was a hand-kept dict in orchestration.py naming clinvar and clinvar_gkm, written before RM267 made Ensembl REST the third placement witness, and the REST witness never asked /info/data either, so a run whose snapshot answered everything and whose REST witnessed a placement contributed no release for it. Both are fixed as a class (@registry-completeness): placement.PLACEMENT_WITNESSES is the roster, read off _AUTHORITY_OF_WITNESS, and releases.witness_releases refuses a map whose keys are not exactly that roster; the REST witness takes the release the live link already asked for, or asks once itself. The link map (LinkReleases.by_link) was the same shape and is now releases.link_releases, checked against RESOLUTION_AUTHORITY_BY_LINK with gnomAD and the retired GraphQL leg named in LINKS_WITHOUT_A_RELEASE, each with its reason. Two more witness-keyed tables are guarded by equality with the roster: CHECK_WITNESSES["placement_agreement"].witness, and _NOT_INDEPENDENT, whose one deliberate omission (REST, asked about its own authority's placements by design) is named with its reason in _ASKED_OF_ITS_OWN_AUTHORITY. Not the same class: DerivedProducer.release_lanes (REST is live, not a CACHE_LANES member, and Ensembl's lane is already named) and CACHE_LANES itself (the registry, already walked). The ensembl licence row in such a run stays withheld, now for a true reason: the row REST witnessed was answered by the snapshot, whose label never equals REST's ensembl_116 string. Red on 1007a26d: test_rm373_a_rest_witness_contributes_the_release_rest_answered_from (/info/data asked 0 times, the witness's contribution None). Residuals: none.

RM372 — the Ensembl snapshot moved to a new Hugging Face repo, and a warm cache never migrates

SHIPPED 2026-11-04 on 0.8, uncut — a minor. Owner enricher + format, severity medium.

Residuals won't fix — enrich alone never migrates a cache pulled from the old repo: the resolver serves it as the whole older release it is, so an offline machine keeps its snapshot, and cache pull / cache prepare re-pull it · won't fix — the read-time check compares the manifest's bytes, not its sha256, because hashing 14.5 GB per enrich is not a read; the sha256 is checked where the bytes are already paid for, by the provisioner · won't fix — the groups/* sidecars (consequence, clinical, predictors, CADD, frequencies, transcripts; 37 GB) are not pulled: nothing here reads them, and CADD's are non-commercial

What shipped.

  • The prefix. download._ENSEMBL_HF_PREFIX is datasets/just-dna-seq/ensembl_variations_split/data, and every provisioned lane's repo is a row of download.SNAPSHOT_REPO_PREFIXES, asserted equal in keys to SNAPSHOT_FILE_GLOBS.
  • Fix 1, a warm cache from another repo. _provision_snapshot returns a cache untouched only when its pull record names this repo (locations.pull_record_repo) and its manifest attests it. A record naming another repo sends it down the pull route, where a file is kept only if the new manifest attests it by size and sha256 (locations.manifest_attests); with no manifest after a switch, every file is refetched. caches._present_or_completed sends a recorded cache from another repo to ensure, so cache pull re-pulls the old-repo cache rather than calling it present. The same keep-rule closes the case the entry did not name: a cache with no record (just-dna-lite's downloader writes none) holding old bytes was compared with the listing by name and would have been recorded as the new release.
  • Fix 2, a cache mixing releases. manifest.json joins SNAPSHOT_ROOT_FILENAMES (snapshot.SNAPSHOT_MANIFEST_FILENAME, before release.json) and is read by the enricher's SnapshotManifest (typed release_id, layout_version, built_at, files[path, group, chrom, rows, bytes, sha256]; every other key dropped, never carried). The provisioner fetches it first into a staged .part, checks every kept and every downloaded file against it, refuses a published data/ file it does not name before downloading anything, and places it last. manifest_coverage is the read-time check, in both directions: a data/*.parquet the manifest does not name or names at another size (a mixed release), or a data/ file it attests that is absent (an incomplete snapshot, found by the lead's migration probe on cc1fea4f: 12 of 25 attested files and no pull record were served silently), makes resolve_ensembl_reference (before the prebuilt .duckdb is considered: this machine's is a view over the same glob) and _resolve_parquet_cache return None for the whole directory, with a warning naming the files and cache pull. Whole rather than per file, because a dropped chromosome would read as asked-and-absent under --offline. An unreadable manifest attests nothing; no manifest is the unknown arm, read as before.
  • The label. locations.ensembl_release_label (release.json's dataset, else the manifest's release_id) is the Ensembl lane's CacheLane.release_label and the rsid_coordinate_agreement record's release.
  • Fix 3, tests and docs. test_enrich.py's multiallelic_cache is parametrized over the pipe-joined and the one-row-per-ALT spelling; @snapshot-pipe-alt names both; the builder is prepare-annotations in caches.py, download.py and ENRICHER.md. test_ensembl_split_release.py pins the rest; each check was broken once and its test went red.

Hand-run (2026-11-04). HfApi.list_repo_files: the new repo holds 203 files (.gitattributes, README.md, manifest.json, 25 data/homo_sapiens-chr*.parquet, 175 groups/<group>/…), tag ensembl-variation-2026_07_13-vep116.0, sha ee964d71b249197f9f943915b2d596286291a90e; the old one 27 (.gitattributes, README.md, 25 data files), no tag, sha 2205d5ed…, last modified 2026-01-15. The manifest: release_id ensembl-variation-2026_07_13-vep116.0, layout_version 1, built 2026-11-04T10:04:28Z, 200 files in 8 groups, 25 core files of 14,539.7 MB, core columns chrom, start, ref, alt, id, row_idx. Every core file differs in size from the old repo's. Two runs of ensure_snapshot against the live repo, on scratch caches: the 25 core files fetched beforehand with no pull record were hashed and all 25 kept as attested (214 s, nothing downloaded: the whole-genome check the entry left unverified, for the bytes rather than the claims about them); and a switch, 23 new files beside the old repo's chr21 and chrMT under the old repo's pull record, re-pulled exactly those two (112 s), dropped replacing, and resolved with the label ensembl-variation-2026_07_13-vep116.0.

The incident this build caused, and its fence. On 2026-11-04 the neighbour suite on this branch ran test_rebuild_caches_and_prepare_caches_are_the_cli_loops, which called prepare_caches on the real Ensembl lane. The developer's cache was recorded from the old repo, so the new route re-pulled it into the shared base: six chromosomes were replaced with the new release before the run was stopped. Restored the same evening from the old repo (all 25 files match just-dna-lite's .sha256 sidecars, the record names the old repo again). The fix is a class fence rather than one test: the autouse _fenced_hub (@no-test-reaches-the-real-hub) refuses the real HfFileSystem and hf_hub_download without JUST_DNA_NETWORK_TESTS=1, and any fetch into the real cache base with it; test_the_hub_is_fenced.py asserts it covers every fetching name the enricher imports. A suite run with JUST_DNA_HUB_GUARD_LOG listed every test that reached the hub, and each now arranges its own: test_cache_lanes.py::test_rebuild_caches_and_prepare_caches_are_the_cli_loops (the incident: it provisioned the real base; its lane's resolve/ensure are stubbed now), test_enrich.py::test_gnomad_link_never_overrides_an_earlier_link and ::test_gnomad_link_fills_only_what_nothing_else_could (an online enrich with no ClinVar snapshot downloaded ClinVar from HuggingFace into tmp_path on every run; download=False now), and test_upload.py::test_upload_module_calls_hf_api and ::test_the_default_commit_messages_name_which_copy_they_are (a bare MagicMock answered file_exists truthily, so the collision check called the real hf_hub_download with a fake token; False now). The fence also wraps the two provisioning bodies, so no real cache directory (the base, or a lane's own override) is provisioned under any setting: _provision_snapshot writes its pull record before its first fetch.

The placement verdicts on the new snapshot (measured 2026-11-04). Every GRCh38 reference example that resolves anything (15) was enriched --offline twice from a copy with resolution.csv deleted, once against the old snapshot and once against the new, with the ClinVar snapshot (2026-06-27) as the only placement witness: ClinVar-GKM is not provisioned on this machine, and the run predates RM267-rest's REST witness on this branch. Of 490 resolution rows (subject × locus), 180 change (the 113 + 48 + 19 below, disjoint): 129 in pathogenic_clinvar, 18 cpic_gene_pairs, 10 cyp2c19_star_alleles, 8 hboc_palb2, 6 hfe_hemochromatosis, 4 shox_par1, 2 apoe_klvs_meta, one each in hfe_compound_het, longevity_studies, model_organisms. No row appears on one side only.

  • 113 move their spelling (start/ref, with alts where the anchor base changed): the left-aligned release respells indels, and RM267's class moves onto the other event.
  • 48 gain an allele (alts alone; none loses one): dbSNP 157 and one row per ALT.
  • 19 change only source: a position the new snapshot answers that an authored or ClinVar row filled before.
  • 2 of the 113 are rsIDs newly resolved, not_found before: rs1256311452 (hfe_hemochromatosis) and rs281864532 (pathogenic_clinvar).
  • 134 placement_verdicts change: undecided → same_event 94 (the new spelling matches ClinVar's, so the comparison settles), same_event → unplaced 24 (a gained allele ClinVar does not hold, so not every ALT is placed), undecided → unplaced 2, and 14 rows gain a verdict where the old run wrote none (11 same_event, 2 undecided, 1 unplaced). No row is withheld as a disagreement in either run.

RM267's own cases, through lookup_loci on both snapshots: rs8176719 9:133257520 G>GC → 9:133257521 T>TC, rs546596010 2:26455248 C>CA → 2:26455249 T>TA, rs1553364018 1:224434031 G>GT → 1:224434032 C>CT. All three insertions of the −1 class now land on the event dbSNP and ClinVar name. rs72613567, rs77944059 and rs333 (CCR5-Δ32, RM270) move one base left, the same event respelled; rs4988235 is unchanged.

The entry as filed.

Taken into 0.8 on 2026-11-04 by the maintainer: "check compatibility and take action to be compatible if needed", after prepare-annotations published a new Ensembl variation release overnight. Measured the same day by a read-only pm subagent on a detached 0.8 worktree, reading chr21 and chrMT bytes of both repos.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor · Owner enricher (download, the Ensembl lane) + format (locations, snapshot) · Motivating case prepare-annotations 1019891 and 8044abf (2026-11-04) · related RM303, RM267, RM270, RM304

What was published. A separate dataset, just-dna-seq/ensembl_variations_split (tag ensembl-variation-2026_07_13-vep116.0), dbSNP 157 + VEP 116, written by DuckDB. The repo 0.8 reads, just-dna-seq/ensembl_variations (download.py _ENSEMBL_HF_PREFIX), has had no commit since 2026-01-15, so 0.8 is not broken today. In the new release:

  • 25 flat files, data/homo_sapiens-chr*.parquet (the old glob still matches), plus groups/* sidecars outside data/, a manifest.json (release id, per-file sha256) and no release.json.
  • The core columns are chrom, start, ref, alt, id, row_idx. start is still the 1-based POS, and chrom is spelled as before.
  • One row per ALT. alt is never pipe-joined, which retires @snapshot-pipe-alt for this repo. id is always an rs….
  • Indels are left-aligned: 301 of 400 sampled indel loci move one base left, so RM267's class disappears from the source.

What the 0.8 reader does with it. It reads the new bytes correctly. test_resolver_integration.py passes against the real files, offline enrich gives byte-identical resolution.csv on two MT examples, and the compiler suite passes under polars 1.44.2.

The build (decided): switch _ENSEMBL_HF_PREFIX to the new repo, plus three fixes.

  1. A warm cache must not serve the old repo's bytes. snapshot_record_missing (locations.py) checks only that the files exist, never the pull record's repo. The file names are identical across the two repos, so a switched prefix silently keeps the old bytes. A record naming another repo is not this snapshot.
  2. A mixed-release cache must not serve without a word. Old chrMT beside new chr21 answered 100 rsIDs and nothing complained. just-dna-lite's downloader writes the same names into the same <base>/ensembl_variations/data/. Read manifest.json's release id (add it to SNAPSHOT_ROOT_FILENAMES) and its per-file sha256. A file the manifest does not attest is withheld as a different release, never merged.
  3. Tests and docs. Every fixture uses the old pipe-joined alt and none pins one row per ALT: add one. caches.py names just-dna-pipelines as the lane's builder, but prepare-annotations builds it. Rewrite @snapshot-pipe-alt as two spellings, the old repo's and the new one's.

What moves for a module (INTEGRATION_0_8 owes a line). Resolutions move as data, not as code. Indel loci change spelling, some rsIDs gain or lose an allele (which can flip a hosting verdict), and two chr21 rsIDs are absent. An existing resolution.csv keeps the old spelling until it is deleted (@sidecar-authoritative). The RM267/RM270 placement verdicts against ClinVar were not re-run against the new snapshot, so the build re-runs them.

Not verified: whole-genome claims, since only chr21 and chrMT were read. Also unknown: whether the two missing rsIDs moved in dbSNP or were dropped by the builder.

RM365 — registry guards that are floors or subsets, and registries that omit what they describe

SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 audit, round 1). Owner format + compiler + enricher, severity low-medium.

Residuals none

A question surfaced, not filed by this build (a builder claims no number): whether literature.csv's doi_exists / doi_checked belong inside literature_signature. Answering yes is a corrected derivation that moves every literature signature on disk, so a release has to declare it; until then the reason they are out is stated as unrecorded, beside the tuple in literature.py.

The class. A registry, or the test guarding it, claims to be complete — "every check this pass writes", "everything but the provenance columns", "the diagram is the tuple" — while the assertion behind the claim is a floor (>= 31), a subset (<=), a count in prose, or a hand-kept roster nothing walks. Such a guard passes on exactly the tree that has drifted, so the registry falls behind the thing it describes and nobody is told (@registry-completeness). The rule applied: where the claim is "these are the Xs", the assertion is an equality over a walked set, with a named exemption carrying its reason; where it is only "every X is a Y" (a value inside a vocabulary, a scope narrowing a map), a subset is the honest shape and stays.

Instances, re-verified on 0.8 at 0a5293b (file:line as found):

  1. enricher/src/just_dna_enricher/producers.py:83-90 — DERIVED_PRODUCERS["resolution.csv"] claimed six checks while enrich/verification_records.py writes nine (published_refutation, evidence_status_currency, placement_agreement missing); :169, the literature producer, omitted provenance_quote. The guard, enricher/tests/test_producers.py:111, was claimed <= VALID_VERIFICATION_CHECKS. → each command's claimed checks equal the names its modules pass to ran/skipped, read by one AST walker (checks_written_in, in enricher/tests/conftest.py) that the vocabulary-wide emitter guard in test_verification_record.py now calls too. It reads ran/skipped under any import alias or module attribute and VerificationRecord(check=…) built directly; an unreadable check name is refused, and a producer module that resolves to nothing fails.
  2. schema/tests/test_first_seen.py:83-85 — len(_ALL_MODELS) >= 31 and >= 414 fields, while the registry held 38 models and 538 fields. → every pydantic model the package defines is in the registry, reachable from a document the tooling writes (ModuleManifest, VerificationDoc, ProvenanceDoc, SnapshotRelease, ReleaseRecord), or one of two named abstract bases; exactly once.
  3. schema/tests/test_first_seen.py:32 — _RELEASES, a hand list, lacked 0.7.1–0.7.3. → equal to the release tags plus the uncut version (the format package's own metadata version).
  4. First-release values: nothing checked a since() value, so ResolutionRow.vrs_spec's 0.5.0 was disputable. Measured: it is right — vrs_spec is in resolution.py at v0.5.0; the "0.8" in the dispute is the parquet that began carrying it (RM270). → every field's declaration must equal the first tag whose model carries it (the uncut release where no tag does), parsed from each tag's own sources with inherited fields resolved; the same walk refuses a published field the model lost (Principle 3) on a model still present under its name. All 538 hold. It skips, saying why, where git is missing or the clone is shallow (CI's default), rather than measuring a partial history.
  5. docs/COMPILER.md — the ARTIFACT_PARQUETS diagram drew 26 of 30 names (no locus_to_gene, colocalisations, consequences, ld_pairs) with expression_effects out of order, under a pinned "Thirty names" (the audit's "Twenty-nine" had already been corrected; its six missing names were four — meta, meta_resolved, model_organisms were drawn); the bullet below half-enumerated it again, and the _INPUT_FILES bullet lacked meta.csv and model_organisms.csv. → the diagram is compared to the tuple in order and the input list as a set (compiler/tests/test_counted_prose.py); the half-inventory points at the tuple instead.
  6. Every *_FACT_FIELDS tuple (17, in 16 modules) — each introduced as "everything but the provenance columns", and only CLINICAL_ASSERTION_FACT_FIELDS had an equality. Fifteen columns sat outside their signatures with no word about them (resolution.csv's authority, caid, vrs_id, vrs_spec, rsid_alternates, rsid_current, rsid_status, placement_witness, placement_verdict, left_aligned; literature.csv's doi_exists, doi_checked, quote_source; consequences.csv's rsid; VerificationRecord.producer), and seven provenance columns were never named. → schema/tests/test_fact_fields_partition.py: each column is in the tuple or named in a sentence of the comment above it that excludes (out, outside, except, …), which is where each module already argued its exclusions, so the exemption list is that prose rather than a second copy, and a column a sentence calls inside cannot be dropped from its tuple unseen; the tuples walked equal those integrity/verification hash. Each column now carries the reason SCHEMAS.md or its tests give; doi_exists/doi_checked say none was recorded. No tuple changed and no signature moves.
  7. enricher/tests/test_sidecar_resolution_is_uniform.py:35-47 — SIDECAR_OWNERS, the roster the no-hand-joined-path AST guard checks, was hand-kept and seven derived tables behind while its comment said it came from the layout module; its own guard was a >=. → derived from DERIVED_PRODUCERS and WRITTEN_BY_EVERY_PASS, held equal to the derived tables plus the licence spellings. The widened walk found no hand-joined path.
  8. compiler/tests/test_validate_agrees_with_compile.py:252 — registry <= covered → ==.
  9. schema/tests/test_closedness_is_measured_not_declared.py:40-75 — the closedness walk read json_schema_extra and never measured a SHARED_VOCABULARIES field (25 published vocabulary fields, clin_sig/direction/source_element/… on the binning, PGx and core models); its guard was >= 10. → it reads field_vocabularies, and every published vocabulary field must be among the measured. All agree with their validators.

Looked at and left, with the reason. enricher/tests/test_release_json_through_the_model.py:94 (len(_BUILDERS) >= 2) and test_licence_row_inside_the_commit.py:286 are vacuity guards on a glob or a walk, not completeness claims — the equality each file states is elsewhere in it, and no registry names the builder modules to derive one from. The ~90 other <= in the suites are "every value is a member" claims, where a subset is the entailed direction. compiler/tests/test_artifact_parquet_bindings.py compares two views derived from the same registries (the audit's point): a compile of an all-surfaces fixture compared against the bindings would close it, and is not built here.

Mechanism. Equalities over walked sets, each broken once on purpose and watched going red: the producer equality and the diagram/input guards red on 0.8 as found; the release list (drop 0.7.1), the model registry (drop LdPairRow), the tag measurement (vrs_spec → 0.8.0), a fact-field exclusion (unname answered_rsid) and the closedness walk (restore the narrow read) each red under mutation.

RM366 — a column meaningless without its companion validates half-stated, and the pairs that are checked are checked by eight hand-written validators

0.8, found by the four-model audit of 0.8, round 1 (2026-11-04).

Severity low · Status SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 audit, round 1) · Owner format (base.py and the row models) + compiler (validate.py) + enricher (opentargets.py) · Motivating case the audit's finding 7 (GPT-5.6 Sol), each instance constructed and validated · related RM330, RM325, RM267, RM239, RM304, RM329, RM54, RM160, @weight-has-no-unit

The class. A value whose meaning is another column — a statistic and the method that computed it, a witness and its verdict, a magnitude and its instrument or measure, a qualifier and what it qualifies. Stated without its companion, the row reads as an answer and is not one. Before this item the rule existed as eight hand-written validators on six models, each with its own wording, and was missing wherever nobody had written one.

The instances, each re-verified on 0.8 before the fix (all still held).

Where Before After
gwas.py:113 GwasEffectRow posterior_probability without fine_mapping_method, or the reverse, loaded refused (both or neither); both 0.8
locus_genes.py:211 ColocalisationRow h4 or clpp without method loaded refused (a statistic needs its method; a method alone stays legal); 0.8
resolution.py:73 ResolutionRow placement_witness without placement_verdict, or the reverse, loaded refused (both or neither); 0.8
spec.py:628 / spec.py:1209 VariantRow, StudyRow effect_size without effect_measure loaded silently reported as paired_field_half_stated in both modes, never refused: both columns are 0.3, so a published module may hold the half (P3)
spec.py VariantRow._require_quality_pair hand-written declared (both_or_neither), refused since 0.5 as before
spec.py StudyRow._refuse_a_magnitude_with_no_instrument, _refuse_half_a_stratum, the unit half of _refuse_a_count_with_no_unit… hand-written declared; the n_cases > sample_size half stays a validator (_refuse_more_cases_than_analysed), being a comparison and not a pair
concordance.py ClinSigAuthorityCallRow.model_post_init (its confidence half) hand-written declared
binning.py:509 CopyNumberRow._validate_modifier (its gene/dosage half) hand-written declared, one entry naming both dosage spellings; the both-spellings refusal stays a validator
meta.py:335 MetaRow._validate_statement (its trait_role half) hand-written declared
base.py AuthoredModel._validate_pointer_companions hand-written loop over VCF_POINTER_COMPANIONS derived by paired_fields from the same map, for every model carrying the element column
opentargets.py:591, :676 (the two writers) would have tracebacked on a release stating a statistic with no method withhold the statistic and keep the row; a withheld posterior is counted as its own reason, PosteriorCounts.method_missing, never as "not in the set" (measured: 26.09 has no such row in 1,519,507 credible sets or 79,887,470 colocalisations)

Not pairs, and why. Two candidates the brief named were tried and withdrawn when the full suite refused them. ResolutionRow.vrs_spec without vrs_id: both columns are 0.5, and the shape is real — an expansion's second locus and the vrs_version_differs remedy both clear an id beside a stated version, and compilation.vrs_version already reads it as nothing to pin (test_no_id_means_no_pin); refusing it would break P3. StudyRow.age_of without a band: RM329 decided age_of stands with or without bounds (test_no_refusal_ties_the_band_together), and two longevity examples state it unbounded. MetaRow.age_of_action_confidence without age_of_action: both are per-locus facts the meta expansion resolves column by column across every row reaching a locus, so a row stating only the confidence combines with another's age, and it is one of REQUIRED_ANY_OF's groups alone (the walking test of that declaration is what refused the first draft). A unit with no magnitude (confidence_unit, sample_unit, effect_unit): it names an instrument nothing was measured on, which is harmless, as RM160 and RM325 decided. n_cases without sample_size: its description allows it ("never more than sample_size when both are stated"). A value-dependent rule (LdPairRow's status↔r2, rsid_current beside rsid_status=merged) is a different shape from a companion column and stays a validator.

The mechanism. base.Companion(field, needs, reason, refuse) — field stated ⇒ one of needs stated — declared per model as _PAIRED_FIELDS, read by base.paired_fields(model) (which adds the element-rule pairs derived from VCF_POINTER_COMPANIONS), and enforced by the one validator on the PairedFields mixin. AuthoredModel inherits the mixin, and so do the four fact rows that carry a pair. A refuse=False entry is reported by compiler.validate._check_half_stated_pairs as paired_field_half_stated, one line per table and column. Every refusal reads <field>=<value> is set and <companion> is empty — <why>, keeping each rule's own explanation, so the phrases tests pinned survive.

The guards (schema/tests/test_paired_fields.py). A parametrized walk over every (model, rule) of _ALL_MODELS constructs the half and the whole; the models declaring a pair and the columns any rule names are asserted equal to the test's base rows and sample values, so a new pair cannot go unwalked; every model declaring a pair must inherit PairedFields, or the declaration is inert. The P3 guard asserts, as an equality, the set of refusing rules on authored models naming a column first seen before 0.8 — exactly the rules that refused before this item; a second equality lists the refusals on machine-written rows naming an older column (ClinSigAuthorityCallRow.confidence, refused since 0.7), so a new one is a stated decision; and no machine-written model may carry a refuse=False rule, which the pre-flight would never report. Mutated twice: turning StudyRow's effect_size rule into a refusal fails the P3 guard, and disabling the validator fails 32 of the walk's cases. The writers' withholding is pinned by test_a_statistic_whose_method_the_release_left_empty_is_withheld_not_a_crash, red (a ValidationError traceback) without it; the warning by compiler/tests/test_paired_field_warning.py, red with the check disabled.

Residuals won't fix — LiteratureRow.doi_exists without doi_checked is a row written before 0.6 added the second column, and the table is a pin a re-run never refetches, so refusing it would refuse true data · won't fix — the older derived tables' plausible pairs (quotes_found beside quote_source, review_stars beside review_status) were not declared because every earlier writer of those tables was not audited for the half, and a refusal there stops an enrich run on a table it merges · won't fix — GwasEffectRow.effect_size without effect_measure (both 0.6) is not declared: the gwas pass always writes the two together, a refusal would break a published hand-edited table, and a refuse=False rule on a machine-written row would be reported nowhere because the pre-flight reads the authored tables only

RM363 — one value, several normalizers: a gene, a drug, a DOI, a PMID and a contig were each compared by more than one rule

Severity medium · Status SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 audit, round 1) · Owner format (spelling.py) + compiler + enricher · Motivating case the 0.8 four-model audit, class B2 · related @one-normalizer-two-spellings, @registry-completeness, RM351, RM356

The class. A value that people and sources write more than one way, compared or keyed in more than one place, where a second place compares by a different rule than the first (or by none). Each site is right alone; the module answers two ways. RM356 made gene comparison case-insensitive in the PGx duplicate checks, and the meta-table's expansion two files away still compared raw.

Instances, re-verified on 0.8 at 0a5293b (line numbers before → the site after):

  • Gene. compiler/.../meta.py:320 diplotype.gene == target.gene → gene_key both sides (reproduced: apoe_klvs_meta with the ε3/ε4 diplotype's gene Apoe compiled green and meta_resolved.parquet lost that row's tier A / LATE); meta.py:171 member conditions compared str(stored) == value, so diplotypes[gene=apoe] matched nothing → comparison_key; table_checks.py:227 grouped the phase check by the raw gene two lines after :220 normalized it → the key, named by first spelling; manifest.py:445/507/548/579/709 published APOE and Apoe as two genes → distinct_spellings; fact_checks.py:587-590/705-708 (derived_row_orphan) → gene_key; tables.py:244 _gene_key, a compiler-private copy → spelling.gene_key. Enricher: pgx.py:229/232/294/596 (authored gene against PharmVar's/CPIC's), clingen.py:238/242, gene_validity.py:472/480, gene_metrics.py:284, identifiers.py:1424/1434, drug_labels.py:353/368/555, the CPIC snapshot client's SQL (cpic.py:635/641/659/683/732/740/756, gene = ? → lower(gene) = ? with gene_key, found by the review), and four drafters' --gene filters re-typing .strip().upper() (clinpgx_draft.py:183/198/344, mitomap_draft.py:259/263, strchive_draft.py:234/235, civic_draft.py:461/465) → gene_key.
  • Contig. VariantRow folded chr12 → 12; StudyRow (spec.py:1198), HaplotypeRow (pgx.py:159), PharmVariantRow (pgx.py:558), HeteroplasmyRow (binning.py:670) and the four derived models kept chr12 (reproduced: a chr12 coordinate study against a chr12 coordinate variant warned ['chr12:111446804:C'] as an orphan). → every chrom field is spelling.ChromCell, an input fold to the member for a primary-assembly spelling and verbatim otherwise; the canonical spelling is the one variant_key and resolution.csv already used (bare, MT).
  • DOI. spec.doi_key (spec.py:236) kept trailing punctuation and literature._doi_token (literature.py:2521) stripped .,; (measured: 10.1101/2024.01.01.123456. keyed two ways). The DOI-only path (literature.py:567-570/1663/1668, Crossref's request) and duplicate_study_citation (table_checks.py:394) used the first; the PubMed path (:1764/:2484/:2489) the second; schema literature.py:282 ran DOI_PATTERN itself; neither stripped a bracket or quote from prose around a DOI ((10.1101/…)), found by the review. → one body, spelling.doi_token/doi_key, which also drops a trailing quote and a closing bracket the DOI does not open (10.1016/S0140-6736(17)30058-2 keeps its own); the enricher's doi_missing dedup compares both sides by the key.
  • PMID. duplicate_study_citation keyed the raw pmid cell, so [PMID: 30642433] and 30642433 were two citations while cited_pmids read them as one → spec.citation_key (PMIDs through extract_pmids, or NONE + the DOI key).
  • Drug. No rule anywhere: MetaRow.drug scopes (meta.py:_scope) and member conditions compared raw, so Azathioprine and azathioprine were two scopes; clinpgx.py:356/370, cpic.py (seven queries), clinpgx_draft.py:182/223 and drug_labels.py:348/364/368 each re-typed .strip().lower() or .casefold() → drug_key; meta_resolved.parquet names a folded scope by its first spelling. A meta row's drug was never compared with its member rows' → meta_member_drug_disagrees (new code, warning in both modes, nothing withheld; an allele row is checked against the diplotypes it reaches by containment too, through the one _contained rule the resolver reads).

Hunted and not instances. trait_efo_id, haplotype and allele names, sex (a closed vocabulary stored as its member), rsIDs (^rs\d+$, one spelling), ancestry and population labels (normalize_population, one rule): each is compared by one rule everywhere. Six enricher sites compare one source's records among themselves (the ACMG SF list, STRchive's loci) and stay raw, listed with that reason in the guard.

The mechanism. just_dna_format.spelling holds one comparison per kind (gene_key, drug_key, doi_key/doi_token, and fold_chrom as ChromCell), COMPARISON_KEYS maps a column name to it, and comparison_key(column, value) is what generic code (meta selectors, same_row's distinct-when-stated columns, meta scopes, and the duplicate key of a table new in 0.8) calls. Gene and drug cells are stored as written (@verbatim-except-order); chrom keeps the input fold VariantRow already had. The guards (schema/tests/test_one_normalizer_per_kind.py): the set of string fields named gene/*_gene/drug/doi/chrom over _ALL_MODELS equals the registry; the set of chrom fields equals the set declared ChromCell; an AST walk over compiler/src and enricher/src finds no comparison, set or dict key, or setdefault/add/get key over a compared attribute outside a key function, the six one-source sites excepted by equality; no tier types .lower()/.upper()/.casefold() onto a value named as a compared kind; DOI_PATTERN is matched only in spelling.py and spec.py. Each was mutated once (a reverted meta.py:320, a chrom field un-typed, a partner_gene field added) and went red. Behaviour on the real compile path: compiler/tests/test_one_normalizer_per_kind.py, with a round trip carrying two spellings of each kind.

Residuals won't fix — within 0.x, the duplicate-row refusal of a table older than 0.8 still keys on stored cells, because folding gene or drug case there would refuse rows a published module may hold (Principle 3); a table new in 0.8 (meta.csv, model_organisms.csv) folds, derived from its fields' first_seen marks in tables._key_compared · won't fix — trait_efo_id written EFO_n and EFO:n stays two values, because unifying an ontology CURIE's two legal forms is a vocabulary decision and not a second normalizer · won't fix — a live query (the CPIC REST client's eq.{gene} filters in cpic.py, PharmVar's alleles for a gene, HGNC) still sends the authored spelling, because which case each remote accepts is that service's convention and upper-casing would break symbols such as C4orf33; the CPIC snapshot client compares lower(gene) with gene_key in SQL, where the AST guard cannot see it, so test_gated_snapshots pins it · won't fix — a pmid cell inside a key (model_organisms.csv) still compares verbatim, because its normalizer extract_pmids lives in spec, which imports spelling, so registering it would be an import cycle; duplicate_study_citation goes through spec.citation_key · RM454 — the enricher's SQL compares (the constraint snapshot by gene, both lookup_loci by rsID and contig) never went through the normalizer, found by 0.9's remote-reads follow-up, a patch after 0.9

RM367 — a check runs on one path and not the other, or after the first write

0.8, filed 2026-11-04 from the 0.8 audit, round 1 (class F).

Severity medium · Status SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 audit, round 1) · Owner compiler (pipeline.py, validate.py, resolution_step.py, check_paths.py, manifest.py, cli.py) · related @validate-refuses-all, @parity-by-check, @off-switch-needs-a-probe, RM141, RM207, RM359

The class. validate_spec is the author's pre-flight for compile_module: the two owe one verdict and one set of findings. A check that runs on one path and not the other breaks that, in either direction; so does a check that runs after a side effect — a compile refusing once it has written part of its artifact. And a switch whose callee does not hear it is the same defect one step earlier: the check runs where the caller asked for it not to.

Instances, re-verified on the 0.8 tip, and every one found in the hunt (lines are 0.8's):

  1. A refusal after the first write — pipeline.py:1080-1093: a malformed provenance.json, an unsupported logo or readme refused after output_dir.mkdir() (:689) and the parquets; a provenance.json that is not UTF-8 escaped as UnicodeDecodeError with the directory half written. The hunt added the fact-table loop's four refusals (:973 spelling, :979 load, :992 overlay, :1005 check), also below the mkdir. → All seven sit above it: the sidecars are loaded, overlaid and checked before mkdir and written after; manifest.ancillary_errors judges the three files read-only, with the compile's words, and validate_spec asks it too (it never read them).
  2. --no-resolve read the table its warning says was not read — pipeline.py:363-405 overlaid it, verified its vrs_ids (a tampered one refused) and counted them into vrs_alleles_identified while :693 wrote no id; :446/:458 judged allele membership against it; validate.py:477-497 did the same. → One reader, resolution_step.read_resolution, whose active view is empty under the switch; every consumer reads the view. The file is parsed only for the count the resolution_disabled warning publishes (its text is unchanged and now true), and that warning is the pre-flight's too.
  3. Two resolution ladders pinned compile-only — locus_cannot_host_genotype and rsid_coordinate_disagrees (test_one_channel_under_strict.py, preflight=False). The exemption they sat under ("they read resolved rows") does not hold for an injected table: applying it is pure computation over bytes the pre-flight holds. → The pre-flight runs the compile's resolution step (resolve_variants, identity_after_resolution, ploidy_after_resolution, unplaced_refusal), over the rows the compile keeps; both cases now refuse on both paths, and so does a post-resolution duplicate (variant_key, genotype), which was compile-only too.
  4. The strict aggregate on two predicates (found in the hunt) — the compile refused every row still unplaced after resolution; the pre-flight asked unresolved_subjects, which is empty for a non-GRCh38 module and was skipped under --no-resolve. So validate --strict passed a GRCh37 rsID-only module, and every reference example under --no-resolve, that compile --strict refused, and test_resolution_coverage_parity.py pinned the second as valid. → One function, unplaced_refusal, over the resolved rows, on both paths. RM359's decision that this aggregate is a different finding from the per-subject rsid_unresolved warnings stands; it is not reopened here.
  5. Warning-only checks the compile asked over resolved rows and the pre-flight never did (found in the hunt): rsid_expanded_to_multiple_loci, rsid_without_resolution_label, resolution_skipped_cross_build, resolution_not_injected on a non-GRCh38 module, contig_ploidy_* on an rsID-authored MT/Y row, derived_row_orphan from the frequency, clinical-assertion and GWAS-effect orphan checks, clin_sig_contradicts_frequency (BA1), source_row_unused, and log_file_not_shipped. Measured on the reference examples: hboc_palb2, mt_common_deletion, pathogenic_clinvar and shox_par1 compiled with a code their pre-flight never emitted, and every example carrying a resolution.csv did under --no-resolve. → Each is asked by both commands, from the shared step or from one shared helper (sources_in_use, discover_logs); validate_spec takes ba1_threshold, and the compile forwards it with its explicit ancillary files.
  6. A flag one entry point never forwarded (found in the hunt) — the validate command had no --no-resolve and no --ba1-threshold, so it could not pre-flight a compile that takes them; and test_validate_agrees_with_compile.py compared a resolving validate with compile --no-resolve, which is how instance 2 stayed green. → Both options on the command; the tests compare one mode.

The mechanism. One resolution step both commands call (compiler/resolution_step.py); one roster of the checks only one path asks, with each one's reason (compiler/check_paths.py: COMPILE_ONLY holds meta_scale_errors, which the pre-flight asks inside build_meta; PREFLIGHT_ONLY holds the checks the compile inherits through the pre-flight); and these guards, each an equality:

  • test_check_paths.py walks compile_module and _validate_spec and asserts the checks each calls minus the other's equal the roster; asserts every CompilationResult(success=False, …) lies above output_dir.mkdir() and nothing is written before it; asserts the compile forwards exactly the pre-flight options it takes, and the validate command exactly validate_spec's parameters.
  • test_one_verdict.py runs both commands over every reference example and a bad fixture per instance, in both modes and with the resolution switch both ways, and asserts equal verdicts, equal warnings_summary code sets, and no output directory after a refusal; and, over every example carrying a resolution.csv plus a tampered-id fixture, that --no-resolve compiles the parquets and resolution facts the same spec compiles with the table deleted.

Red on 0.8: 110 of the 166 test_one_verdict.py cases and four of the five test_check_paths.py walks (the refusal walk named lines 973, 979, 992, 1005, 1083, 1089, 1093). Mutating the compile's reader to ignore the switch turns 43 cases red; dropping one moved check from the pre-flight turns the roster walk red.

What is withheld rather than changed. A malformed resolution.csv still refuses under --no-resolve (its rows are parsed for the count), on both paths; a coordinate impossible in its build or a duplicate key in it no longer does, since those judge a table the switch does not read. On the deprecated ensembl_cache path the pre-flight skips every judgement over resolved rows (coverage, the strict aggregate, the four resolved-row cross-checks) rather than ask it over unresolved rows and publish a second, differently counted sentence (@no-rerun-with-counts). close_module runs the same pre-flight, so it now refuses a malformed provenance.json. Two review findings were declined: that --no-resolve should go on refusing a tampered vrs_id (it judges a table the switch does not read, which is the instance being fixed; the refusal returns with the switch off), and that the compile should take the pre-flight's resolution result instead of running the step again (a cost, not a defect; the compile's own returns stay defensive, and the ensembl_cache path needs them). A sources.csv row naming the resolution layer's authority is not reported unused under --no-resolve: a source row is about the module's files, so sources_in_use reads every row the file holds. The positional joinability report still names how many rows the unconsulted table would have placed (InjectedResolution.named_table). resolution.unresolved_subjects stays importable (the compiler re-export shell names it) and no caller in the repository uses it now.

Residuals won't fix — the deprecated ensembl_cache path stays the compile's alone, because the pre-flight is not handed that reference; it is removed at 1.0 (Principle 3's two-step retirement), and _validate_spec(legacy_reference=True) leaves its coverage judgement to the compile

RM369 — a snapshot's description is written around its bytes by hand: every builder describes a payload it has already swapped in, and readers act on keys the model does not type

SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 audit, round 1). Owner format + enricher, severity low. Found by the four-model audit of 0.8 (GPT-5.6 Sol's findings 5 and 8).

The class. RM303 made release.json a model with one writer and one reader, and stopped there: the model fixed the record's spellings but neither the order a builder writes it in nor the type of the keys a reader acts on. Two shapes of one gap, a contract a party can bypass while the walk stays green:

  • Write order. Every builder moved its payload first and wrote release.json after. A build that died between the two (a full disk, a killed process) left new bytes under the previous build's record, and every reader believes the record: the label cache status prints, the dataset a pass stamps onto SourceRow, a child's parent pin. The house cache rebuild builds into a fresh <base>/<lane>/, so only a direct build onto an existing snapshot was exposed.
  • Untyped reads. SnapshotRelease is extra="allow", so a key read out of extra (getattr, a model_dump() and .get) is unchecked: a misspelt key reads as absent, and a value of the wrong kind reaches logic. A parts_total of "seven" raised a TypeError in the Open Targets pass.

Instances (re-verified on 0.8 at 0a5293b; file:line before → after). Write order, one per builder, 16 modules, 18 write sites:

Builder Before: payload, then write_release After: begin_snapshot_write → payload → commit
acmg_build.py :292 after the CSV :268 → :292
alphagenome_avi_build.py :775, and before LICENSE.txt (:779), against SNAPSHOT_ROOT_FILENAMES' order :727 → :791, after the licence
civic_build.py :746, and before LICENSE.txt (:747) :709 → :749, after the licence
clinpgx_build.py :422 :395 → :423
clinvar_build.py (records) :546 :513 → :578
clinvar_build.py (citations) _merge_release_block :396, the old citations block standing over a new table begin_block_write :391 → :400: the block only is withdrawn, the records' provenance kept
clinvar_gkm_build.py :361, after parquet and licence (the listed instance) :339 → :362
constraint_build.py :295 :291 → :343
cpic_build.py :318 :299 → :319, after the network fetch, never before it
drug_labels_build.py :229 :213 → :296
mane_build.py :690 :669 → :801
mitomap_build.py :370 :275 → :426
mitomap_miss_build.py :391 :387 → :477
opentargets_build.py (build) :460, after rmtree(live) and the rename (the listed instance) :459, immediately before rmtree(live) → :463
opentargets_build.py (subset_snapshot) :557 :547 → :560
pharmvar_build.py :192 :166 → :193
pubmind_build.py :447 :419 → :529
strchive_build.py not an instance: it unlinked the record before the rename (:143), the one builder already right the same order through begin_snapshot_write :144

Untyped reads, 3 modules, 6 sites: opentargets.py:199-205 (parts_read/parts_total via model_dump().get and int()) and :377 → typed attributes at :198-210 and :382; clinvar_gkm.py:438 (getattr(release, "source_release", None)) → release.source_release; clinvar_gkm.py:520 (getattr(self.release, "vrs_version", None), then str()) → self.release.vrs_version; mitomap_miss_build.py:149 (stated[key], a computed key into a dump) → model_dump(include=set(PIN_KEYS)) at :148, with PIN_KEYS ⊆ the typed fields asserted. The hunt found no reader in schema/ or compiler/, and every other enricher reader already read typed fields.

The mechanism. In just_dna_format.snapshot: begin_snapshot_write(dir) withdraws release.json and returns a SnapshotWrite whose commit(release) is a builder's only route to write_release, so describing a snapshot without having withdrawn the old description is not expressible. It is opened immediately before the first byte of the live payload moves, so a download, fetch or parse that fails earlier leaves the old snapshot whole and described; a build that fails after it is not given its old record back. begin_block_write(dir, name) is the same for a half that owns one block of another build's record. And four keys readers act on are typed optional fields on SnapshotRelease: parts_read, parts_total (dict[str, int]), source_release, vrs_version (str). An old value reads through the field's validator; one of the wrong kind costs that key and never the record.

The guards. enricher/tests/test_release_json_through_the_model.py: the builders opening a write equal the *_build.py modules, no builder names write_release (planted shapes shown refused), and an AST walk over every source module of all three tiers refuses getattr/hasattr, .get, subscripts and model_extra on a release, any attribute that is not a typed field, and a non-field or computed key into its dump (six planted shapes refused, including the two 0.8 shipped). enricher/tests/test_a_build_withdraws_its_description_first.py runs every builder offline (the run table's keys equal the *_build.py modules, nothing exempted) against a directory already holding a described snapshot, with the describe step failing: nothing a reader globs may have moved when the record is withdrawn, and no release.json may be left. Red on 0.8 for all sixteen builders and subset_snapshot (STRchive red on the withdrawal check only); mutating begin_snapshot_write to skip the withdrawal turns 18 tests red, and moving CPIC's begin_snapshot_write after its payload write turns its run red on the withdrawal check.

Refused. Staging the whole snapshot and swapping it once: a directory cannot be renamed over a non-empty one, so the swap is two renames with an absent snapshot between them, the same "no description" state the withdrawal reaches, for a rewrite of sixteen builders' path plumbing (AlphaGenome's .knots beside data/, ClinVar-GKM's _downloads). And restoring the old record when a build fails: it would describe bytes the failed build may have changed.

Residuals won't fix — an in-place builder that dies mid-payload still leaves mixed old and new bytes, now under no record rather than a confident wrong one; the in-place write predates this item and cache rebuild builds into a fresh directory · won't fix — write_release stays public, so a builder outside this repository can still write without withdrawing; the guard walks this tree only, and INTEGRATION_0_8 tells such a builder what to call · won't fix — the provisioner's root-file path (download.py _provision_root_file_snapshot) fetches the payload, then release.json, and keeps a previous release.json when the second fetch fails; it is a different party from the builders this class covers, and it only runs when the payload is absent or unreadable.

RM370 — a pass that answered nothing still writes its table: a bare header is the claim this module carries these facts made about nothing

0.8, the 0.8 audit, round 1. Severity low · Status SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 audit, round 1) · Owner enricher · related @write-the-sourcerow, @rederive-never-shortens, RM142

The class. @write-the-sourcerow says a pass that contributes nothing writes no licence row, because a row in sources.csv is the claim this module uses this source. A data table beside the spec makes the same claim one file over, and seven sidecar writers made it about nothing: whenever a run had no subject to ask about (no clin_sig cell, no gene, no on-build allele, no PMID), the writer still renamed a header-only table into the module. The 0.8 reference examples carried the most visible pair.

Instances, re-verified on the 0.8 tip (each a parametrized case in the new test, red on 0.8):

Table Pass, and the run that answered nothing Before → after
clin_sig_concordance.csv, clin_sig_authority_calls.csv enrich (concordance.py _write_table), a ClinVar snapshot to consult and no clin_sig cell header-only pair → no file
frequencies.csv frequencies (frequencies.py _write_frequencies_csv), every resolved row off-build header-only → no file
gene_metrics.csv gene-metrics and dosage (gene_metrics.py _write_gene_metrics_csv, which clingen.py shares), a module with no gene header-only → no file
gene_validity.csv gene-validity (gene_validity.py _write_gene_validity_csv), no gene header-only → no file
clinical_assertions.csv assertions (assertions.py _write_assertions_csv), every resolved row off-build header-only → no file
literature.csv literature online (literature.py _write_literature_csv), every citation DOI-only (pmid=NONE) header-only → no file
licensing.csv licensing.write_sources_csv, a merge adding no row to a module with none header-only → no file (no caller reaches it today; the predicate covers it anyway)

Already clean, by an early return or a local guard, and now under the same predicate: gwas (no rsID), opentargets enrich and its four tables (if not rows and not existing), alphagenome expression (result.written), ld-pairs (no proxy pair), the drafting surface (draft.append_rows returns on not to_write). The listed hla_alleles instance does not hold on the 0.8 tip: that example carries neither file. The six files in cpic_gene_pairs, longevity_studies and model_organisms are removed (git rm); no closure binds a derived file, each still validates --strict, and compile → reverse → compile reproduces artifact.digest and content_signature with no clin_sig_* parquet in the artifact.

The mechanism: one predicate, layout.nothing_to_write(path, rows), called first by every enricher sidecar writer: zero rows and no file there already writes nothing, and since the licence row lands only inside the table's commit (before_commit, RM231) it is skipped with the table. It never suppresses a write over a file already there, and that is the smaller of the two readings the item named: zero rows over an existing table is a pass's answer, not a run that covered nothing. The concordance record clears a subject the authorities stopped contesting (a test pins it), and a merge pass prunes rows whose variant the author deleted; keeping those rows would publish a disagreement nobody has. A run that could not ask already keeps its file by never reaching the writer (@rederive-never-shortens). What the empty concordance pair used to say, asked and found nothing contested, is the clinical_significance record's denominator in verification.json; the compiler already read an empty record and an absent one alike (no manifest block), and answered_call_shift withholds an answered call as no_prior_record for both.

Two empty tables are still written, each for a stated reason. resolution.csv is written header-only when enrich placed nothing (an rsID-only module --offline with no cache): every pass after it (frequencies, assertions, opentargets enrich, vrs) refuses without the file and tells the author to run enrich first, so its presence is the record that enrich ran. It names no source and lands no licence row, and the test asserts it is written. And an empty concordance record is written where the module's overrides.csv answers it: that is RM117's vindication signal, overlay_answer_vindicated, which a missing table would turn into overlay_targets_missing_table advising the author to run the pass that just ran (reached when an author deleted the sidecar to regenerate it).

Guards. enricher/tests/test_a_pass_that_answered_nothing_writes_nothing.py: (1) one nothing-to-answer runner per (table, command) in producers.DERIVED_PRODUCERS, the runner set asserted equal to the registry, each asserting the table is absent and, where no other table answered, no licence row; (2) an AST walk asserting every enricher function that writes a CSV through atomic_writer returns on the predicate before it opens the writer (an if …nothing_to_write(…): return, not merely a call), with the exempt writers (transaction._flush's journal, acmg_build's lane, _write_resolution_csv) named with reasons and asserted equal. Mutating the predicate to False turned eleven cases red; deleting the call from ld_pairs._write turned the AST walk red. One existing test pinned the old behaviour and now pins the new one: test_clingen.py's S77 test asserted "the empty table is still written: an author must be able to see the pass ran" (the author sees it in ClinGenResult.missing, which the same test already asserts).

Residuals none

RM362 — one question, several answerers: the orphan checks read variants.csv alone while stats.genes and the enricher read every table

0.8, filed 2026-11-04 by the lead from the 0.8 four-model audit, round 1.

Severity medium · Status SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 audit, round 1) · Owner compiler (subjects.py, fact_checks.py, table_checks.py, validate.py, pipeline.py, manifest.py) + enricher (gene_metrics.py) · Motivating case the audit probe apoe_klvs_meta plus a gene_metrics.csv row for APOE · related RM28, RM157, S57, @roster-is-as-wide-as-the-tables-it-reads, @registry-completeness

The class. "Which genes, loci and variants is this module about" is one question, and each place that asked it read its own list of tables. manifest.stats.genes and the enricher's module_genes read variants.csv plus every gene-bearing table kind; the enricher's frequency, clinical-assertion and GWAS passes ask about every locus table; the study-orphan check read three tables and the rows a meta member reached; and the derived-row orphan checks read variants.csv alone and returned nothing without one. So apoe_klvs_meta warned "gene_metrics.csv names 1 gene(s) this module never mentions: ['APOE']" while its own manifest listed APOE in stats.genes, and a PGx-only module's fact tables were never checked at all.

Instances (re-verified on 0.8 at 0a5293b; all held), before → after:

  1. fact_checks._cross_check_gene_metrics — {v.gene for v in variants}, [] without variants.csv → subjects.names_gene.
  2. fact_checks._cross_check_gene_validity — the same line → the same predicate.
  3. fact_checks._cross_check_frequencies — positions of variants only → subjects.sits_at.
  4. fact_checks._cross_check_clinical_assertions — the same → subjects.sits_at.
  5. fact_checks._cross_check_gwas_effects — variant_key/rsid of variants only → subjects.carries.
  6. table_checks._cross_validate_studies — variants + haplotypes.csv + pharm_variants.csv + meta-reached rows, with heteroplasmy.csv missing → the locus roster; the meta arm is gone because a member reaches rows of meta.LOCUS_TABLES only, each already on the roster (a test asserts the inclusion).
  7. fact_checks.resolution_target_survives — the authored half placed variants.csv rows only, while reverse writes a resolution.csv row for every placed positional row (RM43): an overrides.csv correction aimed at a positioned heteroplasmy.csv row was "no artifact of this module can carry" on lap 1 and matched on lap 2 (reproduced on mt_heteroplasmy) → subjects.placed.
  8. manifest.module_stats — its own loop over _GENE_BEARING_TABLE_KINDS → module_subjects(...).genes (no answer moves).
  9. enricher.gene_metrics.module_genes — its scope was every gene table minus the non-kind registry, stated beside the compiler's → the difference from MODULE_GENE_TABLES, and the answer is module_subjects(...).gene_symbols.
  10. enricher.enrich.subjects.SUBJECT_TABLES — a hand list; left as it is (its order is precedence and each table has its own subject shape) and pinned equal to MODULE_LOCUS_TABLES plus studies.csv.

  11. positional._GENE_BEARING_TABLE_KINDS / _POSITIONAL_TABLE_KINDS — the same predicates stated a second time → read off the two rosters, so the predicate is written once.

  12. meta.member_variant_rows — the study check's meta arm, now unreachable → removed, with the test pinning its reach.

Checked and held: _cross_check_clin_sig_concordance reads variants.csv because its pass (clinical.compare_clin_sig) compares only variants.csv's clin_sig; _check_ba1_lint (a variants.csv claim); pgx._module_genes (whether the star-allele tables are present, not the module's genes); litvar.module_loci and check_identifiers (every id any authored table writes, studies.csv and model_organisms.csv included, on purpose).

The mechanism. just_dna_compiler.compiler.subjects: MODULE_GENE_TABLES and MODULE_LOCUS_TABLES, derived from _TABLE_KINDS, and module_subjects(rows_by_table) returning ModuleSubjects (genes as written, gene_symbols split on MULTI_SEP, positions, identities, placed keys, and genes_unknown/loci_unknown, which withhold when a roster table is present and loaded no row). A table off the rosters is ignored, so model_organisms.csv's gene stays out by construction. Each check keeps its join (gene, chrom:start:ref, variant_key/rsid) and every pinned sentence; the study warning's tail is now read off the roster. A row with no start contributes no position (a 19:None:None key would have matched every unplaced row on 19). validate_spec asks with two views of the one function: the rows a compile keeps (symbolic drops applied) for the gene orphans and the overlay's reachability, so each sentence is the compile's, and every authored row for the study check, which counts a dropped row as carried (the lead, 2026-11-04) and runs in that pass only.

The guard. Equalities: the rosters against the registry walk; the enricher's gene tables against MODULE_GENE_TABLES; SUBJECT_TABLES less studies.csv against MODULE_LOCUS_TABLES; meta's LOCUS_TABLES within the locus roster. And per reference example (all 22): the gene rows module_genes asks about, the loci the frequency pass asks about and the rsIDs the GWAS pass asks about, plus one decoy each, are compiled, and the orphan findings name the decoy and nothing else; stats.genes split equals module_genes. Mutating the compile's subjects back to variants.csv turns 10 of these red; narrowing the enricher's gene scope turns the roster equality red.

Measured (validate and compile over every reference example, before and after): no warning gained or lost, and stats.genes unchanged on all 22 — no shipped module carries a fact table about a gene or locus outside variants.csv.

2026-11-04, found merging RM364: a position is every spelling the module's own resolution gives a carried identity. The class: a "does the module sit at this locus" question answered from one spelling of a position, when the module's own resolution.csv says the identity sits at another. An indel has several valid spellings. RM364 restores NUDT15 *1 rs1457579126 in cpic_gene_pairs: haplotypes.csv spells it 13:48040982 A (CPIC, right-shifted), the re-enriched resolution.csv places the rsID at 13:48040978 AA (left-aligned), and the frequency pass, which asks gnomAD about the resolution row, wrote frequencies.csv at 13:48040978. module_subjects took a row's position from its own cells only, so the frequency orphan check named the pass's own row "a coordinate no variant in this module sits at", and test_module_subjects_one_answer[cpic_gene_pairs] went red. RM270 never rewrites an authored coordinate, so the row cannot be respelled. The lead's option (a), the @membership-union rule: every locus the injected table places a carried identity at, on the module's build, joins the row's own position.

Instances (hunted across all three packages, at 84dbb2a):

  1. subjects.module_subjects (positions), asked by fact_checks._cross_check_frequencies, fact_checks._cross_check_clinical_assertions and table_checks._cross_validate_studies (sits_at), in both compile_module and validate_spec (three views there: subjects, kept, resolved_subjects).
  2. fact_checks._check_ba1_lint — the pathogenic map was keyed by the variant's own chrom:start:ref, so a common frequency at the table's spelling never met the variant and BA1 stayed silent. The entry above listed it as "checked and held", which was right about the table it reads and wrong about the spelling.
  3. parquets._StudyIndex.supporting — the study join behind weights.parquet's study facts (effect_unit, eur_only_evidence, the outcome strip) matched a coordinate-only study by the variant's own spelling: a study at the table's spelling fed nothing, while the orphan check (instance 1) now says it is about the module.
  4. A locus a 1:N rsID resolves to that cannot host the authored genotype: the compile expands onto the others and re-keys them by coordinate, so the table's third row was reachable through no row's position and no row's key. The frequency pass asks about it, and its row was an orphan. Reached now through the rows' rsid.

Checked and held. resolve_from_table._verify and resolve_positional_rows compare an authored position with the table on purpose (that comparison is the contradiction report). unresolved_subjects already reads the table. allele_checks._check_study_effect_alleles keys rsID first and withholds on a missing key; table_checks haplotype signatures key rsID first, so two spellings of one rsID collapse. fact_checks.resolution_target_survives is keyed by identity and already unions the table. The enricher's collect_subjects, gwas._module_subjects and the frequency, assertion, clinical and Open Targets passes are the askers that read resolution rows, never an authored spelling. The RM364 resolution_loci path is not on 0.8.

The mechanism. subjects.identity_placements(row, resolution, genome_build): every usable locus (resolution.usable_loci, the fill's predicate, public now) the injected table files under the row's variant_key or rsid, empty without a table, under --no-resolve (the callers pass None) and off GRCh38 (where the fills decline to join, RM15). Three-valued by that predicate: a not_found row, a row with no chrom and a row on another build place nothing. module_subjects(..., resolution=, genome_build=) unions it into positions and records it apart as resolved_positions. subjects.row_positions is the per-row answer for a check that attributes a finding to a row (BA1, the study join): a row the table places where it stands (same chrom:start, and ref where the row states one) sits at its own locus only, so one expansion copy is never handed a sibling's evidence; a row the table places at exactly one other position sits there too; with several other positions it keeps its own only, because which one it means is unknown and the house algebra withholds. BA1 reports a variant once per ALT, at its strongest evidence, when both spellings carry a frequency. position_key is the one chrom:start:ref key both sides of a position join use (sits_at and the module's rows). A PAR locus needs no branch: the table holds whichever contig the enricher kept (@par-one-place), and that is the placement.

The guard. compiler/tests/test_module_subjects_placement.py: over all 22 reference examples, the GRCh38 placements resolution.csv files under a carried identity, computed off the raw table, equal resolved_positions (dropping the union turns 16 of them red); a NUDT15-shape fixture (red on 84dbb2a: the orphan fired, BA1 was silent, effect_unit was null); the not_found, other-build and --no-resolve arms, each still an orphan (mutating the predicate turns two red); --no-resolve keeping BA1 and the study join on the authored spelling; strict refusing the fixture (rsid_coordinate_disagrees), so no strict artifact's weights.parquet moves; BA1 once across two spellings; row_positions' four arms; validate/compile parity; and the expanded-rsID fixture, which alone goes red when the rsid lookup is dropped. Measured on all 22 reference examples, 84dbb2a against this change: artifact.digest, content_signature and every compile and validate warning identical.

Lap 2. On bare 0.8, reverse writes the authored spelling back as the resolution fact (RM364's finding), so a module in this state is not a fixed point before or after this change: the second lap's orphan returns and a study fact joined through the table's spelling is lost. RM364's resolution_loci makes it one; nothing here depends on it.

Residuals RM388 (the placement readers that bypass usable_loci; parked) · won't fix — gene symbols compare as written here; folding case and space is the gene-key class (the audit's class 3), not this one.

RM361 — an unknown or failed answer is recorded as a definite one: a retired endpoint as an outage, a throttle as "no copy", an unread part as "not in the release", a timed-out regex as a missed quote, an absent cell as the word None

SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 audit, round 1). Owner enricher + format + compiler, severity high.

Residuals none

The class. The house algebra is three-valued, and a question that was not answered is the third value: withheld, never a negative. The audit found a request that failed, a part that was never read, a regex that timed out, a body that would not parse and a cell that was absent each written down as a definite answer: a 410 recorded as unreachable (an outage), a 429 or a maintenance page recorded as absent (permanent, never asked again), an unread snapshot part as not_in_release, an undecided regex as a quote missing from the paper, an absent ref formatted into a key as None. The hunt across all three packages found the same shape in the places listed below. It is fixed as a class, by one mechanism per kind of boundary, each with a guard that walks the members rather than pinning a site.

The mechanism.

  • Could-not-ask carries its reason (enricher/net.py). Every client's *Retired error mixes in EndpointRetired, and a handler records could_not_ask_reason(exc): retired for a 410 (read through __cause__ too), unreachable otherwise; aggregate_reason leads with retired for a group. A client whose contract is a withheld value rather than an exception mixes in Withholding and says retired through a sticky retired message, read with withheld_reason, without raising. retired joins VALID_VERIFICATION_SKIPS and VALID_FULLTEXT_STATUS.
  • "No such thing" is one named status per client, never "every 4xx": a fulltext route's 404 and BioC's recorded [Error] : No result can be found. body (_fulltext_absent_or_raise), Ensembl REST's 400 (_REST_NO_RECORD_STATUS), GRCh37 REST's 400 (GRCH37_NOTHING_THERE_STATUS), the Hub's own not-found errors (_hub_says_absent). The fulltext and Ensembl REST routes retry a 5xx and a 429.
  • A body that is not the answer's shape is could-not-ask: an esummary with no summary block, an OLS4 body with neither a terms block nor an empty page, an HGNC body with no response.docs, a ClinGen Allele Registry body that is not an allele record, a 200 fulltext that is not JATS.
  • A read is only as complete as its record says (opentargets.read_is_complete, Kleene over the datasets READS names per table): anything but True answers no key, so nothing is replaced and nothing is not_in_release.
  • An undecided member withholds the count: literature._quotes_found is the one quote tally, and an undecided regex withholds quotes_found, which settled_quotes then counts as nothing settled.
  • An absent cell is an empty segment: base.coordinate_key is the one place a coordinate becomes a key; net.release_dataset the one place a release becomes a dataset label.

Every instance, before → after (as of 0.8 at 0a5293b):

  1. opentargets.py enrich_opentargets: a snapshot with no parts_total or a partial part answered its unread keys as not_in_release, _replace_answered dropped their L2G, coloc and consequence rows, and the posterior update nulled a filled value → no key is answered for a table whose datasets were not read whole; unmatched keys are not_read; the posterior is left as it was (posterior.not_read); strict refuses a record silent about any dataset; a malformed count no longer raises TypeError.
  2. literature.py PmcBiocClient.fetch_fulltext: any non-JSON 200 → absent → only the recorded "no result" body; anything else FulltextUnavailable.
  3. literature.py EuropePmcClient.fetch_fulltext, PmcBiocClient.fetch_fulltext, fetch_preprint_fulltext: every status below 500 → absent → only a 404; a 410 is FulltextRetired (fulltext_status="retired", asked again); a 429 is retried, then unreachable.
  4. literature.py extract_text / fetch_fulltext: XML that does not parse, or parses as a page that is not a JATS <article>, returned None (absent) or was searched as the article → FulltextUnavailable.
  5. literature.py _study_quote_found: regex_matches' None → False at three tallies, and settled_quotes counted it checked → bool | None, one count _quotes_found, quotes_found=None.
  6. literature.py lookup/record_for_doi: a missing isOpenAccess/inEPMC flag → False → None.
  7. base.py derive_variant_key: an absent ref → 13:48037749:None (nine keys in reference_examples/cpic_gene_pairs/resolution.csv, corrected) → 13:48037749; the same f-string in fact_checks.py (twice), pharmvar.py, cli/civic_commands.py, clinvar_gkm.py → coordinate_key. positional._table_row_key keyed a gene-only row as None:None:None → None.
  8. RM354's *Retired handlers wrote unreachable: identifiers.py (PGS leg, unreachable_records), currency._ask, acmg.fetch_acmg_page, civic_citations (twice, and the aggregate skip), pgx (a leg), alphagenome_check (twice), litvar (index_retired, and the record), literature (fulltext_status, the DOI route, Crossref's skip) → could_not_ask_reason.
  9. enrich/orchestration.py + verification_records.py: a dbSNP outage published rsid_currency: ran(subjects=N, findings=0) → a skip with the reason.
  10. eutils.esummary: a 200 with no summary block made every uid "no such document" (absent rsIDs, not_found PMIDs) → EutilsError.
  11. ensembl.resolve_rsid: every REST 4xx → [], written not_found → only the 400; else (None, None).
  12. download.py _provision_snapshot / _provision_root_file_snapshot: any Hub failure → SnapshotNotPublished, so cache pull printed "not published yet" and exited 0 → only the Hub's not-found errors; anything else the lane's error.
  13. gnomad.py per-alias errors (a timeout, an internal error) left a null node, written not_found by frequencies, gene_metrics and the resolver chain → GnomadClient.unanswered; no row, named (FrequencyResult.unanswered, GeneMetricsResult.unconsulted; in the resolver chain a warning, because gnomAD is the last-resort link and its error may not overwrite another link's answer), and strict refuses. An alias error saying "not found" stays gnomAD's absence.
  14. grch37.py variants_at / reference_bases: every 4xx → "nothing there" → only the 400; retries a 5xx and a 429.
  15. civic_api + civic_citations: a read short of CIViC's stated total made each recorded paper missing from it "rejected or withdrawn" → short_reads, the absence arm withheld.
  16. civic_citations.read_studies: an unparsable studies.csv → [] → nothing_to_check → None → no_reference, the detail naming the table.
  17. clingen.parse_curation_list, gene_validity.parse_clingen_validity, parse_gencc: no release line → the literal unknown in the dataset merge key → None, and the label is the bare lane.
  18. atlas_client._translate: gRPC UNIMPLEMENTED → AtlasNotScored ("no score for this variant") on every request → only on an indel; elsewhere AtlasRetired, never retried.
  19. cpic_build._fetch_all: no Content-Range count skipped the short-read guard → refuses.
  20. sequences.verify_reference_alleles: a failed read was skipped, so all failing was ran(subjects=0) and a build record saying no ref disagreed → unread, and unreachable when every read failed.
  21. identifiers.OntologyClient: an OLS4 or HGNC body of another shape → absent/unknown → IdentifierUnavailable. clingen_allele._parse: a non-record body → no_identity → unchecked.
  22. The withholding clients (CrossrefClient, PmcIdConverterClient, PmcBiocClient, Grch37Client, EnsemblResolver, ClingenAlleleClient) answered a 410 as an outage → Withholding.retired, logged once per client; Crossref's citation_existence skip and Ensembl's unreachable-rsIDs warning read it. The other four outcomes have no reason field (a GRCh37 diagnosis unchecked, a Registry outcome unchecked, an id the converter left out), and none was added: the 410 reaches the run's log.
  23. The review's: an esummaryresult "Invalid uid" envelope is NCBI's answer, not an outage; a gated or 401/403 Hub repo is not "nothing published"; lookup says "frequencies unchecked" for an allele gnomAD errored on.

Guards (enricher/tests/test_could_not_ask.py unless named): the *Retired classes equal the EndpointRetired-marked ones, walked; an AST walk refuses any except arm writing an unreachable reason without could_not_ask_reason; every CLIENTS row's 410, 503 and transport failure read through it (test_client_exception_contract.py); every fulltext route × seven legs; every Withholding class, walked, names a 410 and not a 503; every quote tally goes through one count (AST); READS equals the owned tables and covers every dataset, and every dataset × {partial, unstated} keeps every earlier row (test_opentargets.py); an AST walk over all three packages refuses a colon-joined f-string key (schema/tests/test_no_absent_value_in_a_key.py). Each was run against 0.8 and fails there, and the mechanism was mutated once (could_not_ask_reason returning unreachable for a 410: 15 red; the completeness predicate forced True: 8 red).

The corrected derivation, measured. reference_examples/cpic_gene_pairs compiled under 0.8 and under this branch: content_signature unchanged, compilation.warnings unchanged, parquet_bytes moved (haplotypes.parquet, the nine variant_key cells) and manifest_fields moved (derived's resolution.csv hash, and readme). compile → reverse → compile keeps artifact.digest and content_signature. The 0.8.0 release record owes a DeclaredChange for it (correction, item RM361).

Decisions the contract did not make, taken withholding. A partial Open Targets snapshot answers no key for the tables it did not read whole (rows it did yield are still merged); a posterior is not filled from one. An undecided regex withholds the row's whole quotes_found, not one member of it. A row naming no place keys as "". A retired fulltext row is asked again. An unparsable studies.csv skips as no_reference, no new vocabulary member. Atlas UNIMPLEMENTED on an SNV is read as a retired method (unprobed: the probe that classified the status used an indel).

2026-11-05, audit round 2: a retired endpoint was still recorded as an outage wherever a guard did not walk. The 0.8 audit's second round (class 6, found by one model of four) named three new instances of this item's class on 0.8 at 5b1b73b8; each held when re-verified there. It also named acmg.py:434-443 and was judged wrong, because that handler's skip already reads the reason. Why the guards above missed the three: (1) the client roster walks classes, and every instance but one sat in a module-level function that calls httpx itself; (2) the handler walk compared ast.Constant for equality, and f"unreachable ({exc})" is a JoinedStr whose constant piece is "unreachable ("; (3) a check reading only could_not_ask_reason passes on a plain *Unavailable raised from a 410, because the helper reads __cause__, while the type and the message still say "could not fetch". Instances, before → after:

  1. net.py:486-490 stream_to_file raised every 410 as the caller's error_cls ("could not download") at all fourteen call sites in eleven lanes (CIViC, ClinPGx, ClinVar twice, ClinVar-GKM, constraint, drug labels, MANE, MITOMAP, Open Targets three times, PubMind, STRchive) → a required retired= keyword; a 410 raises it with retired_message (the body read and quoted, the host that answered named, after any redirect), followed by the file and the lane's own remedy, which still applies when the retired file is a release the operator picked. New: CivicRetired, ClinPgxRetired, ClinVarRetired, ConstraintRetired, DrugLabelRetired, ManeRetired, MitomapRetired, OpenTargetsRetired, PubMindRetired, StrchiveRetired, each beside its *Unavailable; ClinVar-GKM's download raises ClinVarGkmRetired.
  2. clinvar_gkm.py:450-453 lane_currency: ClinVarGkmRetired caught as ClinVarGkmUnavailable and written unchecked="unreachable (…)" → the reason from could_not_ask_reason, retired (…).
  3. clingen.py:161-168 fetch_curation_list: a 410 → ClinGenUnavailable, "could not fetch" → ClinGenRetired.
  4. Found by the hunt: gene_validity.py:388-401 fetch_validity_export → GeneValidityRetired (the host names the submitter); mane_build.py:592-604 discover_current_release → ManeRetired.
  5. Found by the hunt: the placement witness (enrich/orchestration.py:860; the reason is dropped at placement.py:416-432). EnsemblResolver noted a REST 410 (Withholding.retired), and the record's not-asked sentence still said "unreachable after retries…" → REST_RETIRED_REASON, a fixed sentence: the source's body stays in the log, since the record is attested and must be lap-stable, and it says "at least once" because the resolver's note is sticky across the run.
  6. acmg.py:434-443 fetch_acmg_page, the instance the audit judged wrong: the recorded skip was right, but the type and the message were the outage's, and the guard asserts the type → AcmgRetired (its skip defaults to retired).

Checked and not instances: clinpgx_build.probe_archive_dates answers None for every failed HEAD, a 410 included, because it gates nothing (pinned as a withhold). atlas_protos.fetch_protos reads a pinned commit through urllib, and the Hub routes in download.py go through huggingface_hub; both sit outside an httpx walk, and neither is a source that retires a path (a pinned commit's file 404s).

Guards (enricher/tests/test_could_not_ask.py). An AST walk finds every module-level class and function that calls an httpx transport. A class withholds, or its module declares a *Retired. A function is a FETCHERS row (or the one withholding probe), asserted equal to the walk. Each row is driven three ways: a 410 must raise its lane's could-not-ask type marked EndpointRetired, with the body quoted and no partial left; a 503 and a refused connection must raise it unmarked, read as unreachable. A third walk checks every stream_to_file call: its retired= resolves, in the calling module, to a subclass of its error_cls and of EndpointRetired. The handler walk reads an f-string that opens with unreachable, and its not-vacuous test runs that one predicate over all four spellings. The placement case is test_placement_witness.py. Red on 5b1b73b8: the five functions' 410s, stream_to_file's two outage legs (no retired=), the handler walk (clinvar_gkm.py:452), lane_currency and the placement sentence. Each mutation turns a guard red: dropping raise_if_retired from stream_to_file fails its row, and retired=MitomapUnavailable fails the call-site walk. The entry's **Residuals** line above stays none.

RM368 — what the module publisher plans, checks and sends are three readings of the disk

SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 audit, round 1). Owner enricher, severity medium. Reported by four builders of the 0.8 round, each instance re-verified on 0.8 at 0a5293b.

Residuals won't fix — the reference-snapshot send stays an allowlist over the plan's names: a snapshot records no per-file hash (SnapshotRelease has none), so there is no attestation a re-read at send time could defeat, and byte-verifying a 32 GB lane at send would read it twice · RM386 took that back on 2026-11-05: release.json is the attestation a re-read defeated, so the snapshot payload is now hashed once and checked on the hub before it is described

The class. A publisher states what it will send (the plan), checks it (the plan's refusals and the remote guard), and sends it. Each of the three read the disk, the manifest or the remote on its own, so they could disagree: a check ran over one reading and the send shipped another; a field read as absent dropped the check that field feeds; the dry run ran a different set of checks from the real run; a refusal came out as a type no caller could tell from an unrelated failure; and the prose describing the checks counted them wrong.

Instances (file:line on 0.8 at 0a5293b → after):

  1. enricher/src/just_dna_enricher/upload.py:918, :928 — upload_folder(folder_path=…) re-read the directory after the plan hashed the declared files and the guard compared the in-memory manifest; manifest.json itself was re-read by the hub. A recompile between the two shipped bytes nothing checked → the plan records every planned file's sha256 (UploadPlan.sha256, the manifest's from the very bytes parsed), and the send reads each file once more, compares, and commits those bytes through create_commit (_verified_payload); a change is PlanChangedError.
  2. upload.py:452–457 (_file_entries) and :644–646 — an artifact.files that was not a list read as absent and fell back to the allowlist, dropping the attestation check; :449 (_named_entry) read a non-string sha256 as unknown, dropping the hash check (:740); :502–512 (_declared_files) dropped a logs, logo, readme or provenance of the wrong shape → _declarations walks DECLARED_FILE_FIELDS once and the plan refuses a present-but- malformed field, quoting it (ModuleNotPublishable); absent or null is still the unknown arm.
  3. upload.py:743–830 (_versioned_conflict) compared the digest and the declared files, never manifest.json: the same data under a new title replaced the published manifest of a version without --force → a third arm, _manifest_differences, names the dotted paths of every other field that differs; a remote manifest whose bytes hash to the plan's is the same release.
  4. cli/module_commands.py:141 — upload --dry-run called plan_upload alone and skipped the versioned-path check the real run refuses on, while RM355's title read as parity → rehearse_upload (the plan plus the read, read-only, no repo created). The same in the snapshot commands: civic_commands.py:318, gene_reference_commands.py:103, mitomap_commands.py:238, pgx_commands.py:228, :262, :548, strchive_commands.py:110, alphagenome_commands.py:496 skipped the orphan check that clinvar_commands.py:97 and cache_commands.py:483 ran → rehearse_reference_snapshot for every one.
  5. enricher/tests/test_upload.py:1389 — the RM355 dry-run test ran a real upload with no network guard, offline only because the plan refused first → an autouse fixture blocks HfApi and hf_hub_download for the whole file.
  6. upload.py:446 — a whitespace-only name named a file → blank is no name. The attested-entry refusal (:460–473) covers every entry that is not an object with a non-blank string name, wider than the "" RM355's CHANGELOG entry and ENRICHER bullet describe → ENRICHER states the whole class (RM355's shipped CHANGELOG entry is left as written).
  7. upload.py:650, :661, :684, :693, :700, :967, :980 raised FileNotFoundError for a refusal → PublishRefused is the family: ModuleNotPublishable, SnapshotNotPublishable (both keep FileNotFoundError as a second base within 0.8), PlanChangedError, and the existing PublishCollisionError, ToolchainDiffersError, OrphanedSidecarError re-based under it. Every CLI try around a publish catches the family; pgx_commands.py:231 and :265 (cpic publish, clinpgx publish) caught nothing and tracebacked.
  8. upload.py:299 "the three refusals plan_upload raises" and cli/module_commands.py:158 "the three plan_upload refusals" (there were five); ENRICHER.md "Three consequences" above four bullets, "Four things about the gate" above five, "Three positive rules" → the counts are gone.

The mechanism. One plan, read once, is what every check reads and what the send carries: paths and hashes, the manifest among them, verified again at send time with the verified bytes sent. One walker over a registry of declared fields decides absent (withhold) against malformed (refuse). One rehearsal per publisher is the dry run. One error family. The guards: test_the_publisher_reads_every_field_that_names_a_file (the ModuleManifest fields reaching a FileEntry or a Provenance equal DECLARED_FILE_FIELDS ∪ SPEC_SIDE_FILE_FIELDS); test_every_declared_field_has_a_malformed_case (the parametrization walks that registry); test_every_refusal_the_publisher_raises_is_in_its_family (an AST walk: the names upload.py raises equal PublishRefused's subclasses plus PermissionError and ImportError); test_every_publish_command_catches_the_refusal_family (every CLI try calling the publisher names PublishRefused); test_every_dry_run_is_a_rehearsal (the CLI's bare-plan callers equal one allowlisted reproduction check); and the file-wide network block. Each was mutated once and went red.

Decisions taken. Two commits stay two (one create_commit carrying both paths is now a small change, not taken). The manifest arm leaves out the stamps of the act of compiling (COMPILATION_STAMPS: compiled_at, compiled_by, each with its reason), so a recompile of an unchanged spec republishes as a no-op, as it did before; toolchain stays compared, since RM342 reads it. A test holds those stamps and COMPILATION_COMPARED equal to Compilation's fields. The two plan refusals keep FileNotFoundError as a second base within 0.8, so no existing handler stops catching them. RM355's decision that an optional entry naming no file (an empty or blank name) is dropped stands; a name present and not a string is malformed and refuses. The send holds the module's bytes in memory for the two commits, which a module affords; it is the reason the snapshot send is a residual rather than the same mechanism.

RM364 — reverse drops what compile carried: shipped files, the table's answer for a row the fill left alone, and a table the module never had

SHIPPED 2026-11-04 on 0.8, uncut — a minor (the 0.8 audit, round 1) · Severity medium · Owner compiler · Principle 7 · Found by the 0.8 four-model audit (class C)

Residuals won't fix — the second lap's warnings lose the resolution provenance reverse discards (authority, placement_witness), so eight examples gain source_row_unused on lap two; carrying provenance into a parquet reverses the documented reverse-discards-provenance decision and is the pm's call · won't fix — a resolution.csv row about a variant the module does not carry has no row in the artifact to ride on, and resolution.csv gets no parquet (SCHEMAS) · won't fix — a not_found sentinel carries no locus to ride resolution_loci, and strict refuses the module that holds one · won't fix — a coordinate-authored row the table files nothing under is still rebuilt from its own cells, so the second lap's table gains a row the first did not hold; telling that null apart from a reproduced one would cost the ensembl_cache digest parity, and the pm decides whether that path is worth keeping

The class. Everything compile_module reads from a spec directory and carries into the artifact or the manifest is either reconstructed by reverse_module, so the next compile reproduces it, or excluded with a reason. Nothing said which was which: RM241 put the spec fields on a registry, and the files and facts beside them were each handled, or not, on their own. The round-trip gates compared what they had been told to compare, so a loss outside that list was green.

Instances, re-verified on 0.8 and found by walking every input, manifest block and resolution path:

  1. compiler/reverse.py:412-413 (on 0.8): reverse copied back the README and logo only. provenance.json (manifest._collect_provenance) and the logs (manifest._collect_logs) are copied into the artifact and hashed into manifest.provenance / manifest.logs by every compile, and the second lap had neither. → reverse.shipped_files(manifest) lists all four kinds; one helper, _copy_shipped_file, copies each byte for byte after a hash check and refuses a name that leaves the module directory, and _discovered asks each kind's own discovery rule (_log_left_behind_reason for a log) before naming a file the next compile would not find.
  2. compiler/reverse.py:659-678 (on 0.8): the positional pass rebuilt resolution.csv from a positional row's own cells. For a row the fill leaves alone (an authored coordinate the table contradicts, a key naming several loci, every row of a module whose build the fill skips) those cells hold the author's coordinate or nothing, so reverse lost the table's row and, for the first shape, wrote the authored coordinate back as a resolution fact: the second lap's positional_identity_contradicted went silent and resolution_signature moved, with strict accepting the module throughout. reference_examples/cpic_gene_pairs had dropped NUDT15's rs1457579126 (CPIC 48040982, Ensembl 48040978 AA>A) to stay green, and RM331's guard (SUBJECT_TABLES == RESOLUTION_SOURCE_TABLES) could not see it, since the table is a subject source.
  3. compiler/reverse.py:630-656 (on 0.8): the weights pass had the same shape on the SNP core: a locus dropped as unable to host the genotype, a one-to-many none of whose loci could host it, an authored coordinate or ref the table contradicts, and every row of a non-GRCh38 module with a table. strict refuses the first three, which is why the round-trip matrix filed them as unstable rather than as defects; a cross-build module it accepts. → for 2 and 3, weights.parquet and the three positional parquets carry resolution_loci (the proxy_loci struct, one helper parquets.resolution_loci shared with it, keyed on the authored key vrs_columns.resolution_key already computes), and reverse emits those loci. The column is null where the row's own cells already rebuild the key's loci exactly (withhold_reproduced_loci), which keeps every clean module's parquets equal to the deprecated ensembl_cache path's (test_digest_parity_and_offline_roundtrip caught the first cut, which filled every row); reverse rebuilds a null row from its cells, as before.
  4. compiler/reverse.py:479 (on 0.8): reverse wrote a resolution.csv for a module whose compile read none, rebuilt from authored coordinates, so the second lap published a resolution_signature, VRS coverage and expansion counts the first did not (grch37_build, mt_heteroplasmy, cyp2d6_structural; recorded as "not a defect" in RM69 and in the corpus sweep). → _no_table_was_read: no signature in the manifest, no resolution.csv in manifest.derived (a header-only table comes back header-only), and no parquet cell its authored_ident does not name, so an older compile or the deprecated ensembl_cache path, which fill without a signature, still gets its table.
  5. compiler/reverse.py _copy_shipped_file, found by review of the first cut: a name check alone follows a symlink, so a downloaded artifact's logs/x.log linked elsewhere would be copied into the reversed spec. → _leaves_through_a_link refuses a link on either side, as compile never ships one.
  6. compiler/tests/test_reference_examples_roundtrip.py: the lap-1 resolution_signature comparison was exempt on a non-GRCh38 build, which hid cyp2c9_warfarin_grch37 (instance 2's third shape, RM69). The exemption is gone.

The mechanism. reverse.REVERSE_MANIFEST_RECONSTRUCTED / REVERSE_MANIFEST_EXCLUDED place every ModuleManifest field and every Compilation field (walked one level down), and test_every_manifest_field_is_reconstructed_or_excluded asserts the walk equals their union, disjoint, each exclusion with a reason. reconstructed_projection(manifest) is what every round-trip gate now compares lap against lap: the corpus sweep (all 22 examples, from the first lap, resolution_signature included) and a fixture carrying every shipped file kind (README, logo, provenance.json, a top-level log, three files under logs/), since the corpus carries no provenance and no logs. The corpus sweep also asserts every manifest.inputs[] and manifest.derived[] name comes back under a legal spelling. test_every_file_the_manifest_names_beside_the_parquets_is_shipped_back derives the file-bearing manifest fields from the model's annotations and asserts shipped_files reads exactly those, bar inputs/derived (files beside the spec). The round-trip matrix's two positional table_says_more cases are now plain fixed points, and five weights-side cases strict refuses are now stable as well (the matrix's contract, unstable implies refused, still holds; only not_found still moves).

Tests. Red on 0.8 first: the two matrix cases (expected a fixed point, but ['resolution_signature'] moved), the every-field fixture (lap two's logs == [], provenance is None). Each mechanism broken once: with_resolution_loci returning the table unchanged fails the two matrix cases, cyp2c9_warfarin_grch37 and the contradicted-row test; weights.parquet's column left null fails 15 matrix cases; _no_table_was_read returning False fails grch37_build, mt_heteroplasmy, cyp2d6_structural and the no-table test; the link guard and the derived read each fail their test. test_build_roundtrip.test_reversed_resolution_csv_carries_the_module_build now injects a table, since the module it built read none.

Not this class, and why. The verification attestation stays excluded (not in the artifact, bound to bytes reverse re-emits; reverse says so). RM69's own record refused a resolution.parquet and four other repairs; resolution_loci is none of them (nothing joined, the row's coordinate and key untouched, the loci on the module's build) and its addendum says so. The enricher's publisher enumerates the same four shipped kinds from raw JSON (upload._declared_files, RM353), deliberately tolerant of a manifest the model rejects, so it keeps its own reader.

RM270 — an indel's artifact key is its source's spelling: a left-aligned VCF misses a respelled row, and the spelling-independent id the enricher mints never reaches the artifact

0.8, decided 2026-11-03. Taken into 0.8 by the maintainer, with the rest of the indel-placement fixes (RM304, RM267, RM270, RM292, RM305). The status line below predates that decision.

Residuals won't fix — an authored coordinate is never rewritten, because it is the row's identity inside content_signature (PT2 §5 C5) · won't fix — a pair row's recorded reference locus keeps the snapshot's spelling, because re-anchoring the snapshot at build is just-dna-pipelines' builder, outside this repository, so a pair authored in the other spelling carries no vrs_id on its parquet row · won't fix — a consumer who cannot mint VRS still joins an authored respelling only by normalizing both sides, which CONSUMING.md says

What shipped (2026-11-04). The build is 3 + 4 with 2's stamped verdict, as decided below, and it carries the residuals four closed items pointed here: RM241's and RM304's (no parquet carried a vrs_id or its version, so a round trip dropped both), RM267's (a respelling it judged same_event was still written in the snapshot's spelling) and RM291's (the two SHOX misses pinned to this item).

  • (4) The per-ALT vrs_id and its vrs_spec on every variant parquet (compiler/vrs_columns.py): weights.parquet as a List(Utf8) parallel to alts, the three positional parquets (pharm_variants, haplotypes, heteroplasmy) as resolution.csv's comma-joined cell, and studies.parquet's proxy_loci struct. Copied from the row's own resolution.csv row (filed under its authored key, vrs_columns.resolution_key, which reverse shares) by allele, never minted by the compiler (P2) and never borrowed from another subject's row for the same spelling: either would reach resolution.csv on reverse and move the second lap's count. An allele its key records with two ids is withheld. annotations.parquet carries variant_key but no allele, and frequencies.parquet's id is gnomAD's, so neither gains one. reverse writes both back, so compile → reverse → compile keeps every id and vrs_alleles_identified. Digest parity with the deprecated DuckDB path now holds when the table records no id.
  • (3) A coordinate enrich fills from an rsID is written left-aligned, ALT by ALT (sequences.left_normalize, normalize_locus), through RM267's own _left_align (@one-normalizer-two-spellings): a substitution by trimming with no read, an indel against the reference window. ALTs landing on two references become two loci, the split bcftools norm -m -any makes, after the hosting filter; the piece the row's genotype names is written (a genotype naming ALTs in both pieces keeps the source locus whole), and each keeps the RM267 verdict of the locus it came from. Undecidable (offline, a non-nucleotide allele) means the locus is written as the link gave it, whole. Under --rederive the drift canary names a respelling apart from a source that moved, by the alleles' unchanged vrs_ids. An authored coordinate is judged and never rewritten: a warning names its leftmost spelling (EnrichmentResult.spelling, findings over checked, unknown apart), and so is a pair's recorded reference locus, which the compiler compares by spelling. A recorded row is respelled only under --rederive (@sidecar-authoritative).
  • (2) The stamped verdict, resolution.csv left_aligned (tri-state, outside resolution_signature). P5: named for the convention it checks, so a future 3′-shifted (HGVS) verdict is its own column rather than a member squeezed in beside it; no collision with vrs_* or placement_*, and no reserved name. Not a verification.json check: it compares a spelling with a convention, not a claim with a witness.
  • The proof: reference_examples/shox_par1 re-derived (enrich --rederive --no-clinvar), so rs1569493663 is X:634689 CAG>C and X:634689 C>CAG, and compiler/tests/test_consumer_join.py passes with its pin removed and the miss set empty.

Tests: compiler/tests/test_vrs_on_parquets.py (both spellings of rs72613567 → one id on the parquet, rs8176719's two placements → two, the hole kept, the contested allele withheld, the round trip) and the RM270 block of enricher/tests/test_placement_witness.py (the filled respelling written left-aligned and compiled to its id, the authored coordinates judged with cells byte-identical, offline unknown, respelled only on --rederive, the pair's locus kept, the SHOX split over the consumer-join fixture's real bases, the piece a genotype names, and a respelling on --rederive named apart from drift). Each was shown red on the branch before the change and each new rule was mutated once.

Severity high · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (a new optional resolution.csv column and four parquets' new columns; PROPOSAL_0_8_PT2 §5 C5) · Owner enricher (resolution fill, vrs.mint_resolution_rows) + compiler (the parquet column) · Motivating case S120

What was confirmed. The three cases S120 cites (rs72613567, rs77944059, rs333 CCR5-Δ32) sit in our Ensembl snapshot one base right of ClinVar's left-aligned spelling, which is also what the callers emit. Against GRCh38 (UCSC hg38; Ensembl REST was down) each pair gives the same haplotype, so they are one event spelled two legal ways. That is RM267's harmless +1 class, not its wrong-event −1 class. Nothing in the contract names a normalization. The compiler cannot apply one either, because left-alignment reads flanking sequence and the compiler has no sequence (P2). So an indel's variant_key is chrom:start:ref:alts in whatever spelling its source used. Compiling reference_examples/hboc_palb2 keys rs1555461597 as 16:23635706:G:GT.

The identity that would join them already exists and is dropped. The enricher mints each indel's vrs_id over the fully justified allele. Probed: both spellings of rs72613567 mint ga4gh:VA.Jml7SNku3QQBCVIj78BGiFvR21bNkos7, and both of rs77944059 mint ga4gh:VA.ks2GTWYOW0aKfGbJ2aeQUOZxOT_xC2ts. S117's rs8176719 pair mints two different ids, so the id also tells RM267's wrong event apart from a respelling instead of masking it. That id lives in resolution.csv, which has no parquet by design. Of the compiled parquets only frequencies.parquet carries a vrs_id, and that one is gnomAD's. @dont-discard-computed.

Candidate repairs, and why each is wrong or partial.

  1. Compiler left-normalizes and stamps a field (the reporter's preferred option). Refused twice. It needs reference sequence in the compile path, the line COMPILER.md § the VRS verify pass says not to cross (P2). And on an authored coordinate it rewrites a value reverse_module then re-emits, so lap 1 moves content_signature (P7).
  2. An authored coordinate_normalization key. It is a claim no offline tier can check. It costs the full authored price (P9) and would be believed by exactly the consumer it misleads. As a verdict the enricher stamps (tri-state: checked left-aligned / not / unknown), it is honest and minor-legal, and it is part of the answer.
  3. The enricher left-normalizes the coordinates it fills. Legal: a resolution fill is outside content_signature (@rm43-positional-fill). It fixes the +1 class for rsID-authored rows. It does not reach an authored coordinate. For those the enricher reports the normalized spelling as a finding and never rewrites the cell (@enrichment-is-validation). @sidecar-authoritative: it reaches an existing table only on --rederive.
  4. Carry the per-ALT vrs_id onto the variant parquets. A parquet column is approximately free (P9) and it is already computed. It gives a consumer who can mint VRS from its VCF a key that does not depend on spelling. Alone it is not enough, because minting an indel needs sequence access the consumer may not have. Hence it pairs with 3.

The build is 3 + 4, plus the stamped verdict from 2. The part that ships without a decision, the consumer guide stating that no normalization is guaranteed, landed with the S120 reply.

Carries RM241's residual. RM241 (shipped on 0.8) left a round trip that drops every vrs_id, because no variant parquet carries one. Candidate 4 below, the per-ALT vrs_id on the variant parquets, is what closes it.

Pinned by RM291 (2026-09-27). compiler/tests/test_consumer_join.py joins every reference example against a bcftools-normalized ClinVar slice, and the two SHOX rows Ensembl spells at X:634690 (AGAG>AG, AGAG>AGAGAG; ClinVar and callers write X:634689) are its expected misses, pinned to this item. Shipping this empties that set, and the test fails until the pin is removed.

RM331 — a study measured on an LD proxy cannot say so, and filing it under the lead checks the proxy's allele against the lead's

Built on 0.8, 2026-11-04: proxy_rsid and the allele check. StudyRow.proxy_rsid (refused on a row naming no variant, or equal to its own rsid) reaches studies.parquet and reverse; _check_study_effect_alleles reads the proxy's resolved alleles when one is stated and withholds when it has none; enrich.collect_subjects admits each proxy as a subject, last, and the GWAS pass leaves them out. The computed pair followed the same day (below).

Cut 2026-11-04 by the maintainer, after the final measuring run (probes/LONGEVITYMAP_V2_SHAPE_AUDIT.md §3): authors write only proxy_rsid. r² has no meaning without its population, so r² and its population are a pair, and the pair is computed: the enricher asks an LD reference for the r² between proxy and lead in the study's own ancestry and writes it to a machine-written table (half price). The allele check runs against the proxy's alleles.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 D3) · Owner format + compiler (_check_study_effect_alleles) · Motivating case longevitymap v2 requirements §6.2 (rsid, ld_proxy_of), §6.4 (APOE proxies) · for longevitymap v2 · related RM91

What was confirmed. The plan scores lead variants only and records proxies "on study rows". But StudyRow has no flags, so there is nowhere to write that. A study of a proxy then has two homes, and both are wrong:

  • Under the lead's rsID, _check_study_effect_alleles checks the proxy's effect_allele against the lead's alleles. It refuses if they differ and passes silently, with the wrong meaning, if they happen to match.
  • Under the proxy's rsID, it raises study_variant_orphan.

The APOE region alone has five proxies (rs2075650, rs4420638, rs769449, rs405509, rs449647), and rs2075650 is the one genome-wide hit in the Sebastiani 2012 classifier.

Shape. A proxy column pair on StudyRow (the measured variant and its r², plus the LD reference population), with effect_allele checked against the proxy's alleles rather than the lead's. Full ×2–3.

Built 2026-11-04 on 0.8 (build/RM331): the computed pair. just-dna-enricher ld-pairs <spec> asks Ensembl REST's pairwise LD (PT2 §4 question 4) for r² and |D′| between each study row's proxy_rsid and its lead, in the 1000 Genomes phase 3 superpopulation the row's one ancestry code names, and writes the derived table ld_pairs.csv (LdPairRow, key (proxy_rsid, variant_key, ld_population); ld_population is the panel's own name, 1000GENOMES:phase_3:EUR). status (closed, VALID_LD_PAIR_STATUS) carries the reason whenever r² is withheld: not_reported for Ensembl's 200 [] (below its floor or not in LD, never r² = 0), rsid_unknown for its 400, ancestry_mixed / ancestry_unstated for a study naming several superpopulations or none (the pm's setting: no panel is picked; the row is written, against PT2 D3's "no row and counted", per the build brief), and lead_has_no_rsid for a coordinate-authored lead with no rsID. answered_rsid records a merged proxy's current id; dataset is the release read in band (ensembl_116). The (ensembl, ld_pair) licence row commits inside the table's write, only on a run Ensembl answered. It compiles to ld_pairs.parquet with a manifest.ld_pairs block, and reverse writes it back (P7, tested on the real paths). The hand-run calls are probes/LANES_0_8.md § 6.

Fixed the same day: the author's half did not survive a reverse (P7). The proxy's resolution.csv row reached no parquet, so reverse_module (which rebuilds that table from parquets) dropped it: lap 2's resolution_signature moved and the proxy allele check went silent (found by the examples builder, test_reference_example_round_trips_to_a_fixed_point). studies.parquet now carries the proxy's resolved loci (proxy_loci, compiler-filled) and reverse re-emits them, last. The class was checked, not only the instance: of the five tables collect_subjects draws subjects from (variants, pharm_variants, haplotypes, heteroplasmy, studies), studies.csv was the only one reverse did not rebuild from; meta.csv members are asked of dbSNP but never resolved, so they write no row. A test now holds enrich.subjects.SUBJECT_TABLES (walked from every Subject(...) origin) equal to reverse.RESOLUTION_SOURCE_TABLES.

Residuals none

RM267 — the Ensembl snapshot anchors a class of insertions one base early, and resolution.csv serves them as a different event

0.8, decided 2026-11-03. Taken into 0.8 by the maintainer, with the rest of the indel-placement fixes (RM304, RM267, RM270, RM292, RM305). The status line below predates that decision.

Residuals RM270 · won't fix — re-anchoring the snapshot at build is just-dna-pipelines' builder, outside this repository (candidate 1 below) · won't fix — writing a corrected spelling was refused for 0.8 by PROPOSAL_0_8_PT2 §4 question 3

What shipped (2026-11-04). Candidate 4 as S121's addendum generalised it, in placement.py, run by enrich() after every link and before the table is assembled:

  • Every rsID the run placed fresh is compared with the ClinVar snapshot and ClinVar-GKM where either is located (--clinvar-gkm-cache; read locally, never downloaded by enrich). Per allele, the witness's counterparts are its alleles for that rsID on the same contig, within the left-align window, of the same kind (an indel of the same length, or a substitution to the same bases). A counterpart is the same event when the spellings are identical, when two substitutions trim to one spelling, when both mint one VRS id, or when both left-align to one spelling; otherwise undecided, counted. ClinVar-GKM's ids are VRS 2.1.1 against our 2.0, so its VCF spelling is minted here rather than its id compared.
  • A disagreement withholds the locus holding the disputed allele and names both placements; an undisputed locus of the same rsID is still written. An rsID left with none is unresolved, with no not_found row, and the strict sentence names the disagreement; a pair row keeps its authored coordinate; an overrides.csv answer on the subject clears the unresolved state. Nothing is rewritten.
  • Every witness a written row names writes its SourceRow at the resolution layer, and the compiler's orphan check counts placement_witness members as used.
  • A different allele is unplaced, never a disagreement, and the rsIDs with no counterpart anywhere are the published one-witness count (@tautology-zero). A ClinVar fill has no independent witness here.
  • The witness is recorded on the row: placement_witness (who was asked) and placement_verdict (same_event only when every ALT was placed the same / undecided / unplaced), two columns because who and what are two axes (P5), both outside resolution_signature. No different_event member: that row is never written.
  • It attests as placement_agreement (checked side reporting_source, witness clinvar+clinvar_gkm, undecided counted, the one-witness count in detail).
  • Merge-not-clobber holds: a recorded row meets the comparison only under --rederive, where a disputed subject counts as answered and its old placement is not carried forward.

Tests (enricher/tests/test_placement_witness.py) run the real chain over recorded GRCh38 windows served to the run's own SequenceProxy, so every id is minted by ga4gh.vrs offline; the windows reproduce the ids RM270 and ClinVar-GKM recorded for rs72613567 and rs77944059, and rs8176719's pair mints two.

What the real witnesses hold (measured 2026-11-04). Probed 2026-11-04 on real data: neither loaded witness holds rs8176719 (ClinVar's 2026-06-27 VCF has no record at 9:133257510–529 and no RS=8176719; ClinVar-GKM lacks it, RM305), so against today's witnesses S117's own case is counted in the one-witness class and named in detail, not withheld. The spelling 9:133257521 T>TC is dbSNP's and Ensembl REST's; the tests supply it as a ClinVar row to exercise the withhold. An enrich of a four-rsID module against this machine's real Ensembl and ClinVar snapshots wrote rs72613567, rs77944059 and rs4988235 as same_event and rs8176719 as unplaced. A witness that holds it is the live REST rung (candidate 4's original "else REST"), which the 0.8 contract's "two loaded authorities" left out; it was built the same day (below).

2026-11-04: Ensembl REST is the third witness, online only (the lead's call under the default offered to the maintainer that day; it replaces the won't-fix residual "a live Ensembl REST witness is outside PT2 §5 C4's two loaded authorities"). For an rsID the Ensembl snapshot placed, with an allele that is not a substitution, and that neither ClinVar nor ClinVar-GKM holds, an online run asks the live REST rung through the run's resolver (RM268's anchored path) and compares by the same ladder, so S117's own rs8176719 is now withheld against the real witnesses: REST answered -/C at start 133257522, end 133257521 by hand on 2026-11-04 (17:33Z, after 503s and timeouts from 17:26Z), which anchors to 9:133257521 T>TC and mints a different id from the snapshot's 9:133257520 G>GC. The witness is named ensembl, the licensed source placement_witness joins sources.csv on (an ensembl_rest key would have no terms row and warn as an unaccounted source on every module). REST and the snapshot are one authority, so by RM292's rule the comparison is self-consistent, not independent: the record names its checked side ensembl once REST answered (verification.ran(reported_by=)), so independence derives self_consistent for REST alone and withholds beside ClinVar, and an rsID only REST agreed with stays in the one-witness count with its own sentence in detail. That keeps the comparison's value for S117's class, the dump disagreeing with Ensembl's own REST mapping, while saying it cannot catch an error both surfaces share. Unanswered after retries (the REST leg now retries a 5xx and a 429) or unanchorable is not asked, counted in detail, never agreement; --offline asks nothing; answers are never journalled. Tests in enricher/tests/test_placement_witness.py (recorded REST answers for rs8176719 and rs77944059, one live test under JUST_DNA_NETWORK_TESTS=1), each arm mutated once.

2026-11-04: an injected resolver without resolve_rsid_rest leaves REST not asked, never a crash. The witness above called the new method on whatever resolver the host injected, so a resolver written against 0.7 (just-dna-marketplace's test fake is one) raised AttributeError at the first eligible indel. enrich(resolver=) now requires ensembl.RsidResolver (resolve_rsid) and asks the optional ensembl.RestWitness capability only where it exists; otherwise every eligible rsID is not asked, counted, with PlacementCheck.not_asked_reason in detail and one warning. Hunted across enrich's other injected collaborators (gnomAD, GRCh37, the release probes): each calls only its parameter's original contract. Test red before, the reason's wiring mutated once.

2026-11-04: the retired beta GraphQL leg is no longer asked. resolve_rsid POSTed to beta.ensembl.org/api/graphql/variation before every REST request. Probed by hand (19:19Z): 301 to www.ensembl.org, where the query no longer validates (HTTP 400) and a bare rsID is VARIANT_ID_NOT_FOUND. Removed with its settings and dead tests; resolve_rsid is REST alone. ensembl-graphql stays a readable source value. Every other client endpoint was probed once that day, redirects unfollowed: only GenCC's bulk download answered 301 (search.thegencc.org → thegencc.org), and its default now names the new host; ClinPGx's 303 to S3 and ClinVar-GKM's directory 302 are hops to files that answer 200.

2026-11-04: the REST rung is paced and honours Retry-After. Neither existed on it (the review of the REST witness reported both). EnsemblResolver holds a PacingGate (0.1 s, Ensembl's 15 req/s) waited once per attempt; a retried 5xx or 429 waits at least the answer's Retry-After (net.wait_retry_after, the first in the tier), and one past net.RETRY_AFTER_CEILING is not retried and holds every later request until it passes. Tests on a fake clock, each arm mutated once.

Severity high · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (two optional resolution.csv columns and a new check; PROPOSAL_0_8_PT2 §5 C4) · Owner enricher (the resolver chain's snapshot link), with the upstream half in just-dna-pipelines · Motivating case S117

What was confirmed. lookup_loci against the local snapshot returns rs8176719 (ABO O1, MAF 0.34) as 9:133257520 G>GC. GRCh38 reads GGGG T ACC at 517–524, so that spelling is the haplotype GGGGCTACC and ClinVar/dbSNP's 521 T>TC is GGGGTCACC: two events, not one respelled. Both of the report's other −1 examples reproduce the same way against the reference (rs546596010: CCATTCC vs CCTATCC; rs1553364018: GTCCCC vs GCTCCCC).

The mechanism, and where it lives. The snapshot is faithful: Ensembl's own current VCF dump (homo_sapiens-chr9.vcf.gz, read by remote bcftools) carries 133257520 rs8176719 G GC. Ensembl's REST mapping for the same rsID disagrees with its VCF and agrees with ClinVar — start 133257522, end 133257521, -/C, an insertion between 521 and 522, which VCF-anchors at 521 T>TC. Across seven insertions (the two cited plus five sampled from the −1 class on chr3/5/12/16) the dump's POS is REST end − 1 every time, and REST end is ClinVar's POS every time. So the dump anchors a class of insertions one base left of Ensembl's own interbase point: invisible inside a run of the anchor base, a different event outside one. @two-surfaces-two-denominators applies to Ensembl against itself.

Why no check here sees it. The wrong anchor base is a real genome base, so sequences.verify_reference_alleles passes it by construction. check_rsid_coordinates calls every indel position difference undecided (RM31: an indel re-anchors legitimately). And for an rsID-only row _verify never runs. A module resolving rs8176719 through the table therefore compiles green and matches no sample.

Why each candidate repair is wrong alone.

  1. Re-anchor at snapshot build. Correct, and it is just-dna-pipelines' build, not this tier's (CACHE_LANES["ensembl"].unbuilt). It also leaves every deployed snapshot wrong until rebuilt.
  2. Left-normalize in resolve_variants (the reporter's first candidate). It fixes the +1 class, which is harmless respelling one base right of VCF left-normalization. It cannot fix the −1 class: G>GC after GGGG has no left-shift room, so it normalizes to itself and stays the wrong event.
  3. Re-derive insertions from REST. Right values, but it turns a bulk snapshot into one request per insertion rsID, and REST's rung has its own defect (RM268) to fix first.
  4. A finding that withholds (the reporter's second candidate): for each insertion the snapshot resolves, compare against a second placement the enricher holds (the ClinVar snapshot on rsID, else REST). Apply both spellings to the reference window, report a different haplotype, and withhold the row rather than choosing. It reports without repairing (@enrichment-is-validation) and is the part that fits here. What it does not settle is whether the enricher may then write the corrected spelling. Under @provenance-beside-a-claim-is-outside-content-identity a rewritten snapshot value should say so on its row, which is a new optional resolution.csv column. That column is minor-legal, and it is why this item is sized as a minor, not a patch.

content_signature is unaffected either way (a resolution fill is authored_ident, @rm43-positional-fill). @sidecar-authoritative applies: a corrected spelling reaches an existing resolution.csv only on --rederive or a deleted sidecar, so the release that ships it must say so. Measured scale (the reporter's join, not re-run here): 5,788 insertion and 2,111 deletion alleles in the −1 class, of which roughly three in four of the sampled insertions are a different event.

Addendum 2026-09-27, S121: candidate 4 is the general rule, not an Ensembl special case. Confirmed in code: the ClinVar link (enrich.py, the "ClinVar cache link" block) fills only what the Ensembl cache missed. The same run already holds the ClinVar snapshot for the clin_sig cross-check, yet it never compares a placement. The comment gives the reason for that order as "so no compiled module's artifact.digest moves", which is the one reason the house rules say is never enough on its own. So every coordinate in resolution.csv has one witness, and authority=ensembl reads the same whether a second authority agreed, disagreed, or was never asked. The build is therefore:

  • Compare every placement two loaded authorities give for one rsID, and withhold on disagreement. Compare by minted vrs_id where both sides can be minted, because it needs no tolerance. Probed for RM270: a respelling mints one id (rs72613567, rs77944059) and S117's wrong event mints two (rs8176719). Elsewhere, use parsimony_reduce plus a reference window. A disagreement is a finding naming both placements, and the row is not written. The count of rsIDs that had only one witness is published beside it (@tautology-zero).
  • Record the witness on the row. A new optional resolution.csv column saying which second authority was asked and what it answered, tri-state. This is the minor-legal addition this item was already sized for.
  • S121's third ask is inverted, not adopted. The VRS id is the arbiter, not the hazard: the three rows S121 cites mint the same id as ClinVar's spelling, so their ids are correct. A −1-class row is withheld whole, id included, by the first bullet.

This is the same failure @start-1based recorded on 2026-08-06 ("validate-by-redundancy assumes independence"), and the RM31 residual (0.5) that went unfiled. The postmortem of the 2026-09-27 round covers the procedure side.

RM359 — under --strict, study_effect_allele_not_at_locus arrives as both an error and a warning, and SCHEMAS.md states a count the code has outgrown

0.8, filed 2026-11-04 by the lead as a second-pass item: found by a 0.8 builder.

Severity low · Status SHIPPED 2026-11-04 on 0.8, uncut — a minor · Owner compiler (allele_checks.py) + docs (SCHEMAS.md) · Motivating case a 0.8 builder's report, 2026-11-04 · related @no-rerun-with-counts, @registry-completeness

Two instances of one class: a fact stated where it can disagree with itself.

  1. A finding on two channels at once. Under --strict, study_effect_allele_not_at_locus is escalated into errors and still emitted into warnings, so a consumer counting findings counts it twice and one reading of the result contradicts the other.
  2. A count stated in prose. SCHEMAS.md says authoring_reference()["vocabularies"] has "21 entries today". It has 38 on main (measured) and the builder counted 43 on 0.8.

The fix, as one rule. A finding lives on exactly one channel, the one its severity under the mode picks, and a test asserts no code appears in both lists. The prose drops the number and states the rule that generates the list (@registry-completeness: never a count in prose).

Shipped 2026-11-04 on 0.8. Instance 1, the class: a mode-ladder finding under strict is in errors and nowhere else. Two routes put it in both, and both are closed. compile_module ran its pre-flight in best_effort whatever its own mode, so it seeded warnings with every ladder sentence; it now runs the pre-flight in its own mode, so a strict compile refuses with validate --strict's accumulated errors for every check the pre-flight asks (the deprecated ensembl_cache path is told apart, because the pre-flight cannot see what that reference places). Unchanged by this item, and under the standing resolved-rows exemption: validate --strict still reports valid where compile --strict refuses on the two resolution ladders that read resolved rows (locus_cannot_host_genotype, rsid_coordinate_disagrees); the test pins them as compile-only so the day the pre-flight asks them it says so. ResolutionOutcome.warnings carried each resolution ladder's warning in both modes; ResolutionOutcome.channels(strict=) now routes them through route, and its docstring no longer says the refusal is published "beside" the warning. compiler/tests/test_one_channel_under_strict.py asserts the rule over every code the LadderFinding walk finds plus symbolic_allele_unusable (which the walk cannot see); all eight cases were red on 0.8 before the change. Kept out of the rule on purpose: the strict-only aggregates (strict compile: N variant(s) …, build_disagreement_error) are different findings from the per-subject warnings that fire in both modes, and the enricher escalates by raising. @one-finding-one-channel.

Instance 2, the class: a count in prose with nothing re-deriving it. SCHEMAS.md's "21 entries today" (47 on the 0.8 tip) is gone, and so is every registry total the sweep found in the maintained references beside entries / codes / tables / table kinds / lanes / parquets / kinds / checks: ladder.py's and mode_ladder.feature's "seven" ladder codes, the nine table kinds (six sites), the four binning and PGx kinds (eight sites), COMPILER.md's "six fact tables" (thirteen), "all nine" overridable tables (twelve) and "seven merged tables" (ten), ENRICHER.md's "five lanes" not published (the enumeration also missed opentargets), the per-command check counts, cpic_build's "five parquets", "eight finding kinds", "four other tables" with a source column (two sites), a parametrized test's "four checks", and SCHEMAS.md's "eight siblings" of resolution.csv (thirteen). test_counted_prose.py keeps the two generated-roster paragraphs free of a total; the counts it already pins (ARTIFACT_PARQUETS, OVERRIDABLE_TABLES, _FACT_TABLES, the hash family) stay pinned. Left as written, being dated or designed rather than registry totals: ROADMAP / INTEGRATION_0_7 / POSTMORTEM / AGENT_NOTES narratives, closed-vocabulary member counts (state's six), measurements, and headings.

Residuals none

RM357 — the authored tables that are not table kinds have no registry: three copies of one loader, and a refused meta.csv reports its citations as uncited

0.8, filed 2026-11-04 by the lead as a second-pass item: found by a 0.8 builder.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor · Owner compiler (load_meta, load_model_organisms, load_overlay and the lists that name them) · Motivating case a 0.8 builder's report, 2026-11-04 · related RM335, RM28, @registry-completeness, @overlay-not-inside

One class: a category of table with no registry. meta.csv (RM28, compiler/meta.py on 0.8), model_organisms.csv (RM335, compiler/model_organisms.py on build/RM335) and overrides.csv (load_overlay) are authored tables outside the table-kind registry. Each has its own copy of one loader body, and about ten hand-kept lists say which of them cites literature, names a gene or is a lead table. A fourth such table means another copy and ten more edits, and a list that misses one fails silently.

The instance that misleads an author. load_meta drops all its rows on a duplicate-key error. In the same run, a literature.csv row cited only by meta.csv is then reported as uncited, which points the author at literature.csv when the defect is in meta.csv.

The fix, as one rule. One registry of authored non-kind tables, each entry carrying its loader and its citing, gene and lead flags; every list is derived from it and a test asserts equality over the walked set. A loader that refuses still hands its parsed rows to the other checks, so one table's error never becomes another table's finding.

What shipped. tables.AUTHORED_NON_KIND_TABLES (public, entries of NonKindTable) registers the three tables in ARTIFACT_PARQUETS order: CSV name, parquets (the first carries every authored cell and is what reverse reads), row model and row_checks (the overlay's overlay_coherence_errors). The entry asked for citing, gene and lead flags; none is declared. Whether an entry cites is read off its model (pmid). "Not a lead table" is membership itself, and so is "its gene is not the module's" (manifest.stats.genes reads variants.csv and the kinds only, and the enricher's scope follows it by excluding every registered table); a declared gene flag could only ever be False, since module_stats would not read a True one. Every entry is draftable. One loader, load.load_authored_table(spec_dir, csv_name), replaces the three bodies: compiler/model_organisms.py is gone, meta.load_meta is gone, and load_overlay stays public (the enricher calls it) as that loader on overrides.csv. validate_spec and compile_module each load all three once, in one loop over the registry. A refused table keeps its rows for the citing view: all of them on a duplicate key or a row_checks error; on a parse error the rows that parsed, only for a table that cites (the overlay applied half-parsed would raise findings against the tables it corrects, which a review of this build reproduced). A refused meta.csv is not expanded, so its findings stay the refusal.

The lists now derived from the registry: tables._INPUT_FILES, tables.ARTIFACT_PARQUETS, tables.table_bindings(), tables._TABLE_DUPE_KEYS, load.spec_tables' roster (so content_signature), binning_checks._CITING_TABLE_KINDS (so load_citing_rows and table_citations), table_checks._KNOWN_SPEC_FILES, the citing view in validate_spec (citing_kinds/citing_survivors) and in compile_module (citing_rows), reverse_module's three write-backs (one loop), draft.DRAFTABLE (so the describe/template/requirements/stub/hint dispatch and the enricher's identifiers._id_bearing_tables and litvar rosters), and the enricher's gene_metrics._NOT_THE_MODULES_GENES. The format tier cannot import the compiler, so its three reference groups became one declared group, reference._AUTHORED_NON_KIND_MODELS, asserted equal to the registry's models. Left as they were: the compile's write sites (meta.csv builds two derived frames, the other two go through _build_table), and the enricher's subjects.meta_member_rsids, which reads meta.csv for the rsIDs its members name and refuses on a parse error only.

Tests: compiler/tests/test_authored_non_kind_tables.py (the registry against the format tier's model walk, the input files, DRAFTABLE, the artifact listing, LEAD_PARQUETS and the gene facet; the one loader's absent and empty arms; a module carrying all three tables round-trips to the same digest and signature); a malformed overlay is not applied; test_meta_compile.py's two RM357 tests (the duplicate-key case, red before; the parse-error case, red before). Broken once each, and a test went red: the loader's two arms, the reverse loop, _INPUT_FILES, DRAFTABLE, table_bindings(), _TABLE_DUPE_KEYS, _CITING_TABLE_KINDS, _KNOWN_SPEC_FILES and the reference group. The 16 reference examples and the meta, model-organism and overlay fixtures give identical validate and compile warnings and errors, digests, artifact.files, signatures and reversed files before and after.

Residuals none

RM356 — a named-allele row's identity key omits gene, so two genes' *2 defined by the same variant are one duplicate

0.8, filed 2026-11-04 by the lead as a second-pass item: found by a 0.8 builder alongside RM351.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor · Owner format (pgx.py _KEY_FIELDS) + compiler (the dedup sites that read it) · Motivating case a 0.8 builder's report, 2026-11-04: the UGT1A genes share their exons 2–5, so two genes' *2 can be defined by the same variant and allele · related RM351, @absent-is-not-different

One class: an identity or dedup key that names an allele without its gene. HaplotypeRow._KEY_FIELDS is ("haplotype_name", "variant_key", "allele"). A UGT1A1 *2 row and a UGT1A6 *2 row on the same shared-exon variant and allele are then the same row, and the duplicate check refuses the second. RM351 found the same shape in the cross-table checks, which key a named allele on its bare name; AlleleFunctionRow already keys (gene, allele). Grep for the class, not the instance: every _KEY_FIELDS and every dedup or merge key in the three tiers that carries an allele name and no gene.

The P3 question the fix answers first. Adding gene to a key narrows what counts as a duplicate: a pair that is refused today becomes legal, nothing legal today is refused, so the change is additive. But gene is optional on HaplotypeRow, so two rows split on it only when both state it and the values differ (@absent-is-not-different); a row with no gene still collides with one that has it, and the check narrows rather than the key splitting on an absence. The merge identity drafting uses moves with the key, so a module drafted before the change must re-draft to the same rows (a lap test).

What shipped. gene joins the identity as a declared split, not as a _KEY_FIELDS member. A tuple member would have read an absent gene as a distinct value, and the relation the entry asks for is not transitive (a gene-less *2 collides with UGT1A1's and with UGT1A6's, which do not collide with each other), so no hashable key can carry it.

  • HaplotypeRow._KEY_DISTINCT_WHEN_STATED = ("gene",) (schema pgx.py): columns that split two rows sharing _KEY_FIELDS only when both state them and the stated values differ. _KEY_FIELDS is unchanged.
  • compiler.tables.same_row(row, earlier): the one predicate, comparing a stated gene through RM351's _gene_key (moved here from table_checks.py, so both items compare a gene one way). Asked by the compile/validate refusal (_validate_table_kind, bucketed by the key), by draft.append_rows (so a second gene's drafted row is added, and a re-draft over its own rows reports every row already_present) and by the hints lint (_check_duplicate_keys). The refusal text is byte-identical and still prints the three-member key.
  • hints.TableKey.distinct_when_stated (and describe_table(...)["key"]) publishes the column beside columns; a walking test over reference._ALL_MODELS pins that every declared column is an optional authored field outside _KEY_FIELDS.
  • Recompile stability: the four reference examples with haplotypes.csv compile to the same artifact.digest and content_signature with and without the declaration (a test, on one toolchain), and all six PGx examples matched a pre-change compile byte for byte.

The class survey found no second instance. AlleleFunctionRow keys (gene, allele), DiplotypeRow keys on gene, the CPIC provider's match_on is (gene, allele), the enricher's function cross-check keys (row.gene, row.allele), drug_labels subjects carry the gene, RM351 re-keyed the cross-table checks, the meta-table's member tables do not include haplotypes, and haplotypes.csv is no overlay target. Read and left alone: enrich/subjects.py builds a resolution subject from a haplotype row's position (a variant-level fact, which the gene does not change), and allele_checks.py labels a symbolic-allele finding with the bare haplotype_name when a row has no variant_key (a message label, not a key). Tests: compiler/tests/test_haplotype_key_gene.py (six arrangements through validate, compile, drafting and the lint, the non-transitive case, the lap test, a round trip, the walking test, digest stability); one scenario in features/compiler/licensing_closure_pgx.feature.

Residuals none

RM333 — the effector gene behind a GWAS locus has no source and no column

Placement settled 2026-11-04. The effector-confidence label is never authored (RM323's cut). This lane's derived table is one of its inputs, beside coloc and the coding consequence.

Licence probed 2026-11-04 (all claims checked at the source); decided by the maintainer: build, under Open Targets' own terms plus its notice.

What the probe found:

  • L2G now lives in the Platform: release 26.09, dataset l2g_prediction, on EBI's FTP. There is no Hugging Face copy.
  • The release is marked CC0 1.0 (the licence page, and the croissant's only license key).
  • The terms of use add "no additional restrictions … other than those provided by the original data owners" and a third-party-rights disclaimer.

The SourceRow therefore records commercial_use=True, share_alike=False, redistribution=True, and notice carries that disclaimer verbatim.

For a lawyer, named and not settled:

  • "marked with" CC0 against "dedicates", for data Open Targets did not wholly author;
  • whether "all Open Targets users" reaches a module's buyer;
  • whether the CC BY-SA 3.0 of ChEMBL and HPA, as training inputs, reaches the scores;
  • whether a CC0 mark satisfies the CC BY 4.0 attribution owed to eQTL Catalogue and GTEx;
  • FinnGen's terms, unstated at its source;
  • the 26.09 inputs missing from Open Targets' licence table;
  • PanelApp's "commercial use for Open Targets".

For 0.9: the host licence defers to the original owners, and an L2G row cannot name its owner (@a-hosts-terms-are-not-its-contents-terms assumes a record can override). That is a SourceRow axis gap, filed as RM345 with AlphaGenome's four (probes/ALPHAGENOME_ATLAS.md §2.6).

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 D2) · Owner enricher (a new lane) + format (a derived table's columns) · Motivating case longevitymap v2 requirements §4.2 (causal and effector confidence, R-CAUSAL) · for longevitymap v2 · related RM239, RM238, RM236

Need. v2 names a gene only at effector confidence E1/E2, using Open Targets locus-to-gene (L2G) scores and coloc. VariantRow.gene is a symbol with no provenance, so nothing tells a nearest gene from an effector call. RM239 covers the fine-mapping posterior on gwas_effects.csv, RM238 the per-tissue eQTL (parked), and RM236 the coding consequence that C1/E1 key on. No item covers L2G, and no lane reads Open Targets.

Shape. An Open Targets snapshot lane, walked through CACHE_SURFACE.md's checklist, licence probed first (not verified here). Effector gene, score, method and release on a derived table (half cost). The C1–C4 / E1–E4 labels are the module's rubric over those inputs, so they are computed once the inputs exist, never authored.

Built 2026-11-04 on 0.8 (build/RM333). The lane opentargets (opentargets build, opentargets_build.py) mirrors release 26.09 from EBI's FTP over https and flattens it; opentargets enrich (opentargets.py) fills locus_to_gene.csv at Open Targets' own grain, one row per (study locus, gene) a module variant leads, and colocalisations.csv at the source's (left, right) study-locus grain, the sibling the probe chose: one (study locus, gene) pair colocalises with up to 1,738 right-hand loci (2,308,572 of 10,326,986 pairs have more than one), so h4/clpp on the L2G row would have picked a tissue. Several study loci per variant are kept. The SourceRow is OPENTARGETS_TERMS (CC0-1.0, commercial_use=True, share_alike=False, redistribution=True, notice = Data Services items 2 and 4 of the terms of use, verbatim). No C or E label is computed. The hand-run build and its counts are probes/LANES_0_8.md § 5. The lead-only predicate is the contract's and it is narrow: measured over the whole release, rs1800562 sits in 82 GWAS credible sets and leads none, rs646776 leads 205 of 2,061; a members-wide L2G table would need variant_key in its key, a decision left to the pm.

Addendum 2026-11-04 — grain widened to members (pm, on the lead's measurement, decided on main after this entry shipped). locus_to_gene.csv covers every study locus a module variant is a member of, not only the ones it leads. Measured on the full 26.09 build: rs1800562 (HFE C282Y) sits in 82 credible sets and leads none, and rs646776 leads 205 of the 2,061 it is in. A lead-only table is empty for an HFE module, so it fails the case the lane exists for. variant_key joins the key (study_locus_id, gene_id, variant_key) and means the module variant asked about. lead_variant_id still names the source's lead, and the member's weight is its posterior on gwas_effects.csv (RM239). The cost is one row per member variant and no new column, in a machine-written table. colocalisations.csv takes the same rule if it is lead-only too. Chosen over two alternatives: lead-only, which fails HFE, and a study_locus_id column on gwas_effects.csv, which adds a column.

Members, not lead-only: built 2026-11-04 on 0.8 (build/RM333-members), on the addendum above. opentargets enrich now writes the L2G and coloc rows of every GWAS credible set a module variant is a member of, read off credible_set_members, which the snapshot already held for the posterior. LocusToGeneRow is keyed (study_locus_id, gene_id, variant_key) and ColocalisationRow (study_locus_id, right_study_locus_id, variant_key), since coloc was lead-only too; both models are new in 0.8 and unreleased, so re-keying them breaks no reader. No new column: lead_variant_id still names the source's lead and now names another variant whenever the module's is a member only. Over the whole release no GWAS set's lead is missing from its own member list, so the member-wide table holds every lead-only row. On the HFE example C282Y now gets 121 L2G rows over its 82 sets and 13 coloc rows (it had none). Measured against the full snapshot, rs646776 gets 6,182 L2G rows over its 2,061 sets (615 over 205 lead-only) and 309,634 coloc rows (29,885 lead-only), so a module with a heavily fine-mapped variant now carries a coloc table in the hundreds of thousands of rows. The overlay stays keyed (study_locus_id, gene_id) / (study_locus_id, right_study_locus_id): a score is the set's fact whichever member asked, so an update reaches every member's row of the pair. Because variant_key is now a key column the overlay does not key on, an update of it is refused (it would give several rows one key), and an insert matches on the variant_key it supplies, so it can add a second member's row to a pair; a suppress still removes every member's row of the pair and cannot withdraw one member's, and the overlay alone cannot insert two members of one pair, since two insert rows of one field share the overlay's own key (table, subject, member, field). The arm that withholds two module keys on one release allele is kept, renamed shared_allele_keys (it was lead_key_ambiguous, unreleased) and computed over every allele rather than only those in a set; its old reason, a key collision, no longer holds under the wider key, and it now rests on one allele stated under two keys being a module defect to name. subset_snapshot cuts member loci, and the committed slice was recut from the full build with one more allele, 6_26072764_C_T, a member of all 82 of C282Y's sets, so two module variants share study loci in a test.

A row with no ALT: built 2026-11-04 on 0.8 (build/RM333-noalt), on the maintainer's "build the recommendation". opentargets enrich skipped a resolution.csv row whose alts is empty, silently, so apoe_epsilon's rs429358 and rs7412 got no row in any table. It now reads every allele the release holds at the row's (chrom, start) and each one's rsIds, which the builder keeps as variants.parquet's rs_ids (the snapshot grows from 5,419.5 to 5,457.3 MB, inside the lane's declared 5,500). One allele carrying the row's rsID (or its rsid_current) on the row's REF supplies the ALT for all four tables and the key is named in allele_supplied; several candidates, a carrier on another REF, or a row whose rsID is the back-fill's pick (status="ambiguous") are withheld and named (allele_unstated_withheld); none is the ordinary not-in-release answer; a row with no rsID either is withheld (allele_unstated_no_rsid). One departure from the decision's letter: an allele whose rsIds is empty counts as a candidate, not as a no. At 6:26091590 G the release puts rs773443949 on G>T only, while the HFE example, from ClinVar, carries it on G>A too; the literal rule would have supplied G>T, picking one of two. The cost, measured over 26.09: 101,945 of the 276,003 loci with several alleles at one (chrom, position, ref) have an rsID-less allele beside a labelled one, and a no-ALT row at any of them is withheld. The supplied ALT is never written back, and no derived row names it: the pass's lists and counts are the only record (a row-level column is a P5 question left open). A snapshot built before rs_ids answers such rows as not asked, and --strict refuses it; the shared cache at /data/just-dna-cache/opentargets is such a snapshot until rebuilt. subset_snapshot now keeps every allele at a wanted allele's position whole, and the slice was recut with rs35589214's two alleles at 8:78193100 C. Against the full release apoe_epsilon gets 17,849 L2G rows, 147,760 coloc rows and 122 consequence rows, and compiles, reverses and recompiles to the same digest. The overlay reaches both sides: a supplied key's consequence row is suppressed or corrected by (variant_key, transcript), and a withheld site's rows are inserted, with the two study-locus limits above unchanged.

Residuals RM238 · RM345

RM239 — a fine-mapping posterior has no column, and gwas_effects.csv already has its key

Columns settled 2026-11-04 by the pm seat, on the lead's hand-run probe (probes/LANES_0_8.md on 0.8, 92eff12): gwas_effects.csv gains posterior_probability and fine_mapping_method, and no credible-set level.

  • Open Targets 26.09 publishes only the 95% set: is95 = is99 = true on all 40,967,780 GWAS member rows, so a level column would have no case.
  • The posterior comes from three methods (SuSiE, SuSiE-inf, PICS), and the number means nothing without its method, the same rule as a magnitude carrying its unit.

The column count is the same, and every value has a case. It is a derived table, so half price.

0.8, decided 2026-11-03. Kept in 0.8 as an input to longevitymap v2's causal and effector-gene confidence labels (RM333), while the rest of RM188's parity work moved to 0.9.

Severity low · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 D2) · Owner enricher · Motivating case probes/CLAWBIO_SURVEY.md § nine databases, and the two axes that come back with no home

For longevitymap v2 (2026-11-03): the fine-mapping posterior is the input to causal confidence C1–C4. See the group.

The same gwas-lookup report returns three fine-mapping credible sets for rs3798220 with a posterior probability and 95%/99% set membership per (trait, study) — PP 0.92 for Lipoprotein(a) in GCST005140, 0.45 for aortic valve stenosis in GCST90038614 with 95% No and 99% Yes.

A posterior inclusion probability is the same class of object as an allele frequency or a LOEUF: a number a named dataset publishes, no measurement by us, no inference by us. Its key is (variant, trait, study), which is GwasEffectRow's key plus nothing — the row already carries trait_efo_id, study_accession and p_value_num. So the cheap shape is two optional columns on the existing table, posterior_probability and credible_set, minor-legal under P3/P8, and the GWAS Catalog now publishes credible sets for its harmonised studies.

Smallest item on the survey's list, and it should not be done on its own. Do it the next time enricher/gwas.py is open for another reason. Two things a design owes: whether credible_set is a membership flag or the set's size/level (95/99 are two answers to one question, and putting both in one column is the @field-description-is-a-claim failure), and a withhold for a study whose harmonised release carries no credible set, which is a nobody-asked third state and not a zero.

Related RM188, RM90 (the table this lands on).

Built 2026-11-04 on 0.8 (build/RM333). GwasEffectRow.posterior_probability and fine_mapping_method, filled by opentargets enrich on the rows the gwas pass wrote when exactly one value answers for (variant_key, study_accession); left empty and counted when the study has no GWAS credible set in the release, when the variant is not in its 95% set, and when the variant sits in several of the study's sets with different values (2.8% of the release's (variant, study) pairs, 1,096,671 of 39,795,615). Manifest gwas_effects.with_posterior counts the filled rows.

Residuals none

RM236 — consequence and impact are planned axes with no slot, and an ACMG engine reads both as primary inputs

0.8, decided 2026-11-03. Kept in 0.8 as an input to longevitymap v2's causal and effector-gene confidence labels (RM333), while the rest of RM188's parity work moved to 0.9.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 D2) · Owner format (schema + compiler), then enricher · Motivating case probes/CLAWBIO_SURVEY.md § the two columns their engine reads that we cannot store

For longevitymap v2 (2026-11-03): causal confidence C1 and effector confidence E1 both key on a variant being coding. See the group.

ROADMAP § Reserved namespace lists consequence (the VEP/Sequence Ontology term) and impact (HIGH|MODERATE|LOW|MODIFIER) as planned future annotation axes, with the rule that they "get a slot and a specific diagnosis only when a release actually commits to building them". Nobody had committed, because nobody had a case. The case is now in hand: ClawBio's skills/clinical-variant-reporter/acmg_engine.py is a running 653-line ACMG/AMP engine whose per-criterion evidence table prints consequence=frameshift_variant for PVS1, impact=HIGH for PM1, and consequence=frameshift_variant, SpliceAI=N/A for BP7 — three of its twelve implemented criteria read a column this format cannot store, and a fourth reads the transcript the term was called against.

Get the mechanism right before touching anything. Neither name is in RESERVED_NAMES_0_4, so reject_reserved never claimed them and there is nothing to move out of a "built half": an author writing consequence today gets the generic extra="forbid" message. Committing means one of two things, and choosing is the first deliverable — build the column, or add the reserved slot plus a vocab.RESERVED_NAME_REASONS entry so an author hears what the name is held for instead of the stray-column message. The second is the honest outcome if the grain question below defers the build.

The blocker is grain, and it is RM23's blocker restated. A variant has one consequence per transcript; VariantRow is one row per (variant_key, genotype). Three options:

  1. MANE Select only — one value per variant, with GeneMetricsRow.mane_select naming the transcript it was called against. Cheap, lossy, and defensible only if the column's description says so in the field itself (@field-description-is-a-claim).
  2. Most severe across transcripts — a ranking policy. That is an interpretation, so it is out by the same clause that keeps threshold-picking out of RM23.
  3. A derived consequences.csv sidecar keyed (variant_key, transcript) — half cost under Principle 9, no authoring burden, and it is the same shape RM23 needs.

Recommend (3), and settle RM23's grain in the same pass. They are one question asked twice, and answering it once is the whole saving; splitting them is how two sidecars end up with two different answers to "which transcript". Do not build (1) as a stepping stone — a column shipped under a major cannot be retyped into a table.

Related RM23 (same grain blocker, and the pass that should settle both), RM188.

Built 2026-11-04 on 0.8 (build/RM333), option (3). consequences.csv → ConsequenceRow, keyed (variant_key, transcript), filled by opentargets enrich from Open Targets' VEP annotation: consequence_so_ids (Sequence Ontology accessions, verbatim; the name consequence stays reserved for a term label), impact (closed, VALID_IMPACTS), gene_id, gene, mane_select, canonical. The transcript set is the source's, one canonical transcript per nearby gene, and the field description says so. RM23 inherits the grain and its entry says so.

Residuals RM23

RM305 — ClinVar-GKM's allele table is an offline, independent witness for where an indel sits, and nothing reads it

Decided 2026-11-04 by the maintainer: a witness, indels only. ClinVar-GKM becomes the witness RM292's checks name (no check of its own), and the lane keeps the ~270k ReferenceLengthExpression alleles plus other indels, not the full 4.46 M rows.

0.8, decided 2026-11-03. Taken into 0.8 by the maintainer, with the rest of the indel-placement fixes (RM304, RM267, RM270, RM292, RM305). The status line below predates that decision.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (a new cache lane; no check of its own, per the 2026-11-04 decision; PROPOSAL_0_8_PT2 §5 C3) · Owner enricher (a lane beside the ClinVar VCF lane, and the check) · Motivating case GKS_SURVEY.md §0 finding 4, 2026-09-28 · related RM267, RM270, RM292

Residuals RM267 · won't fix — the source keeps no archived Parquet sets, so a past release cannot be rebuilt or pinned by URL, only detected as drift

What shipped (2026-11-04). A cache lane, clinvar_gkm (clinvar_gkm.py, clinvar_gkm_build.py, clinvar-gkm build|currency|lookup), built through CACHE_SURFACE.md's checklist. The probe (LANES_0_8.md §3) corrected two lines below: the source is on Cloudflare R2, not Google Cloud Storage, and its ids are minted under VRS 2.1.1, not 2.0.x. The lane decisions, in order:

  • Indels only, as decided: the GRCh38 alleles whose SPDI deletes and inserts a different number of bases, whichever VRS state type carries them, so the reference-agreeing ReferenceLengthExpression alleles are dropped too. 309,405 alleles from the 2026-10-24 set, 17.2 MB; every dropped class is counted in release.json (LANES §3.7).
  • The pin is (source_release, sha256), because the source overwrites its one Parquet set weekly. Both inputs are downloaded whole, as the source asks, and a file whose size or digest differs from the set's manifest.json is refused (ClinVarGkmMismatch). That is also the guard for the R2 range slip §4 records: a partial body fails the size check whatever status came with it. A release landing mid-build, and an overwrite in place under the same release, are each named.
  • Its own SourceRow, CLINVAR_GKM_TERMS, with the manifest's attribution and disclaimer verbatim. CC0 permits publishing, so the lane has ensure_* and just-dna-seq/clinvar_gkm (not created yet).
  • Keys: the VRS id and the gnomAD-style VCF spelling on every row, the rsID secondary (71% of rows). ClinVarGkmWitness.lookup returns every placement and never picks; ids_comparable allows a VRS-id comparison only at the same VRS minor, so against today's 2.0 minter a check compares by the left-normalized VCF spelling.
  • No check of its own. RM292's records and RM267's comparison name it as their witness.
  • Currency, three questions apart: a newer Parquet set exists, the set was overwritten under the same release (both digests are compared), or the set itself lags the line's newest weekly release, which a rebuild cannot fix. clinvar_gkm also joins currency.default_probes, so --verify-datasets asks it for any module whose sources.csv names it.

What exists. ClinGen's ClinVar-GKM pipeline republishes each ClinVar release in GA4GH form. Its allele.parquet is 1.09 GB, CC0, and holds 4.46 M alleles, each with a VRS 2.0 id beside spdi, hgvs.g and a gnomAD-style VCF expression. The survey found exactly the two insertion ids RM270 minted (rs72613567, rs77944059) in it, and our stdlib SNV ids matched it byte for byte on the two rows sampled.

Why it matters here. Three open items need to know whether a placement is right, and each checks it today against a source that shares our failure: RM267's anchoring error comes from the Ensembl snapshot, RM270's respelling from the source's spelling, and RM292 asks that a check say what it checked against. A table built by a different pipeline, with a spelling-independent id on every row, is a witness none of them has. It does not replace the ClinVar VCF lane: clinical significance still comes from there, and this lane is used for placement only.

Things the survey recorded that the design must carry.

  • Maturity. The dataset is at 1.0-rc3, and a breaking change landed mid-RC. The lane pins a release and records it in release.json (RM303's model, if it has landed).
  • Currency. The latest weekly delta was dated 2026-08-22, about five weeks stale at survey time, so the lane owes a currency finding (@currency-asks-the-source-not-the-cache).
  • Distribution is Google Cloud Storage, not FTP. The builder's download is a new transport and owes the client contract (@client-exception-contract).
  • VRS version. Its ids are 2.0.x (vrs_output_2_0_1.schema.json). Comparing them against ours is exactly where RM304's version record is needed.

Open questions. Is it a new check, or the witness an existing check gains (RM292's shape)? Should the lane carry the full 4.46 M rows, or only the 270,161 ReferenceLengthExpression alleles and other indels, where placement is actually in doubt?

RM328 — no study row can name the ancestry it was measured in, so "European-only evidence" is a hand-set flag

Built on 0.8, 2026-11-04: the column. StudyRow.ancestry, closed and multi-valued over vocab.VALID_SUPERPOPULATIONS, reaches studies.parquet and reverse; pgs.VALID_TRAINING_ANCESTRY is derived from the same constant plus multi. Still open: eur_only_evidence on weights.parquet, the last commit of the same StudyRow batch.

Decided 2026-11-04 by the maintainer: the 1000G superpopulation codes (AFR, AMR, EAS, EUR, SAS), the binding PgsRow.training_ancestry already uses.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 A5), taken into 0.8 on 2026-11-03 as a priority · Owner format + compiler (derived) · Motivating case longevitymap v2 requirements §5.4 (R-ANC-1, R-ANC-2) · for longevitymap v2 · related RM188 (axis 2)

What shipped. StudyRow gains ancestry, optional, multi-valued and closed over vocab.VALID_SUPERPOPULATIONS (AFR, AMR, EAS, EUR, SAS), first release 0.8.0; a trans-ethnic study lists its codes, and population stays free text. pgs.VALID_TRAINING_ANCESTRY is now derived as that constant plus multi, so the codes are one vocabulary; the gnomAD list stays apart. The column reaches studies.parquet as a list and reverse writes it back |-joined. eur_only_evidence is derived on weights.parquet, Kleene over the supporting study rows: false when one states a code other than EUR, null when any states none or there are none, otherwise true. The ancestry banner (R-ANC-3) is just-dna-lite's. Tests: compiler/tests/test_studyrow_0_8.py (the round trip, the closed list, the PGS set equality, and eur_only_evidence over a fixture meeting all three arms, including unknown AND false = false).

Residuals none

What was confirmed. StudyRow.population is free text. GwasEffectRow.ancestry and PgsRow.training_ancestry exist but each is scoped to its own table. RM188 sighted this axis three times in other projects (dna-engine's transferability, kaiseki, OmniGenis). This is the first in-house module that needs it.

Shape. A multi-valued ancestry on StudyRow bound to a vocabulary. Which one is the decision: the 1000G superpopulation codes behind training_ancestry, or the gnomAD population list, and vocab.py forbids merging the two. Full ×1. Then eur_only_evidence is derived (near-zero): every supporting row says EUR. Kleene again: a row with no ancestry makes the answer unknown, never false. The ancestry banner (R-ANC-3) is just-dna-lite's half.

RM326 — a study row cannot say which outcome it measured, so the definition of "pro-longevity" lives in a study_design prefix

Built on 0.8, 2026-11-04: the narrowing by class. duplicate_study_citation treats two rows for one (variant_key, pmid) as two claims when both state phenotype_class and the values differ. Still open: the outcome strip.

Built on 0.8, 2026-11-04: the column and its warning. StudyRow.phenotype_class, open over RECOMMENDED_PHENOTYPE_CLASSES (v2's twelve), reaches studies.parquet and reverse; a token outside the twelve draws phenotype_class_unrecognized, once per module. Still open: the duplicate-citation narrowing by class and the outcome strip on weights.parquet, both later in the same StudyRow batch.

Measured 2026-11-04, then decided by the maintainer.

The measurement was run by a subagent against both ported longevitymap studies.csv files, v2's evidence/K_definitions_comparison.csv, and OLS4. The trait term separates 0 of the 12 classes in real rows. Neither ported file fills trait_efo_id. The one longevity term in real use, OBA_VT0005372 (EFO_0004300 "longevity" is obsolete and points to it), covers at least four classes. In principle a term separates only PARENTAL_LIFESPAN (EFO_0007796) and HEALTHSPAN (EFO_0009762). Other findings:

  • study_design is free text and does not separate the classes either.
  • 15 of the K file's 63 PMIDs carry two or three classes.
  • v2 spells three class names two ways (FAMILIAL/FAMILIAL_LONGEVITY, MR/MR_MEDIATOR, BIOMARKER/BIOMARKER_CLOCK).
  • Three real studies fit none of the twelve.

Decided:

  • The column is built: phenotype_class on StudyRow, open, with v2's twelve as the recommended members. A token outside them draws a warning, which catches spelling drift without refusing a study that fits no class.
  • One paper, several classes: RM140's rule. Two rows for one (variant_key, pmid) are not duplicate citations when both state phenotype_class and the values differ. The key stays as it is, and the duplicate check narrows (@absent-is-not-different).

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 A5), taken into 0.8 on 2026-11-03 as a priority · Owner format + compiler (derived columns) · Motivating case longevitymap v2 requirements §4.5, R-DEF-1 · for longevitymap v2 · related RM323, RM325

What shipped. StudyRow gains phenotype_class, optional and open, first release 0.8.0, with v2's twelve classes as RECOMMENDED_PHENOTYPE_CLASSES spelled as this entry lists them; a token outside them is kept and draws the new warning phenotype_class_unrecognized, once per module, naming each token with its row count, in both modes. It reaches studies.parquet and reverse. Two rows for one (variant_key, pmid) stating different classes are not a duplicate citation (RM140's rule). The outcome strip is derived on weights.parquet: outcome_healthspan, outcome_lifespan, outcome_exceptional, true when a supporting study row's class maps to the cell in vocab.OUTCOME_STRIP_CELLS (HEALTHSPAN; PARENTAL_LIFESPAN, OWN_SURVIVAL; EXTREME_SURVIVAL_CC, FAMILIAL) and null otherwise, never false. v2's requirements §5.1 name the three cells and state no class map, so the map is PT2 §3 item 10's; every other class maps to no cell. The evidence role stays the module's README policy, as decided. Tests: compiler/tests/test_studyrow_0_8.py (the round trip, the warning in both modes with v2's own long spellings, the narrowing, and each strip cell over a fixture whose loci meet studied, unstudied and unmapped classes).

Residuals none

Need. v2 sorts every study into one of twelve phenotype classes (EXTREME_SURVIVAL_CC, PARENTAL_LIFESPAN, OWN_SURVIVAL, VIABILITY_AF, HEALTHSPAN, MULTIVARIATE_AGEING, FAMILIAL, DISEASE_DEPLETION, RARE_BURDEN, EVOLUTIONARY, MR, BIOMARKER), and the class decides what a row may do. The plan writes it as a prefix in study_design. But study_design describes the study (case-control, GWAS, meta-analysis) and the class describes the outcome, so a prefix puts two axes in one cell (P5).

Ask first whether it is derivable. StudyRow.trait_efo_id already distinguishes some classes (OBA life span against EFO parental longevity). Measure how many of the twelve an ontology term separates before adding a column.

Shape. One optional column with a vocabulary (closed or recommended-open is a decision). Full ×1. Two things become derived, near-zero, once it exists:

  • evidence role (score or annotate). This is the module's own policy over classes, so it belongs in the module's README, never a column.
  • the outcome strip per locus (healthspan / lifespan / exceptional survival). Kleene, never two-valued: a locus with no study row of a class is untested and withheld, never "no effect".

RM330 — an effect measured in one sex, one smoking stratum or one genotype has no row

Built on 0.8, 2026-11-04: the narrowing by stratum. duplicate_study_citation treats two rows for one (variant_key, pmid) as two claims when both state the stratum pair and it differs.

Built on 0.8, 2026-11-04: the study stratum. StudyRow.stratum and stratum_level, free text and both or neither, reach studies.parquet and reverse. Still open: the duplicate-citation narrowing by stratum, later in the same StudyRow batch.

Built on 0.8, 2026-11-04: sex. meta.csv gains the closed sex condition (male, female), part of the row key; a sex-scoped row outranks the same key without one, for that sex, and meta_resolved.parquet carries one row per scope. Still open: the study's stratum, StudyRow's half (the StudyRow batch).

Narrowing extended 2026-11-04 (the final run's gap 12). Two rows that differ only by stratum do not count as a duplicate citation, RM140's pattern.

Decided 2026-11-04 by the maintainer: the study's stratum and a sex condition. StudyRow gains the stratum an estimate was measured in, a modifier and its level (full ×2). Conclusion rows gain one closed sex condition (male/female), which the consumer matches against karyotype. This is RM28's "plain column on demand" rule, with sex as its first class. A modifier that is another locus's genotype stays RM28's (0.9).

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 A5), taken into 0.8 on 2026-11-03 as a priority · Owner format · Motivating case longevitymap v2 requirements §4.2 (context), §10 (effect_modifiers) · for longevitymap v2 · related RM188 (axis 3), RM28

What shipped. Both halves are on 0.8. The conclusion half shipped with the meta-table: meta.csv's closed sex condition (male, female), part of its row key. The study half is StudyRow.stratum and stratum_level, free text with first release 0.8.0, written both or neither (one without the other is refused), through studies.parquet and reverse; and duplicate_study_citation treats two rows for one (variant_key, pmid) as two claims when both state the stratum pair and it differs. One pair holds one modifier, so a second ("hypertensive men") stays in statistical_test; a modifier that is another locus's genotype is RM28's. Tests: compiler/tests/test_studyrow_0_8.py (the round trip with Pilling's parent-sex strata and CHAMP's sex stratum, the both-or-neither refusal, and the narrowing).

Residuals none

Need. FOXO3 rs2802292 is positive in men only, HLA-DRB1*15:01 is anti-longevity in men, and some estimates exist only in smoking strata. The plan writes these as flags: sex_specific:m and in the conclusion prose. RM188 sighted this axis three times (open-genome-atlas, a nutrigenomics project, genomi's caveat). CopyNumberRow.modifier_gene / modifier_cn is the only precedent, and it is genetic.

Two different things, kept apart.

  • The stratum a study measured in: a fact about the estimate, so optional StudyRow columns (the modifier and its level). Full ×2.
  • A conclusion that depends on the modifier: the consumer supplies it at query time (sex from karyotype, smoking from nothing). That is the injected cofactor RM28 dropped in 2026-08 with the rule "each class gets a plain column on demand". This is the demand, and sex is the candidate first class.

A modifier that is another locus's genotype (KL-VS in APOE4 carriers) is not this item. It is RM28's (in 0.8 since 2026-11-04) corpus entry.

RM329 — an age-stratified estimate has no age band, so age of action is reconstructed from statistical_test prose

Built on 0.8, 2026-11-04: the narrowing by band. duplicate_study_citation treats two rows for one (variant_key, pmid) as two claims when age_min, age_max or age_of is stated on both and differs, cell by cell; an unstated cell is unknown and still warns.

Built on 0.8, 2026-11-04: the band. StudyRow.age_min, age_max and age_of (VALID_AGE_OF) reach studies.parquet and reverse. Still open: the duplicate-citation narrowing by band, later in the same StudyRow batch.

Cut 2026-11-04 by the maintainer, after the final measuring run (probes/LONGEVITYMAP_V2_SHAPE_AUDIT.md §3): age_event (0 v2 rows with an event other than death). The band is age_min, age_max and whose age (age_of); names still get the P5 audit. Rows that differ only by band narrow the duplicate-citation check, RM140's pattern, extended to bands.

Severity low · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 A5), taken into 0.8 on 2026-11-03 as a priority · Owner format · Motivating case longevitymap v2 requirements §4.2 (age of action), Timmers 2019 age bands · for longevitymap v2 · related RM323, RM140

What shipped. StudyRow gains age_min and age_max (years, finite and ≥ 0; either may be empty for an open band) and age_of (closed, VALID_AGE_OF: participant, parent), optional with first release 0.8.0 and declared after every 0.7 column; no refusal ties the three together, and age_event was cut before the build. They reach studies.parquet and reverse writes them back. duplicate_study_citation reads the band by RM140's rule, cell by cell: two rows for one (variant_key, pmid) are two claims when a band cell is stated on both and differs, and an unstated cell is unknown and still warns. The age-of-action class and its confidence stay on meta.csv (RM323's home). Tests: compiler/tests/test_studyrow_0_8.py (the round trip with Timmers 2019's three parental bands, the closed age_of, finite ages, and the narrowing per cell, including 80– against 80–90 still warning).

Residuals none

Interim that works. One study row per age band, each with a stated and different statistical_test. RM140's rule silences duplicate_study_citation for exactly that case. Otherwise it warns, in both modes, and never refuses.

Shape. Band bounds plus whose age they are: participant or parent, at which event (death, recruitment). Full ×2–3. The names need the P5 audit before they are fixed. The age-of-action class (LIFELONG, MIDLIFE, LATE…) is a per-locus judgement and lands in RM323's home. Its confidence grade (DIRECT, DIRECT_WEAK) is partly derivable from the bands once they are data.

RM332 — a beta has no unit on authored rows, while gwas_effects.csv has carried one since 0.6

Cut 2026-11-04 by the maintainer, after the final measuring run (probes/LONGEVITYMAP_V2_SHAPE_AUDIT.md §3): the VariantRow half, which reverses the morning's "both tables". effect_unit is on StudyRow only, and the parquet joins it onto a variant's effect from the matching study row.

Decided 2026-11-04 by the maintainer: both tables. effect_unit goes on StudyRow and on VariantRow, free text and verbatim, mirroring gwas_effects.csv: wherever an effect size is authored, its unit sits beside it.

Severity low · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 A5), taken into 0.8 on 2026-11-03 as a priority · Owner format · Motivating case longevitymap v2 requirements §6.2 (effect_measure), §9 step 3 (sign conventions) · for longevitymap v2 · related @weight-has-no-unit

What shipped. StudyRow gains effect_unit, optional free text kept verbatim, first release 0.8.0, the annotation GwasEffectRow.effect_unit has; it reaches studies.parquet and reverse writes it back. The VariantRow half was cut by the maintainer before the build. weights.parquet gains a derived effect_unit per variant, repeated on each genotype row: the unit every supporting study row (same rsid or same chrom:start:ref, the orphan check's rule) that states one agrees on, and null when none states one or two disagree — PT2 §3 item 17's unanimity default for the undefined "matching study row", accepted by the pm. It is appended after every 0.7 column and reverse never reads it back, so content_signature does not move and every module with variants.csv gets a new artifact.digest on a 0.8 recompile. Tests: compiler/tests/test_studyrow_0_8.py (the column's round trip, the join over a variant whose rows agree, one whose rows disagree, one where one row of three states a unit, and the variants with none; variants.csv after reverse carries no effect_unit).

Residuals none

What was confirmed. GwasEffectRow.effect_unit (0.6) records the unit of a beta verbatim. VariantRow and StudyRow have only effect_measure. v2's betas come in years per allele (sometimes doubled from a parental estimate), in Martingale residuals (Pilling) and in healthspan hazards (Zenin), so the plan writes the unit into statistical_test prose.

Shape. effect_unit on StudyRow (and on VariantRow, which is a decision), free text and verbatim, mirroring the derived table. Full ×1–2. A sign convention ("positive = shorter life") is not a unit: effect_allele with direction already says it.

RM325 — studies.csv has no sample size, and v2's tier A rule is stated in N

Decided 2026-11-04 by the maintainer: sample_size, a closed sample_unit beside it (individuals / lives), and n_cases. A magnitude carries its unit beside it (@weight-has-no-unit), so v2's "N ≥ 100k lives" is checkable from the artifact. The names still get the P5 audit in the proposal.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 A5), taken into 0.8 on 2026-11-03 as a priority · Owner format (+ enricher, if a derived N is filled) · Motivating case longevitymap v2 requirements §4.1 · for longevitymap v2 · related RM324, RM326

What shipped. StudyRow gains sample_size (an integer ≥ 0, the total analysed with the cases included), sample_unit (closed, VALID_SAMPLE_UNITS: individuals, lives) and n_cases (an integer ≥ 0), all optional with first release 0.8.0 and declared after every 0.7 column. A sample_size without its unit is refused (@weight-has-no-unit: a parental-lifespan study counts two lives per participant), and so is an n_cases larger than the sample_size beside it; a unit or a case count alone is legal. The three reach studies.parquet (the counts as Int64, since a consumer sums them), reverse writes them back, and a stated cell is inside content_signature. The derived N on gwas_effects.csv the entry priced as a separate half-cost option was not built: nothing asked for it. Tests: compiler/tests/test_studyrow_0_8.py (a copy of reference_examples/hfe_hemochromatosis with the columns filled, compile → reverse → compile to a fixed point on both identities, and the two refusals).

Residuals none

What was confirmed. Tier A requires "N ≥ 100k lives, or ≥ 3k cases above the 90th percentile". No table in the format carries a sample size. A grep for sample_size or n_cases over the schema finds nothing, on StudyRow or on GwasEffectRow. So the rubric cannot be checked from the artifact.

Shape. sample_size (and n_cases for case-control designs) on StudyRow. Full ×1–2. The name needs the P5 audit: parental-lifespan studies count lives (two parents per participant), which is not the number of people genotyped. A derived N on gwas_effects.csv is a separate half-cost option. The GWAS Catalog publishes its sample description as text, so probe the real field before modelling it (@probe-the-real-file).

RM349 — a pmid=NONE row's DOI is never checked to exist, and its quote is never matched against the paper

0.8, filed 2026-11-04 by the lead as a second-pass item: RM336's residual.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor · Owner enricher (literature, lookup) · Motivating case the RM336 builder's report · related RM336, RM263

RM336 lets a study cite a DOI-only preprint through pmid=NONE + doi. The literature pass then has nothing to look up: a NONE row's quote or citation is recorded as an unsupported skip, so a fabricated DOI and a real one read the same, and provenance_quote is never matched against the preprint's text. The DOI is the only identifier the row carries, so it is the one the pass must check: existence through Crossref (CrossrefClient.exists, which already answers three-valued) and, where a full text is reachable (bioRxiv/medRxiv), the quote. @existence-not-identity applies: the check names the title it found.

Residuals won't fix — a DOI-only citation's answers are not pinned in literature.csv, so the compiler's quote-counter, licence and title-as-quote checks never see them; reported to the lead to file · won't fix — bioRxiv's own API publishes a jatsxml link for every preprint, a wider route than Europe PMC's subset, and is a new source rather than an existing client; reported to the lead to file

What shipped.

  • One question set per distinct DOI (spec.doi_key, so a bare DOI and a doi.org URL in another case are one citation), put by literature._check_doi_citation and returned as LiteratureResult.doi_citations, one DoiCitation each: Crossref's tri-state exists, whether it was asked, the title and agency Crossref returned, and the quote half with LiteratureRow's meanings (quotes_authored, quotes_found, quote_source, fulltext_status, and quotes_checked() through the new just_dna_format.literature.settled_quotes, which LiteratureRow.quotes_checked now calls, so the two cannot disagree about what an abstract settled).
  • Existence names its work. No citing table carries a stated title, so the contract's comparison branch has nothing to compare: the title is recorded and named in the citation_existence detail (Crossref names <doi> as '<title>', a bounded few) and on the CLI (NONE doi <doi>: names '…'). A DOI no agency knows joins doi_missing, so --strict refuses it and the CLI names it in red.
  • A Crossref 404 is not the registries' answer. Probed 2026-11-04: /works answers 404 for a real DataCite DOI (10.5281/zenodo.3360392), the kind of work a NONE row cites. CrossrefWork gained agency, and after a 404 CrossrefClient.work asks /works/{doi}/agency: another agency is exists=True with no title, a 404 there is False, and a failed or contradicting answer withholds. This reaches every caller of work/exists: an authored DOI on a PubMed row, and hint citation --doi, whose finding now says who registered the DOI rather than "Crossref has a record".
  • The text by DOI. EuropePmcClient.record_for_doi searches DOI:"…" over every source and takes only a record whose own doi matches. A record with a PMC id goes the RM257 rungs; a preprint goes to fetch_preprint_fulltext (europepmc.org/api/fulltextRepo: the file list, then the JATS file it names), and only when its search record lists a full text. Probed by hand first: the documented /{id}/fullTextXML answered 500 for all four PPR ids tried, with and without a full text; the repository served PPR1129025's JATS, and answers 500 too for a preprint with none (PPR1146237), which is why the search record gates the request. The abstract is the fallback (a hit settles, a miss does not), and fulltext_status is retrieved | absent | unreachable with RM258's meaning.
  • The records. Settled DOI-only quotes join provenance_quote's denominator and DOI verdicts join citation_existence's, each gap named in its own clause. A module citing only by DOI records citation_existence with source="crossref", or skips it as not_requested or unreachable. Offline nothing is asked (@unreachable-not-absent) and both records say offline; the quote record used to say unsupported, which after this item would claim no run could ask. unsupported is left for a row whose doi carries no DOI token, which check_citation_pair keeps out of any loaded module.
  • Not persisted. literature.csv is keyed on a PubMed id and feeds literature.parquet, which the compiler reads by PMID (split_cited_literature, the RM275 duplicate rule, manifest.literature), so a NONE row there would widen a published column's grammar, a decision this item was not given. verification.json is the durable half, and RM72's merge keeps an online ran over a later offline skip while the authored bytes stand still. Every online run asks again. Never writes a PMID anywhere (RM263 reports; it never fills).

Tests. enricher/tests/test_literature_doi_only.py, off responses recorded 2026-11-04 (a CC BY bioRxiv preprint's Crossref record, Europe PMC search, repository file list and trimmed JATS, in assets/): an existing DOI checked and its title named; a fabricated DOI a finding, refused under strict; an unreachable Crossref unreachable, never absent; --no-doi asking nothing; a DataCite DOI not absent, and every failure leg of the agency, DOI-search and repository requests; a quote found in, and missing from, the preprint body; a preprint with no text asking no repository and settling on the abstract; an unanswered repository unreachable; one preprint in two spellings asked once; a preprint beside a PMID adding to both denominators; offline asking nothing; the hint finding; and one live test under JUST_DNA_NETWORK_TESTS=1 against that preprint. test_literature_doi_cells.py's two RM336 expectations moved with the behaviour (offline quote → offline; a DOI-only pharm module asks Crossref once and records ran). Each new arm was broken once and its test went red.

RM292 — a verification check does not say what it checked against, so a check that witnesses itself reads as verified

0.8, decided 2026-11-03. Taken into 0.8 by the maintainer, with the rest of the indel-placement fixes (RM304, RM267, RM270, RM292, RM305). The status line below predates that decision.

Severity high · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 C2) · Owner format (VerificationRecord) + enricher (the check roster) · Motivating case the 2026-09-27 postmortem, blindspot B2 and mitigation M3, decided with the maintainer that day · related RM267, RM270, RM274, RM305, @start-1based, @registry-completeness

Residuals RM305 — ClinVar-GKM's allele table is the independent witness for indel placement that no check reads yet; it gets a roster entry when a check reads it · RM267 — comparing two placement authorities is the check that would turn rsid_coordinate_agreement's counted undecided indels into verdicts · won't fix — a CIViC-drafted module's published_refutation reads its checked side as withheld rather than self_consistent, because CIViC's drafter is a judgement drafter and records no digest that could establish which cells it supplied

Every check that could have seen the indel anchor error either compared a source with itself or was tolerant by design. The reference-allele check passes a wrong anchor because the anchor base is a real genome base. check_rsid_coordinates abstains on every indel position difference and counts none of them. The ClinVar snapshot was loaded in the same run and used only as a fallback. @start-1based wrote the lesson down on 2026-08-06 (validate-by-redundancy assumes independence), but only as a sentence.

The change. Each check declares two things: the source of what it checks, and the source it checks against. When those are the same source, the record reads self-consistent, never verified. A tolerance that makes a class undecided counts that class and publishes the count (@tautology-zero). It is carried as a field on the check registry and asserted by an equality over the roster, so a new check cannot ship without stating its witness.

Why a minor. The field on VerificationRecord is a new member of a published document, and self-consistent is a new verdict vocabulary member. Both are additive and minor-legal (P3, P8). Price: the record is machine-written, so half cost (P9). Not on main.

What shipped (2026-11-04). Four optional fields on VerificationRecord, all since 0.8.0: checked_source, witness_source, undecided, and independence over a new closed vocabulary VALID_VERIFICATION_INDEPENDENCE = {independent, self_consistent}. The field is named for its axis rather than verdict (P5: an outcome verdict is a likely later field on the same record), and the member opposite self_consistent is independent rather than verified, because a record with findings was not "verified". independence is derived on the model from the two sources and refused when it contradicts them; the other three join VERIFICATION_FACT_FIELDS, and since fact_signature drops None no published signature moved. witness_source is not source: source is a single licence join key (null on a two-authority check), the witness names them all, +-joined.

The roster is just_dna_enricher.verification.CHECK_WITNESSES, one CheckWitness per emitting check (checked, witness, reason, the columns a drafter digest could cover, and a tolerance). ran() and skipped() fill every record from it: a check with no entry raises, a source outside the declared witness is refused, a tolerant check's run without undecided is refused, and a non-tolerant check carrying one is refused. record_verification then settles authored against the licence table, over carried records too (the table is outside the binding), three-valued: one source whose drafter digest still covers the cells → that source (so a ClinVar-drafted, unedited clin_sig reads clinvar against clinvar, self_consistent), unless the witness is also named at the annotation layer and is another source; the witness named with nothing establishing which cells → withheld; nothing recorded → authored; an unreadable table (licensing.load_sources_file, the tri-state core read_sources_file now folds) → withheld. A checked side that is one of several witnesses withholds independence; citation_existence names Crossref only when a DOI verdict is among its subjects. The currency checks (evidence_status_currency, dataset_currency) are self_consistent by construction. rsid_coordinate_agreement publishes the indel pairs it abstains on as undecided, on the ran record and on the no_reference skip whose snapshot settled nothing. Tests: enricher/tests/test_check_witness.py (the equality over the roster, red with one entry dropped), test_enricher_doc_registries.py (ENRICHER.md's new Reads/Against columns equal the roster, red with one cell changed), and the record tests in test_verification.py, test_rsid_coordinate_agreement.py and test_clinical.py.

RM335 — model-organism evidence has nowhere to go, and a study row naming the rsID claims the mouse study was about the human variant

Severity low · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 A6, §3 item 23), taken into 0.8 on 2026-11-03 as a priority · Owner format · Motivating case longevitymap v2 requirements §4.3 (R-ANIMAL-1…5), §10 · for longevitymap v2 · related RM327

What was confirmed. The plan's interim is a studies.csv row with study_design: model_organism. That row is false either way:

  • With the rsID, it says a mouse lifespan study was about the human SNP.
  • Without one, it attaches to the whole module, because StudyRow has no gene column (RM47 made the variant optional, not a gene the row could name instead).

What shipped. model_organisms.csv, one row per model-organism lifespan finding about a human gene: ModelOrganismRow (just_dna_format.model_organisms, on AuthoredModel and CitationPair) with gene required and orthologue, species, model_type, sex, diet, lifespan_effect, concordance, pmid, doi optional. concordance is closed (concordant, discordant, nonmonotone) and empty is unstated, which is what v2's 55 "unclear" rows become. The key is every column but lifespan_effect and concordance, refused on a duplicate through _TABLE_DUPE_KEYS. An uncited row draws no warning; a cited one follows the pair's rules and is a citation site (_CITING_TABLE_KINDS). sex is the animals', free text, and deliberately not bound to meta.csv's VALID_SEXES (a karyotype condition, another axis). gene has no model-level grammar, like VariantRow.gene; check-identifiers reads it because the table is in DRAFTABLE.

Registered on the meta-table's terms, not as a _TABLE_KINDS entry, departing from §5 A6's wording on purpose (the reason is at tables.MODEL_ORGANISMS_CSV): a table kind satisfies "a module must carry at least one recognized table", is a LEAD_PARQUETS member the publish gate and discovery key on, and feeds manifest.stats.genes, and a mouse lifespan finding is none of those. So the CSV is authored input (_INPUT_FILES, content_signature), compiles verbatim to model_organisms.parquet (last in ARTIFACT_PARQUETS, not lead), and comes back through reverse. Tests: schema/tests/test_model_organisms.py and compiler/tests/test_model_organisms_compile.py (the audit's two rows through compile → reverse → compile with equal digest and content_signature, the signature moving on an edited cell, the duplicate refusal, the vocabulary refusal, no warning from an uncited row, the module-alone refusal, a literature row cited only here); the duplicate key, the signature roster, the citing roster and the reverse were each broken once and their test went red. The enricher's gene scope (gene_metrics.module_genes, which the constraint, gene-validity and dosage passes read) leaves the table out, as manifest.stats.genes does; check-identifiers still reads it.

Residuals none

Shape. A separate table, one concern per table: the human gene with an orthologue id (symbol matching found 20 of the 22 genes NCBI orthologues found), species, model type, sex, diet, the lifespan effect, and the direction concordance with the human allele (concordant, discordant, nonmonotone), with a citation. Annotation only: it never reaches an effect column or a tier (R-ANIMAL-1). Full, a new table kind. (As built, a new authored table at full price, registered beside the meta-table rather than as a _TABLE_KINDS entry: see What shipped.)

RM351 — a PGx check keys a named allele on its bare name, so star_allele_undefined fires on every HLA allele

0.8, filed 2026-11-04 by the lead as a second-pass item: found while building RM334.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor · Owner compiler (table_checks._cross_validate_haplotype_definitions and its siblings) · Motivating case the RM322/RM334 builder's e2e: ['*15:01', '*57:01:01'] reported as used but not defined · related RM334, RM28

One class. The cross-table PGx checks collect allele names into sets keyed on the bare allele string, not on (gene, allele). A typed allele that has no defining variants by design (an HLA allele, called by a typer, not a SNP) is then reported as "can never match", which is false, and two genes sharing an allele name (*2) are conflated. The meta-table's allele_function members (RM28) make this the v2 shape. The fix keys every such set on (gene, allele) and exempts a gene whose alleles are typed rather than defined (the HLA grammar's genes). Grep for the class, not the instance: every used.setdefault(row.allele and set of bare allele names in the compiler.

What shipped. The class had two instances, both in compiler/.../table_checks.py:

  • _cross_validate_haplotype_definitions (star_allele_undefined): defined and used were sets of bare names. They are (gene, allele) now. A haplotypes.csv row with no gene (the column is optional there and required on the other two tables) is the unknown arm: it defines its name for every gene, which is what the bare-name key did, so a module that leaves gene out of haplotypes.csv is warned about the same alleles as before. Genes compare through _gene_key (case and surrounding space ignored), because the bare-name key never read the gene and a stricter comparison would have turned a spelling into a finding. An HLA gene (pgx.is_hla_gene) that haplotypes.csv defines nothing for is exempt, since its alleles are typed; one the module defines by variants (a tag SNP) is checked like any other. The predicate is new, it states the HLA- prefix once, and RM334's hla_allele_refusal now reads it too. The message keeps its wording and appends By gene: <gene> <allele>, …; <gene> …, then, when an HLA allele was skipped, the HLA genes it did not check. When every undefined allele is an HLA allele, nothing fires.
  • _cross_validate_phase_ambiguity (diplotype_definitions_identical, diplotype_phase_ambiguous): definitions was keyed on the haplotype name, so a second gene's *2 merged its defining variants into the first gene's *2, and a real finding about the first went silent. Definitions are keyed (gene, name) now, through the same _gene_key. A diplotype reads its gene's own rows laid over any gene-less ones (_defined_for), resolved once per (gene, name) rather than once per row.

Not instances, read and left alone: compiler/meta.py's allele-to-diplotype reach (gated on diplotype.gene == target.gene), and in the enricher pgx.py's function cross-check (keyed (row.gene, row.allele)), drug_labels.authored_subjects (passes row.gene), and pgx_draft (one gene per draft, so its allele sets are already per gene). Tests: compiler/tests/test_pgx_allele_identity.py (the HLA case and the shared-*2 case, both failing before the change; the phase leak; both gene-less cases; a gene spelled in another case; an HLA gene defined by a tag SNP; the per-gene grouping; and the six PGx reference examples, checked against the bare-name rule restated in the test, and for the phase check against a run with haplotypes.csv's genes blanked); one scenario in features/compiler/licensing_closure_pgx.feature.

2026-11-04, RM356. The same class reached haplotypes.csv's own duplicate rule, which keyed a row on (haplotype_name, variant_key, allele) with no gene, so two genes' *2 on one variant were one row. RM356 splits it on a stated gene and moved _gene_key beside the shared predicate, compiler.tables.same_row.

Residuals none

RM327 — pleiotropy has no per-trait row, so a trade-off can only be prose, and tradeoff is computed rather than authored

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor, taken into 0.8 on 2026-11-03 as a priority; the per-trait rows shipped with the meta-table (RM28), tradeoff with PROPOSAL_0_8_PT2 §3 item 9, §5 B2 · Owner format + compiler · Motivating case longevitymap v2 requirements §4.2 (pleiotropy, mediator), §10 · for longevitymap v2 · related RM28, RM321, RM323, USE_CASES § 6a

Residuals won't fix — false stays unreachable in 0.8, because a module states no closed list of the traits an allele touches, and the reason is in this entry

What shipped (B2, 2026-11-04). tradeoff is a nullable boolean column of meta_resolved.parquet, computed and never authored. A per-trait judgement is a one-member meta.csv row with trait_efo_id and a direction. The verdict is taken per member (its members_key): true when the member has a protective row on one trait and a risk row on another, and it lands on every row the member reaches (each genotype row of a bare locus, the reference homozygote included, and each diplotype carrying a named allele_function allele). A row two members reach is true when either is. Two alleles are never pooled: ε2 protective on one trait and ε4 risk on another leave the ε2/ε4 row null, since neither allele has a trade-off. On one trait at one row the fact columns' precedence runs first, so a narrower judgement on that trait (a sex-scoped row, a diplotype over the allele it contains, a genotype over its locus) drops the broader one there; that came out of the code review, whose case was ε3/ε4 stated neutral on the trait ε4 is risk on. Defaults taken: a mediator row counts, because its direction is still a benefit or a harm; neutral, unknown and contested are not signs; a direction the compile withheld (meta_member_allele_ambiguous) is unknown and adds no sign; a direction with no trait_efo_id is not a per-trait row. The name left RESERVED_NAMES_0_4 for MISPLACED_COLUMN_REASONS in the same commit, so a tradeoff column on any authored table is refused with the reason that the compiler computes it. Tests: compiler/tests/test_meta_compile.py (the audit's example 4, a parametrized Kleene table, per-member versus pooled, sex precedence, the round trip and byte determinism) and schema/tests/test_v04.py (the refusal, walked over every authored model).

Why false is never written. RM327's Kleene rule makes false mean that every trait's judgement is present and none opposes another. A module cannot say it has listed every trait an allele touches: there is no closed trait list in the format, and the absence of a risk row is not a judgement that there is no harm. So one sign alone is null. Reaching false would need a declared closure (for example a module-level statement that its per-trait rows for a member are complete), which no consumer has asked for; it is not filed.

The dated lines below are the record as it stood, newest first. The oldest of them, the (subject_kind, subject, trait_efo_id) key, was superseded by the re-derivation above it once RM323 dropped subject kinds: what shipped is the meta-table's key, (members_key, trait_efo_id, sex), with APOE ε4's per-trait rows written as allele_function members. The Shape below is the pre-design sketch; its authored per-trait table was not built, and the reservation it describes has moved.

Built on 0.8, 2026-11-04: the meta rows. A per-trait judgement is a one-member meta.csv row with trait_efo_id, direction and an allele-bearing member (a bare locus bears one when its rows share an effect_allele, else meta_member_allele_ambiguous and the direction is withheld), trait_role (mediator) beside it. Still open: tradeoff and the resolved facts' Kleene table (B2), computed at meta_resolved.parquet's grain; the name stays reserved until then.

Default under the 2026-11-04 reduction rule (the pm seat's reading; the maintainer may veto): a per-trait judgement is a row of RM28's meta-table: one member, trait_efo_id, and direction (protective/risk). tradeoff is computed over those rows, and no new table kind is built for this item.

Key to re-derive, 2026-11-04. RM323 no longer has subject kinds, so "align on RM323's subject" now means: a per-trait row is keyed on an item of a single-statement table plus trait_efo_id, using the same item references as the meta-table's members. The proposal settles the exact spelling.

Decided 2026-11-04 by the maintainer: the key aligns on RM323's subject. It is (subject_kind, subject, trait_efo_id), and effect_allele is kept for variant subjects only; a haplotype or gene subject is its own allele. RM323, this table and later RM28 then share one identity, so APOE ε4's per-trait rows are haplotype rows.

What was confirmed. VariantRow keys on (variant_key, genotype), so a genotype row states one claim about one trait. Re-keying a shipped authored table is major-only (P3; RM140's text). DiplotypeRow already keys on trait_efo_id, so the two tables disagree on whether pleiotropy is a row. The per-trait facts already arrive in gwas_effects.csv (derived, with effect_direction increase/decrease). What has no home is the curator's per-trait judgement: whether this allele's effect on that trait is a benefit or a harm, which VALID_EFFECT_DIRECTIONS deliberately does not say.

direction: contested is not the interim. Its description says the sources disagree about the sign. At a trade-off nobody disagrees: two known effects point opposite ways. SH2B3 and CDKN2B-AS1 are genome-wide-significant lifespan hits, so their lifespan sign is established, and the trade-off belongs in negatives until this table exists.

Shape.

  • An authored per-trait table keyed on (variant_key, effect_allele, trait_efo_id), carrying the existing direction vocabulary, a role (outcome or mediator), and a citation. The mediator EFO the plan parks in flags: mediator: folds in here, so trait_efo_id stays role-free. Full, a new table kind.
  • tradeoff, computed, never authored (decided). True when an allele has a protective and a risk row across traits. Kleene: false only when every trait's judgement is present and none of them is opposite, and unknown otherwise, unless both signs are already present. A derived column, near-zero.
  • Reserve the name tradeoff in RESERVED_NAMES_0_4 with a reason, so nobody authors it before the computed one lands. Done 2026-11-03, on main as a patch: every authored model now refuses the column with that reason rather than the generic stray-column message. When the derived column ships, the name moves from the reserved set to MISPLACED_COLUMN_REASONS, since it will then be real on a generated table and still never authored.

RM352 — release records have no change kind for a toolchain-only byte move, so the 0.8 cut cannot declare polars 2

0.8, filed 2026-11-04 by the lead as a second-pass item: RM342's residual, and a cut gate.

Severity high · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (a new member of a closed published vocabulary, and a Goals amendment) · Owner format (release_records.VALID_RELEASE_CHANGE_KINDS) + compiler (sweep.py) · Motivating case the RM342 builder's report · related RM342, RM341

Residuals none

Why it was filed. VALID_RELEASE_CHANGE_KINDS was {correction, addition}, and the sweep's gate (UNDECLARED_KIND_PHRASE) needs one of them for every moved axis. polars 1 → 2 moves parquet_bytes on every module with no value wrong and nothing added, so the 0.8.0 record could not be written. A third member, toolchain (bytes moved, content unchanged, the toolchain record says why), is additive and minor-legal. The 0.8.0 record then declares the polars move with it. The Constitution's Goals sentence on reproducibility ("anyone holding the inputs and the pinned compiler version") gains "and the recorded toolchain", matching RM342's Principle 4 amendment, with a line in the amendments history.

Decided 2026-11-04 by the lead with the maintainer, during the build. Content unchanged is not enough to accept a toolchain declaration: a compiler bug moves bytes without moving content, and at the 0.8 cut the compiler version changes together with polars, so RM342's toolchain_differs co-occurs with every move in the release sweep and separates nothing. The only clean separation is a second sweep with the compiler held fixed and only the toolchain varied, and the gate reads that sweep's fields, never a sentence in evidence (@one-side-only-has-two-causes).

What shipped.

  • VALID_RELEASE_CHANGE_KINDS gains toolchain. DeclaredChange refuses it on any axis but parquet_bytes (a model validator), since only a byte measurement can back it. RecompileAnswer.toolchain_moves sits beside corrections and additions, and the three cover declared (asserted over a synthetic record holding one of each).
  • SweepMeasurement.before_toolchain / after_toolchain (the one toolchain each side recorded, None when a module recorded none or the side mixes two) and before_digests / after_digests (each module's artifact.digest). measurement_json carries all four.
  • gate_findings(..., toolchain_measurement=) and sweep --toolchain-before DIR (the release's compiler under the previous toolchain; the release sweep's AFTER tree is the other side, nested under toolchain_sweep in --json). A toolchain declaration on a moved parquet_bytes passes only when that sweep was passed, its two sides carry one compiler_version and it is the release gated, both sides record a toolchain and they differ (unrecorded is unknown and never satisfies), its AFTER side is the release's AFTER tree digest for digest, and content_signature did not move on the modules it speaks for. Which modules the toolchain explains is per module and a digest equality: the previous compiler and this one wrote the same bytes under the previous toolchain (the release BEFORE digest equals the fixed-compiler BEFORE digest). The code review caught the first build accepting a module merely because it also moved under the toolchain, which polars 2 does to every module, so a compiler byte change would have shipped labelled toolchain. When toolchain is the axis's only kind every moved module must be explained; beside another kind it must explain at least one. Nine TOOLCHAIN_* phrases (one a note). UNDECLARED_KIND_PHRASE keeps its wording and appends (or, on this axis, a toolchain move) on parquet_bytes.
  • The Goals bullet Make integrity the identity now ends "holding the inputs, the pinned compiler version and the recorded toolchain." The why is in CONSTITUTION_AMENDMENTS_HISTORY.md.

Measured, not assumed (2026-11-04, the 0.8 branch at this item). Three real trees of the sixteen reference_examples/: published just-dna-compiler 0.7.2 under polars 1.44.2, this branch's compiler under polars 1.44.2 (uv run --with), and this branch's compiler under the locked polars 2.1.0. Under the toolchain alone parquet_bytes moves on 16 of 16 and nothing else moves. With polars held at 1.44.2, the compiler alone moves parquet_bytes on 3 of 16 (fmr1_cgg_repeat, hboc_palb2, pathogenic_clinvar, the three whose parquet_schema moved too) and manifest_fields on all 16. So a toolchain-only declaration over the real interval is refused for exactly those three, and toolchain beside an addition passes with a note naming them: the review's case, measured. The 0.8.0 record itself is the cut's to write, after measuring. Tests: compiler/tests/test_release_kind_toolchain.py, the kind tests in schema/tests/test_release_records.py.

RM303 — the snapshot layout is a contract with six parties and no model, so it belongs in just-dna-format

0.8, confirmed 2026-11-03 by the maintainer when scoping 0.8.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — filed 2026-09-28 at the maintainer's request, taken into 0.8 (PROPOSAL_0_8_PT2 §3 item 21, §5 D1) · Owner format (the model) + enricher (the writers and readers) · Motivating case the builders' release.json keys have drifted, and one drift already reached cache status

Residuals won't fix — snapshots already published on HuggingFace keep their old keys until a republish, because a published file is never edited in place and the model reads them · won't fix — the acmg and mitomap_miss lanes write no dataset, so cache status prints no label for either; that predates this item, changes no spelling, and was reported to the lead for a number of its own

The problem. A reference snapshot is data/*.parquet, optional sidecars, LICENSE.txt and release.json, and locations.py's own header says that at least four parties (builder, publisher, provisioner, reader) have to agree on those names. The names are constants in the enricher, so any other repo that wants the layout has to import the network tier to get them. release.json has no model at all. read_release returns a dict, and the 14 builders write it by hand at 15 sites. The keys have drifted:

Key Writers
built_at all 15 sites
builder_version 13
source_url, source_sha256, dataset 11 each
rows alphagenome_avi, mane, mitomap
row_count clinvar, clinpgx, acmg
license / licence strchive / civic
builder, release, parents acmg; civic; mitomap_miss

ClinVar writes no dataset, so cache status printed a blank release label for it. The repair was a per-lane exception (clinvar_dataset_label, see caches.py near _dataset_label). That is the drift surfacing as an incident, and it was repaired at the reader rather than at the contract.

The split. The two files mix two kinds of thing, and they are separated by what each is tied to:

  • Contract → just_dna_format.snapshot, pydantic + stdlib only, no environment, no network: the layout names (data/, release.json, LICENSE.txt, the sidecar and root-filename tuples), a SnapshotRelease model, read_release(dir) -> SnapshotRelease | None, and a payload predicate ("this directory holds a snapshot") that reads no environment.
  • Deployment → stays in the enricher: CACHE_BASE_VAR and the per-lane variables, .env loading, platformdirs and APPNAME, the per-lane resolvers, CACHE_LANES, prepare, rebuild and publish. It provisions and fetches, and it is tied to specific lanes. The enricher's locations names become imports from format.

Charter checks.

  • Goals: an amendment is owed. Goal 1 scopes format to "annotation modules", and a snapshot is not a module. No principle forbids the move (no network, no new dependency), but it widens what the package is for, so it lands as a deliberate one-bullet Goals amendment, with the reasoning in CONSTITUTION_AMENDMENTS_HISTORY.md.
  • P3 from then on. Once the model is published, release.json keys are additive-only within the major. That makes the drift above a decision to take before the first publish: which spelling of each drifted pair becomes the field, and whether the other is read as an alias.
  • P9. A derived file that no human authors: half price at most, and no authored schema moves.
  • The tri-state rule. read_release keeps None for both absent and unreadable, as it does today. A key the model makes optional stays None when it is unstated, never a default, because the ClinVar label bug above is exactly a missing key being read as a blank answer.

Open questions.

  1. Core plus extension. parents (the derived lane) and lane-specific keys either get typed optional fields or ride in extra="allow". Typed fields are safer; extra keys keep the model small. Decide by listing what each reader actually reads.
  2. The drifted pairs. rows/row_count and license/licence pick one spelling each; the old spelling is read on input and never written again. builder against builder_version needs a look at what acmg means by it.
  3. A guard. Every builder writes through the model rather than through json.dumps. An AST walk over *_build.py refusing a hand-built release.json dict is the usual shape (@registry-completeness).
  4. Published snapshots. Snapshots already on HuggingFace keep their old keys. The model reads them, and a republish writes the canonical spelling, never an in-place edit.

Considered and refused on the same day.

  • Renaming just-dna-format (e.g. to just-dna-schema, the workspace directory's name). With the snapshot contract added, "format" becomes more accurate: the package defines two on-disk formats. A rename would touch about 130 importing files across five repos and keep two distribution names alive for a major. Refused by the maintainer.
  • A just-dna-datasets / just-dna-builders package. First offered on 2026-09-25 (the RM261 round) as the recommended way to take the builders out of the wheel, and declined then without being recorded. Weighed again now, it forms a cycle: builders need the layout from the enricher, and cache rebuild needs the builders. Breaking the cycle means moving the layout below both, which is this item, and after that the separate package buys nothing. Its dependencies are the enricher's own, and the columns it writes are read by enricher passes, so every snapshot change would become a release of two packages. It would also need a Goal 2 / Principle 2 amendment, since builders fetch and the enricher is named as the only tier that may. Builders and readers stay beside the pass that reads their columns. just-prs's parquet lanes stay in just-prs (PRS_CACHE_DIR), and the v1 port is a consumer (pipelines → enricher), not a dataset.
  • A nano-library holding only the convention. Too small to be its own package. Format already depends on pydantic and already owns the module's provenance record (manifest.json), and release.json is that record's snapshot twin.

What shipped (2026-11-04). just_dna_format.snapshot: the layout names, SnapshotRelease, read_release (None for absent and unreadable, as before), write_release (exclude_unset, sorted, atomic), release_label, release_is_unreadable, holds_snapshot_payload, and clinvar_release_label. The open questions, answered by §3 item 21 and by reading every reader first (the reader×key table is in the commit message):

  1. Core plus extension. Every key some reader reads is a typed optional field (dataset, source_url, source_sha256, built_at, builder_version, license, license_sha256, row_count, row_counts, record_count, genome_build, parents, clinvar_file_date, status_basis, sf_version); everything else rides in extra="allow". Reading the real MANE snapshot showed source_url and source_sha256 per input there, so both are str or a per-input map.
  2. The drifted pairs. license is the field and licence is read. rows was two things: a total (AlphaGenome AVI) reads into row_count, a per-file map (MANE, MITOMAP) into row_counts, CPIC's spelling, rather than one field holding two kinds of value. acmg's builder is the module path just_dna_enricher.acmg_build, not a version, so it is no alias of builder_version and rides in extra. ClinVar's builder now writes dataset through clinvar_release_label, and a release written before has clinvar_file_date and no dataset, which the model reads into dataset through the same formula. So CacheLane.release_label's ClinVar override is gone and the lane set overriding it is empty; cache status prints the same labels before and after.
  3. The guard. enricher/tests/test_release_json_through_the_model.py walks every *_build.py: no builder may name release.json (constant or literal) outside an import or an .unlink, and the builders calling write_release equal the builders. It was red on all fourteen before the conversion. mitomap_miss's parent pins compare both sides in canonical spelling, so a parent rebuilt with row_counts is not reported as moved from a pin that says rows.
  4. Published snapshots read through the model, and a republish writes the canonical spellings.

Every reader of release.json in the enricher now goes through read_release or release_label, including the eight that parsed it by hand. The Goals amendment is in CONSTITUTION.md, with its reasoning in CONSTITUTION_AMENDMENTS_HISTORY.md.

RM253 — a repeat-count star allele (UGT1A1 *28 = TA(8)) has no home a diplotype can name, and the CPIC drafter translates none of CPIC's notation

What shipped (2026-11-04). All three seams, as decided, in the enricher alone: no model, column or pattern changed.

  • Seam 1 and seam 2, spelled. cpic_notation.spell turns DEL<bases>, INS<bases> and UNIT(n) into the VCF-anchored, left-normalized indel a caller writes, reading the anchor and the run from the GRCh38 reference through the enricher's SequenceProxy and the CIViC drafter's _left_align. Read by hand first (seqrepo REST, 2026-11-04): 2:233760233 is C and 233760234–233760247 is seven AT, so *28 is C>CAT, *36 CAT>C, *37 C>CATAT, matching the decision line exactly; the reference count TA(7) is *1's, and it is written C>C at that anchor, the reference state. CPIC's position convention was measured, not assumed: a DEL position is the first deleted base, an INS position the base the insertion follows, a repeat's the first base of the run. Two traps the decision did not name, both found on the snapshot: RYR1 writes a delins as DEL<bases> on Reference beside INS<bases> on the variant, read by locus as TC>CT (Ensembl's own reading of rs193922862), and a repeat row carries no rsID (the rs3064744 trap), while a DEL/INS row keeps CPIC's.
  • Seam 3, written. pgx_draft._draft_name drops the spaces and writes CPIC's comma as &, only when every part is HGVS; HAPLOTYPE_NAME_PATTERN accepted the result on all three PGx models and was not widened. DPYD, RYR1, CACNA1S and MT-RNR1 draft and compile --strict; G6PD's alias lists stay skipped, because an & there would claim a compound.
  • What still does not spell, by reason: a bare DEL (by decision), alternatives (GAGTCG(3) OR GAGTCG(4), MT-RNR1's ; list), a reference that does not bear the notation out, and one that could not be read (every row under --offline).

Measured on the provisioned snapshot (cpic_snapshot_b0ffd4c6f010): it holds 46 distinct notation spellings, 27 of them on star-named alleles, the only ones the old drafter could reach (the filing said 25); test_the_closure_counts_of_notation_spellings_on_the_snapshot_it_names re-derives both. After, the reachable spellings still skipped are the bare DEL and GAGTCG(3) OR GAGTCG(4); the rest of the skipped DEL<bases> spellings sit on G6PD and CFTR alleles whose names the drafter does not write. (Measured once over every gene with the live reference on 2026-11-04, not re-derived by a test: 35 of the 46 spelled at least once.) The tests are enricher/tests/test_cpic_notation.py, against the snapshot and a recorded slice of the reference (assets/grch38_cpic_notation_windows.json).

Residuals none

NUDT15 *2 is still undefined, and it is not a residual of this item: the snapshot has no defining row for it at all, so there is nothing for a translation to spell. Whether the live API defines it was never probed, and no open item carries it.

Seam 1 decided 2026-11-04 by the pm seat, on the evidence, as the maintainer asked: spelled, VCF-anchored and left-normalized.

A subagent read the site in about 120 PGP-HMS VCFs plus local runs. The evidence, all measured:

  • DeepVariant, DRAGEN, GATK, Clair3, Isaac, Helix, the imputation servers and CGI vcfBeta all write *28 as the ordinary indel C>CAT at the anchor (GRCh38 2:233760233, GRCh37 2:234668879), left-normalized.
  • No file holds a symbolic allele at the site, and no caller gives a repeat count in place of sequence.
  • freeBayes and bcftools mpileup write the whole 16-base run unnormalized. They match only once the consumer normalizes, which the consumer guide already says no format guarantees.

So *1 is the reference, *28 is C>CAT, *36 is CAT>C and *37 is C>CATAT. Seam 2 follows the same rule: CPIC's DEL<bases>/INS<bases> are spelled the same way, and the bare DEL with no length stays skipped.

One trap to carry into the build. rs3064744 appears in no VCF's ID column. Arrays (23andMe, AncestryDNA) and dbSNP-annotated VCFs carry rs34983651 for the +TA allele, and one imputation server stamps rs606231201, which dbSNP places as a different allele. So an rsID-keyed row must not rely on rs3064744.

Decided 2026-11-04, in part. DPYD (seam 3): the drafter writes CPIC's full name with the spaces dropped, as the maintainer chose. The comma between variants is replaced, because a comma inside a name would split any multi-valued cell (MULTI_SEP is ,;|). The maintainer suggested :, tentatively ("maybe?"). The pm seat picked & instead, and the maintainer may still veto it before the drafter ships. & was picked because every other candidate already means something in an allele name. : is HGVS's reference separator. + is an intronic offset (c.1905+1G>A, DPYD *2A). _ is an HGVS range. / separates the two halves of a diplotype. So HapB3 is c.1129-5923C>G&c.1236G>A(HapB3). Seam 1, how a repeat count is spelled: open, decided after checking precedent in real VCFs (PGP-HMS, and just-vcf's seats).

0.8, confirmed 2026-11-03 by the maintainer when scoping 0.8.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-21 (PROPOSAL_0_8_PT2 § 5, A8) · Owner enricher (pgx_draft, cpic_notation); no schema change · Motivating case S106 — the most common UGT1A1 allele, the one atazanavir and the irinotecan labels key on, ships undefined

Reproduced on the snapshot, and the reporter's reading holds with one correction. CPIC defines UGT1A1*1 as TA(7), *28 as TA(8), *36 as TA(6) and *37 as TA(9), all at rs3064744 (the report said rs8175347, the promoter's other name in the literature), plus *80+*28 and *80+*37 as two-variant haplotypes. draft_gene skips all six repeat rows, so haplotypes.csv defines *28 by nothing while allele_function.csv and diplotypes.csv name it, and validate warns "Star allele(s) used but not defined" — correctly, and unfixably by the author. Across the whole snapshot the notation the drafter skips is 25 distinct spellings: DEL<bases> (the bulk, e.g. DELTCT), a bare DEL (4 rows, lengthless), INSCGGG, and UNIT(n) repeats (TA(8), AAAGGGGCG(2), GGA(1), TCAG(2)). NUDT15 *2 has no defining row in the snapshot at all, so that half of the report is scoped to the live API, which was not probed.

Three seams, and they are not one item's worth of the same thing.

  1. A repeat count as a defining allele. The format holds <CNV:TR:n> since RM5 — but n is a length in bases, so TA(8) would be <CNV:TR:16>: legal, distinguishable from *36/*37/*1 by length, and lossy about the unit. Whether that is the right spelling, or whether the sequence should be spelled out (sixteen bases, the standard's own preference when the sequence is known — but VCF-anchored, which needs the preceding base the drafter does not have and the Ensembl row RM251 now records does), or whether repeat_alleles.csv should gain a join to a haplotype name, is the design question. The reporter's framing is exact: today it is a bin or a name, never both, and the diplotype table needs the name. @hosting-tri-state says a symbolic allele compares as undecided against a spelled call, so the first option moves the join to the consumer's caller (requires_callable) — which may be the honest answer for a VNTR, and is still a decision.
  2. DEL<bases> / INS<bases> → <DEL:n> / <INS:n>. A drafter translation, not a schema gap: the length is the notation's own, and the symbolic spelling is exactly what RM5 built for a variant "whose sequence is deliberately unspelled". The bare DEL stays skipped (no length). The open question is whether a spelled deletion should be spelled — CPIC gives the deleted bases and the position, and the anchor base is one reference read away.
  3. HGVS-named alleles (DPYD). HAPLOTYPE_NAME_PATTERN refuses whitespace, and CPIC's names are c.1003G>T (*11) and c.1129-5923C>G, c.1236G>A (HapB3). The report's claim that haplotype_name accepts them is wrong as spelled — probed, all three PGx models refuse on the space — so this is a naming policy for the drafter (the legacy star in the parenthesis? the HGVS string with the space removed? both, one as suballele?) before it is anything else. 167 defining rows and 3,570 diplotypes wait on it.

What shipped with the filing (message only, in the uncut 0.7 line): the RM5 notation warning now names the three symbolic spellings the format holds and says the drafter does not translate into them, pointing here; and the unparsable-diplotype sentence is bucketed by reason, so DPYD's HGVS names are no longer reported as CYP2D6's copy-number notation.

Parking-condition gate audit: none of the three needs a consumer to act first — the corpus is the snapshot, already provisioned, and the probe module is a draft_gene("UGT1A1") away. This is a design decision, not a wait.

RM334 — an HLA allele has no table, and tag SNPs cannot stand in for one

Cut 2026-11-04 by the maintainer, after the final measuring run (probes/LONGEVITYMAP_V2_SHAPE_AUDIT.md §3): the new HLA table. allele_function.csv (keyed (gene, allele)) holds the 8 v2 alleles, and meta-table rows hold their facts and findings. The nomenclature grammar check applies to HLA genes on allele_function.csv.

Decided 2026-11-04 by the maintainer: grammar now, the list in 0.9. The format checks the nomenclature's grammar (gene*field:field at a stated resolution). Checking that an allele exists in IPD-IMGT/HLA's list is an enricher lane whose licence is unprobed, and it waits for 0.9.

Severity low · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 A4, §3 item 22), taken into 0.8 on 2026-11-03 as a priority · Owner format · Motivating case longevitymap v2 requirements §2 (R-HLA), §10 · for longevitymap v2 · related RM331

What shipped. No new table, as the maintainer cut it: an HLA allele is an allele_function.csv row. Where AlleleFunctionRow.gene starts with HLA-, allele must match pgx.HLA_ALLELE_PATTERN in full: *, two to four colon-separated numeric fields of at least two digits each, and an optional expression suffix from N, L, S, C, A, Q. The field count is the stated resolution, so a one-field name is refused, and so is the colon-less *1501. A malformed name is a refusal at the model (validate_hla_allele), so validate and compile refuse it alike in both modes, naming the row, the shape and an example. Every other gene keeps the permissive haplotype-name rule. The rule has one statement, pgx.hla_allele_refusal (a reason or None): the model raises it, and the CPIC drafter (pgx_draft) skips an HLA allele it refuses with the same reason instead of failing the draft.

The published-module scan (2026-11-04), which the refusal was gated on. The reference examples: two allele_function.csv files (cyp2c19_star_alleles, cyp2c9_warfarin_grch37), no HLA- row. The registry's prod catalogue: 24 modules and 46 versions, read through each version's manifest; one module carries allele_function.csv (antonkulaga/fut2_secretor 1.0.0 and 1.1.0, three FUT2 rows each, downloaded and read), no HLA- row. The HLA genes in big_five_personality_snps and pathogenic are variants.csv genes, outside the check. The test group on prod lists nothing. So the refusal breaks no published module.

Not in this item: checking that an allele exists in IPD-IMGT/HLA's list, which the maintainer put in 0.9 as an enricher lane with an unprobed licence; no RMn carries it yet. Tests: schema/tests/test_rm334_hla_grammar.py (the accepted and refused names, mutation-checked on the field count and on the gene test) and compiler/tests/test_rm334_hla_refusal.py (validate/compile parity, and a well-formed HLA row through compile → reverse → compile).

Residuals none

2026-11-04, RM351. Building this item turned up a defect in a neighbouring check: star_allele_undefined reported every HLA allele as one that "can never match" (its e2e reported ['*15:01', '*57:01:01']), because the PGx cross-table checks keyed an allele on its bare name. RM351 keys them on (gene, allele) and exempts an HLA gene through pgx.is_hla_gene, which hla_allele_refusal now reads as well.

Need. HLA-DRB1*15:01 and B*57:01 are v2's most consistent non-APOE signals, and the plan defers them to tag SNPs flagged with r².

Why no existing brick fits. HaplotypeRow is a definition: the variants that are on one strand. An HLA tag SNP is a probabilistic proxy whose r² depends on ancestry, so writing it as a definition would be a false claim. AlleleFunctionRow has the nearest key, (gene, allele), but its columns are PGx activity and function.

Shape. A per-allele carrier table keyed on (gene, allele) at a stated field resolution (two-field), with direction, trait_efo_id, conclusion and a citation. The consumer joins it against an HLA typing call, which is a measurement a SNP VCF does not contain. The tag-SNP fallback reuses RM331's proxy shape. Full, a new table kind. Validating the nomenclature (IPD-IMGT/HLA) is an open question.

RM322 — diplotypes.csv carries none of the axes a scored finding needs, so APOE, the module's headline result, cannot state its tier, mechanism or trade-off

Cut 2026-11-04 by the maintainer, after the final measuring run (probes/LONGEVITYMAP_V2_SHAPE_AUDIT.md §3): priority (it restates the tier; v2 says it is "derived from tier") and actionability (v2's policy "late-acting ⇒ descriptive" belongs in its README). DiplotypeRow gains only negatives and category.

Decided 2026-11-04 by the maintainer: four columns, no flags. DiplotypeRow gains negatives, category, priority and actionability, each full price, with RM70 as the precedent. flags stays off: no tier acts on its tags (RM321), and v2's flag tokens are what RM323–RM330's typed columns replace. Per-locus facts go on RM323's table, with APOE ε2 and ε4 as haplotype subjects.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §5 A3), taken into 0.8 on 2026-11-03 as a priority · Owner format (DiplotypeRow) + compiler (the diplotype parquet and reverse) · Motivating case longevitymap v2 requirements §6.4, decision D2 · for longevitymap v2 · related RM323, RM28

What shipped. DiplotypeRow gains negatives and category, both optional free text with first release 0.8.0. Each is VariantRow's column of the same name, description included, and category binds no vocabulary on either table. They reach diplotypes.parquet as nullable strings through the generic table materializer, reverse writes them back, and both are inside content_signature when stated; a module that leaves them out or empty keeps its signature. Every module carrying diplotypes.csv gets a new artifact.digest on a 0.8 recompile, because the parquet gains two columns; they are declared last, so no 0.7 column changes position. priority, actionability and flags were cut by the maintainer on 2026-11-04 and are not deferred: priority restates the tier, actionability is v2's README policy, and per-locus facts live on the meta-table (RM323). Tests: compiler/tests/test_rm322_diplotype_axes.py (a copy of reference_examples/apoe_epsilon with both columns filled, compile → reverse → compile to a fixed point on both identities).

Residuals none

What was confirmed. DiplotypeRow has gene, haplotype_a, haplotype_b, trait_efo_id, direction, clin_sig, phenotype, conclusion and the PharmGKB drug block (drug, response, evidence_level, recommendation_strength, clinical_context). It has no negatives, category, priority, flags, actionability, stat_significance or effect_*. v2 scores APOE once, as an ε diplotype (R-APOE-1), so its tier A locus is the one locus that can say none of the things the report groups and orders by.

What already fits. The key includes trait_efo_id, so one row per (diplotype, trait) is legal: an Alzheimer's row and a lifespan row per ε pair, which is how the plan's two framings coexist.

Shapes, priced.

  • Widen DiplotypeRow with the general annotation columns: negatives, category, priority, flags, and possibly actionability. Full price each, minor-legal; RM70 is the precedent for carrying a VariantRow column to a PGx table. VariantRow itself calls these axes general ("any variant finding may carry them"), so this is not a foreign domain's columns on a PGx table. Each is three touch points, plus the diplotype parquet and reverse.
  • Author APOE as rs429358/rs7412 genotype rows in variants.csv. Refused: a per-SNP row cannot say ε2/ε4, and the plan's own rule is to score APOE once.
  • README prose. Drops the axes out of the data entirely.

To design. Which columns, and whether the home RM323 decides for locus-level facts also reaches a gene-pair subject (it does not if that home is keyed on variant_key).

RM336 — a DOI written into pmid parses as five or six PubMed ids, and the literature pass looks each one up

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §3 items 18 and 23, §5 A2) · Owner format (spec.validate_pmid_cell) · Motivating case longevitymap v2 requirements §6.3 ("pmid, or doi for preprints") · for longevitymap v2 · related RM50, RM263, ROADMAP § StudyRow.pmid required + PMID-shaped

Widened 2026-11-04 by the maintainer, after the second measuring run: "fix the error class on all tables". The pmid/doi pair applies to every table where a row cites, not only studies.csv:

  • a DOI is never written into pmid;
  • pmid accepts the NONE sentinel, which makes doi mandatory and validated.

Tables that cite with a pmid and no doi today gain doi:

  • pharm_variants.csv (RM132's pmid);
  • the binning kinds (RM47's pmid);
  • the derived gwas_effects.csv (half price);
  • the two new citing tables: the meta-table and RM335's model-organism table.

The run measured 6 preprint-only HLA alleles and 17 PMID-less model-organism rows. The roster of citing tables is derived (the compiler's _CITING_TABLE_KINDS), never hand-kept.

Preprints, decided 2026-11-04 by the maintainer after the final run (17 v2 studies are DOI-only). DOIs stay in doi and never in pmid. pmid accepts a typed sentinel (NONE or similar; the exact spelling gets its P5 audit). That sentinel makes doi the mandatory substitute, and the validator then checks the DOI instead. A DOI written into pmid is still refused. pmid stays required, because the cell is present, so this is minor-legal (P8). RM263's DOI-to-PMID lookup still fills a real PMID wherever PubMed indexes the paper.

Decided 2026-11-04 by the maintainer: a refusal, like RM50's PMCID arm. validate_pmid_cell refuses a cell whose only token is a DOI, and names it. Principle 3 says a module that validated keeps validating, so before the build, check the published modules (the registry's catalogue and the reference examples) for a DOI in pmid. None found: the refusal breaks no published module. Any found: they go back to the maintainer before the arm ships.

Reproduced 2026-11-03. StudyRow(rsid="rs429358", pmid="10.1101/2025.03.01.640000") validates. extract_pmids returns ['10', '1101', '2025', '03', '01', '640000'], and doi:10.1038/s41586-019-1234-5 gives five. enricher/src/just_dna_enricher/literature.py iterates extract_pmids(study.pmid), so the literature pass checks PubMed records 10, 1101 and so on as the row's citations. A preprint-only row is exactly where an author writes this, because pmid is required and the paper has only a DOI.

Same class as RM50. RM50 gave validate_pmid_cell a PMCID arm, refusing a cell whose only id is a PubMed Central number and naming it. A DOI is the next registry whose digits read as PMIDs.

The decision. A refusal arm like RM50's makes cells that shipped modules may already hold invalid (P3/P8), while a new warning code is minor-class (RM308's rule). The real fix for preprints stays the 1.0 doi-first demotion. RM263 is the route from a DOI to its PMID.

Residuals RM349

The published-module scan, run before the refusal was built (2026-11-04). The prod registry, all 24 modules and every one of their 47 versions (inputs, parquets and derived sidecars, fetched read-only from module-registry.just-dna.life): 138 files carry a pmid column, 1,792,856 cells, no DOI and no NA/n/a/-/none/null spelling anywhere. reference_examples/: 18 files, 667 cells, none. So the refusal breaks no published module, and the decision's gate was met.

What shipped.

  • spec.validate_pmid_cell gained a DOI arm between the PMID success and the PMCID arm: a cell whose only identifier is a DOI is refused, naming it and pointing at doi, NONE and just-dna-enricher hint citation --doi. extract_pmids skips digit runs inside a DOI_PATTERN span, as it skips a PMC id's, so 21551363; 10.1101/… still yields the PMID and a DOI yields nothing. The generic refusal keeps its leading phrase and appends a pointer to NONE.
  • pmid accepts spec.PMID_NONE = NONE, exactly. The rule that it makes doi mandatory is spec.check_citation_pair, applied through the mixin spec.CitationPair, which also carries the doi cell check (spec.validate_doi_cell, StudyRow's old message, moved). The pmid grammar stays on each model, because required differs.
  • CitationPair on StudyRow, MeasureBinRow (all four binning kinds), PharmVariantRow and GwasEffectRow; doi? (since 0.8.0) on the last three. GwasEffectRow.pmid now runs validate_pmid_cell, which its description had always promised; doi joined GWAS_FACT_FIELDS, and an unset one moves no fact signature (None is dropped from the hash). Compile, parquet and reverse needed no edit: all four tables go through the model-driven writers.
  • The duplicate-citation check keys a NONE row on its DOI token, lower-cased (spec.doi_key), so two preprints on one variant are two citations and the same preprint twice, in either spelling, still warns, naming the DOI (spec.cited_as, which the two other study findings printing a pmid use too).
  • Found in review, and the same item: a quote on a NONE row sat in none of the literature pass's counts, so verification.json said "no provenance quote or regex on any citation" about a module carrying one. LiteratureResult.quotes_without_pmid counts them; alone they make the record an unsupported skip, beside others they are a clause in its detail. The same held for existence: a module citing only by DOI was refused as "no citations", and past that would have recorded citation_existence as ran(0, 0); citations_without_pmid counts DOI-only citations on every citing table, and the record is unsupported when they are all there is.

P5 audit. doi is StudyRow.doi's name for the same fact on a finer-grained row; it collides with nothing on those models and is not in RESERVED_NAMES_0_4; LiteratureRow.doi is the registry's answer about an article, a different table. NONE is upper case so it is not Python's None (the unknown arm everywhere else) or a word of a free-form reference, and it is the one spelling: NA/n/a/-/none stay refused. The meta-table and RM335's model-organism table (other builders) reuse CitationPair.

Tests. schema/tests/test_pmid_doi_pair.py (the reproduction refused naming the DOI on every citing model; NONE with and without doi; the other spellings' pointer; extract_pmids on both); compiler/tests/test_citation_pair.py (an equality over reference._ALL_MODELS between models with a pmid and models carrying CitationPair and doi, LiteratureRow the one named exemption, with _CITING_TABLE_KINDS inside it; round trips with NONE+doi on studies.csv, repeat_alleles.csv and pharm_variants.csv, and a gwas_effects.csv doi reaching its parquet; the duplicate key); enricher/tests/test_literature_doi_cells.py (the pass's lookup list holds only the PMID beside a DOI, and nothing for NONE or a DOI-only cell; a NONE row's quote is reported, never read as no quote). Each new arm was broken once and its test went red.

RM304 — a vrs_id does not say which VRS minted it, and VRS 2.1 moves some insertion ids

Decided 2026-11-04 by the maintainer: both, a module-wide pin and a per-row version. The manifest pins the VRS version the module's ids are meant to be minted under, and each vrs_id carries the version that minted it, beside it. A row whose version differs from the pin is the one to invalidate against, with its own reason, never the mismatch error (question 2). A per-row column alone cannot say which version is intended; a pin alone cannot survive a merge-not-clobber table mixing runs.

0.8, decided 2026-11-03. Taken into 0.8 by the maintainer, with the rest of the indel-placement fixes (RM304, RM267, RM270, RM292, RM305). The status line below predates that decision.

Severity high · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (PROPOSAL_0_8_PT2 §3 item 20, §5 C1), landed before RM270 · Owner format (where the version is recorded) + enricher (the minting) · Motivating case GKS_SURVEY.md §0 findings 2 and 3, 2026-09-28

Residuals RM270

RM270 carries the minted per-ALT vrs_id onto the variant parquets, and with it this item's per-row version (PROPOSAL_0_8_PT2 §5 C5, "with C1's version"). Until then no compiled parquet carries an id we minted, so neither does any parquet carry the version, and reverse_module (which rebuilds resolution.csv from the parquets) drops both: RM241's residual, which RM270 already names. Lifting the ga4gh.vrs<2.4 cap is the liaison's, once vrs-python releases rle_subunit_mode; it is not a remainder of this item, which keeps the cap by design.

What shipped (2026-11-04). The premise of fact 1 was half wrong, and the build starts from the correction. "Nothing in the repo records the version" came from grepping vrs_version. The per-row half had shipped in 0.5 as ResolutionRow.vrs_spec: every row mint_resolution_rows mints has been stamped "2.0" since then. Nothing read it, and its description said the allele id does not drift, which VRS 2.1 refutes. So the per-row column is vrs_spec, re-described, and no vrs_version column was added to resolution.csv: two columns for one axis is the P5 failure, and P3 would have kept both for the rest of the major. The name vrs_version went to the pin, as the proposal named it.

  • The pin, manifest.compilation.vrs_version: str | None. No manifest.resolution block exists; the resolution-table facts live in Compilation (resolution_signature, vrs_alleles, vrs_alleles_identified), so the pin sits beside the VA coverage counts. Its value is vrs.VRS_SPEC_VERSION ("2.0"), the rule the compiler's stdlib implements and verifies against, when at least one allele in resolution.csv carries an id, and None otherwise. The compiler cannot import ga4gh.vrs (P2, Goal 2), so the pin is the rule it can check, and the verify pass compares every row against the same constant.
  • One grammar for both sides, just_dna_format.vrs.vrs_spec_release. The library spells its version "2.0.1" and every table carries "2.0"; a raw compare would have reported every row of every enriched module. The id rule changes at a VRS minor, so a version is compared at major.minor. Unstated (None, blank) answers None, the unknown arm; an unreadable value comes back untouched, equal to no pin and quoted whole in the warning. No validator was added to vrs_spec: that would refuse a cell a 0.5 module may hold, and the comparison already reports it.
  • The minting call reads ga4gh.vrs.VRS_VERSION, the attribute vrs-python publishes for the VRS spec it implements ("2.0.1" under ga4gh.vrs 2.3.3; its __version__, "2.3.3", is the library's own release and says nothing about the rule). vrs.MINTER_VRS_VERSION = vrs_spec_release(VRS_VERSION) = "2.0" is stamped on every row the pass mints. An already-recorded id keeps its vrs_spec, an empty one included: that run did not mint the id, so it may not claim its version (@currency-cannot-be-a-column). A recorded version other than the minter's is counted in MintResult.version_differs and printed as vrs_version_differs: … by enrich and vrs mint.
  • The verify pass. RM304 question 2 named "the enricher's VRS verify pass". There is no such pass: the enricher never recomputes a stored id, and the pass that does is the compiler's _verify_vrs_ids (run by validate and compile). The reason is reported at both places that see a stored id: there as warning code vrs_version_differs, and at the enricher's already_present branch as a CodedWarning with the same code and words. In _verify_vrs_ids the version is a fact about the row, reported beside each allele's own verdict, never instead of it. The first build put it instead, skipping the recompute, and the code review caught what that did: a substitution needs no normalization and this tier never recomputes an insertion, so the skip removed no false mismatch, and writing 2.1 (or garbage) into vrs_spec silenced the corruption error on a substitution. Now: within the pin's major a substitution that recomputes differently is still the corruption error. Only under another major (1.3, where the digest serialization differs) is the difference counted in the version line instead. An unreadable version is quoted, and the row is verified as unstated. An indel under another version stays in vrs_id_unverifiable too. A warning in both modes, actionable because re-minting clears it.
  • Stamped by route. An all-substitution row is stamped with the format tier's VRS_SPEC_VERSION, the rule its stdlib minted under. A row with any normalized allele gets the library's version. They are one minor today, so nothing written changes; stamping by route keeps the stamp true if they split.
  • Tests. compiler/tests/test_vrs_version.py: the reason beside a verified id; a same-major corrupt substitution still refused; a cross-major one counted, against a same-version control that stays a mismatch error; an indel counted in both lines; rows sharing a key counted as rows; patch spellings and whitespace that are not a difference; the unreadable arm, which still refuses a corrupt id; a table with no vrs_spec column that still verifies and still refuses a tampered id; both modes through compile_module, with validate_spec agreeing; the pin present, and absent with no table or no id; a compile → reverse → compile fixed point. enricher/tests/test_vrs_version.py: the minter's version read off the library; the library's minor equal to VRS_SPEC_VERSION (red the day an upgrade implements another minor); a minted row stamped; a recorded row with another version reported and left alone; one with none left unstated; and the pinned insertion rs72613567 (4-87310240-T-TA → ga4gh:VA.Jml7SNku3QQBCVIj78BGiFvR21bNkos7) behind JUST_DNA_NETWORK_TESTS=1, run once against the live proxy and green. Mutation runs (the version arm off, the pin unconditional, the enricher's count off) each turned their tests red. A features/ scenario grounds the code.

Two facts, both measured in the survey.

  1. The id carries no version. For BRAF V600E (chr7:140753336 A>T) three ga4gh:VA. ids exist: ours under VRS 2.0 (…Otc5ovrw…), vrs-python's VRS 1.3 computation (…fZiBjQEo…), and the ClinGen Allele Registry's (…HaPTmn-r…, a VRS 1.x shape). All three are well-formed and none says which spec produced it. Nothing in the repo records the version: grep -rni 'vrs_version' over schema/, enricher/ and SCHEMAS.md finds nothing.
  2. VRS 2.1.0 (2026-09-01) changes ambiguous-insertion normalization: it now picks the smallest repeat-unit factor where 2.0 picked the greatest, and that moves the digest of affected alleles. vrs-python has not implemented it. Both 2.3.3 (ours) and 2.4.0a4 still iterate the factors descending, and the change is open as vrs-python issue #637. Today everyone we compare against mints 2.0.x ids: our enricher, ClinVar-GKM and gnomAD. The first vrs-python release that ships the 2.1 rule will make a fresh enrich mint a different id for some insertions than the one stored in resolution.csv and the one gnomAD publishes, with nothing to say why.

Why it is filed before RM270. RM270's candidate repair carries the enricher's vrs_id onto the parquets as the spelling-independent join key. A key whose derivation silently changes under a dependency upgrade is the failure RM270 exists to remove, moved one layer down.

Mitigation shipped separately, the same day. ga4gh.vrs is capped <2.4 in the enricher, so no upgrade can change the rule unannounced. The cap is a stopgap. It is lifted by this item, never quietly: once the version is recorded, an upgrade becomes a declared re-id instead of a silent one.

Open questions.

  1. Where the version lives. It could be one run-level fact on resolution.csv's provenance or in the manifest (every id in a run is minted by one library), or a column beside vrs_id. Both spellings of one allele can coexist only in the column form. The run-level form is cheaper, and a merge-not-clobber sidecar mixing runs is the case that breaks it (@currency-cannot-be-a-column asks which run writes it).
  2. What the verify pass does on a version mismatch. Recomputing a stored 2.0 id under 2.1 gives a mismatch that is neither corruption nor a wrong event. It needs its own reason, never the existing mismatch error (@vrs-three-outcomes).
  3. A pinned insertion. The ground-truth tests pin substitutions against gnomAD. rs72613567 (4-87310240-T-TA → ga4gh:VA.Jml7SNku3QQBCVIj78BGiFvR21bNkos7, present in ClinVar-GKM) is the insertion to pin, behind JUST_DNA_NETWORK_TESTS=1 since indel minting reads the SeqRepo proxy. The test is what turns a future rule change red.

Addendum, 2026-11-04 (the liaison, docs/UPSTREAM_GA4GH_VRS.md). vrs-python PR #665, still open, adds normalize(rle_subunit_mode=...) with a default of LARGEST, the VRS 2.0 rule. Its text says the vrs/2.1 branch will default to SMALLEST. Through 2.4.0-a6, no digest we compute moves (the liaison diffed and measured it). Once the keyword is released, the cap can be lifted with the id rule chosen on purpose: our call passes the mode explicitly, and question 1's recorded version says which rule minted each id.

RM342 — the manifest does not record the toolchain that wrote the bytes, so a digest that moves cannot say why

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (a new optional manifest field, a new exception subclass, and a Principle 4 amendment), PROPOSAL_0_8_PT2 §3 item 19, §4 question 7, §5 block A1 · Owner format + compiler + enricher · Motivating case RM341 · related RM304, RM341

Residuals RM352

What shipped. Compilation.toolchain: dict[str, str] | None, stamped at compile as {"polars": pl.__version__, "python": platform.python_version()} of the running process, outside artifact.digest like compiler_version (the manifest is not one of the Merkle root's files). None on a manifest compiled before 0.8. The format tier owns the one comparison, manifest.toolchains_differ, three-valued (Kleene: a shared library at two releases is True whatever else is unknown; a library only one side names is absent, never different), and the reason constant TOOLCHAIN_DIFFERS. The two places a fresh compile meets a recorded digest use it: the publish collision check raises ToolchainDiffersError, a subclass of PublishCollisionError with reason, published_toolchain, local_toolchain and the tri-state content_unchanged (the reason names a co-occurring difference, not a proven cause), and the CLI prints TOOLCHAIN DIFFERS from a branch ahead of the collision's; the release sweep's ModuleDelta carries toolchain_differs and bytes_reason, and SweepMeasurement.moved_under_other_toolchain lists the modules. Either toolchain unrecorded, or the same toolchain with a different digest, keeps the old outcome. The publish still refuses unless --force: the reason changes what the refusal says, not whether the versioned path's bytes are protected. compilation.toolchain joins EXCLUDED_MANIFEST_FIELDS, since it moves whenever the install does. verify_manifest and needs_recompile are unchanged: the first re-hashes files on disk and the second compares two version strings, and neither holds a second toolchain. Principle 4's last sentence and Principle 7's closing parenthesis were amended together (the why is in CONSTITUTION_AMENDMENTS_HISTORY.md). Tests: schema/tests/test_toolchain.py, compiler/tests/test_toolchain.py, and the RM342 block in enricher/tests/test_upload.py.

Where the toolchain reason fires, corrected 2026-11-04 (the lead's PT2 §4 question 7, accepted by the pm seat). verify_manifest re-hashes files and never recompiles, so it cannot see a toolchain. The reason toolchain_differs therefore fires where a fresh compile is compared with a recorded digest: the publish collision check and the release sweeps. This keeps the maintainer's intent: an explainable difference is never reported as corruption.

Decided 2026-11-04 by the maintainer.

  • One toolchain block: a single optional field in manifest.compilation holding a small map (e.g. {polars: 2.1.0, python: 3.13.1}). A library added later is a new key, not a new field.
  • verify gives a toolchain difference its own reason. "Bytes differ, toolchain differs" is distinct from corruption and never the plain mismatch error (@vrs-three-outcomes).
  • Principle 4 is amended. Reproducibility is pinned via compiler_version, the recorded toolchain and the resolved reference. The why goes in CONSTITUTION_AMENDMENTS_HISTORY.md, and the lead lands the amendment with the item.

Ready to build; the polars 2 lock moves into 0.8 with it.

0.8, decided 2026-11-04, on the lead's list, "not ready": its open questions (one field or a toolchain block; whether verify reports a toolchain mismatch as its own reason; whether Principle 4 needs an amendment) are settled in the 0.8 interview. The polars 2 lock moves into 0.8 with it.

Why it is filed. polars stays uncapped (RM341, the maintainer, 2026-11-04). From 2.0 the parquet bytes name the polars release that wrote them, so two installs of one compiler_version mint different digests for equal content, and nothing in the manifest says which polars wrote which. The liaison's adoption map, item 3: record the polars version beside compiler_version in manifest.compilation, as an optional field. That is additive and minor-legal. The alternative, deciding in P4 that the digest names the toolchain, would be a charter amendment.

Open questions. Whether the record is one manifest field or a toolchain block (polars, arrow if it ever appears, Python); whether verify reports a digest mismatch whose recorded toolchain differs from the running one as its own reason (@vrs-three-outcomes asks for that); and whether P4's sentence on reproducibility needs an amendment once the toolchain is recorded.

The 0.8 PT1 build round

The bugfix round PROPOSAL_0_8_PT1.md decided on 2026-09-29, built on the 0.8 branch in the proposal's order. Newest first.

RM28 — the combination half: the meta-table

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — the combination half, taken into 0.8 on 2026-11-04 (PROPOSAL_0_8_PT2 §3 items 1–8, §5 B1 steps 1–5; step 4, the study-orphan widening, in wave 3) · Owner format (just_dna_format.meta) + compiler (compiler/meta.py) + enricher (the rsID currency pass) · Motivating case KL-VS buffering in APOE ε4 carriers (longevitymap v2), CPIC's six gene pairs, Lewis · related RM323, RM324, RM327, RM330

Residuals RM327 · RM330

What shipped. meta.csv, one authored table: a row maps a member set to a finding and/or the per-locus facts. One grammar for every member, table[column=value, …] over variants, diplotypes, pharm_variants and allele_function, members joined by & at bracket depth 0; conditions AND-ed, = on a list column meaning contains, and a member existential inside a combination. The key is the sorted members plus trait_efo_id plus sex plus drug (2026-11-04: drug added at the maintainer's default; see below), so A & B and B & A are one key, refused as a duplicate. Negation, OR, ranges, joins across tables and selectors over studies.csv are refused, each by its own message; there is no bare-rsID shorthand. The compiler expands every member into the rows it matches and writes meta.parquet (the selectors verbatim for reverse, the matches, replaces) and meta_resolved.parquet (each row a one-member meta row reaches, with its facts after precedence), so a consumer evaluates no rule (P1). A matching combination replaces the findings of exactly the rows it lists. The manifest records every member's match count (meta_selectors), and a member matching nothing warns (meta_selector_matches_nothing). The enricher's rsID currency pass asks dbSNP about every rsID a member names, so one variant under two keys (IL6R's rs8192284) is caught where NCBI is the oracle.

The study-orphan widening (B1 step 4), shipped 2026-11-04 in wave 3, after the StudyRow batch. A study's variant is carried, so not study_variant_orphan, when it is a variants.csv row's, a defining variant in haplotypes.csv, or the variant of a variants.csv / pharm_variants.csv row a meta member reached (compiler/meta.py member_variant_rows, read off build_meta's matches, so a selector covers exactly what it matched). APOE scored only as diplotypes, longevitymap v2's R-APOE-1, draws no orphan for its 14 study links on rs429358/rs7412 (compiler/tests/test_study_orphan_widening.py). The check still runs only beside a variants.csv, as before (until the decision below); the message keeps its pinned prefix.

2026-11-04, the lead's decision (reversible until the cut; keeping the gate was the rejected alternative). pharm_variants.csv is a fourth arm: a study on a pharm_variants.csv row's variant is not an orphan whether or not a meta member reaches it. The if variants: gate is gone, so a diplotype-only or PGx-only module is checked too, and duplicate_study_citation, computed in the same pass, runs there with it (@roster-is-as-wide-as-the-tables-it-reads). An arm whose file is present but loaded no row withholds the orphan half, since what the module carries is then unknown; the gate had withheld that case for variants.csv by accident. Measured on the 16 reference_examples/ before and after: none gains or loses a warning (fmr1_cgg_repeat, the one with studies.csv and no variants.csv, names no variant on any study row). The meta arm now reaches only rows the two table arms already carry; it is kept, not removed, so a future member table that is not an arm stays covered.

What stays open, and where. RM28's open section in ROADMAP_0_8.md keeps only the predicate half's remainder: open-world negation, OR and trans phase, all out of bounds by the maintainer's decision. RM327 computes tradeoff over the per-trait rows this table now holds. RM330's study stratum is the StudyRow half; its sex condition shipped here.

2026-11-04, the lead, under the default offered to the maintainer (recommended, no objection): drug joins the key. reference_examples/cpic_gene_pairs found that CPIC answers one TPMT × NUDT15 phenotype pair once per thiopurine, and the key (members_key, trait_efo_id, sex) refused the second drug's row as a duplicate, so the example carried azathioprine only. MetaRow.drug (optional, free text as DiplotypeRow.drug, the drug the statement is about) is now the key's fourth column and a second scope axis beside sex: a drug-scoped row outranks the same key without one, for that drug, and meta_resolved.parquet's grain is (row reached, sex, drug), every combination of the stated values. The example now carries all three thiopurines.

RM323 — a fact about a locus has no authored home, so every per-locus axis is copied onto each genotype row and nothing checks the copies agree

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor, taken into 0.8 on 2026-11-03 as a priority, built as the meta-table (PROPOSAL_0_8_PT2 §3 items 1–8, §5 B1) · Owner format (just_dna_format.meta) + compiler (compiler/meta.py) · Motivating case longevitymap v2 requirements §4.2 · for longevitymap v2 · related RM28, RM322, RM324

Residuals RM333 · RM346 · RM327

Built 2026-11-04 on 0.8, under "go with C". The per-locus facts are columns of meta.csv only: tier, age_of_action, age_of_action_confidence and flags. A single locus's facts are a one-member row (variants[variant_key=…]), a named allele's are allele_function[gene=…, allele=…], and nothing is copied onto a genotype row, so no two copies can drift. The compiler resolves them per row reached into meta_resolved.parquet (most specific wins; incomparable disagreeing rows withhold the column), which is what makes APOE's ε2/ε4 break a withheld cell rather than a silent pick. What stays elsewhere: causal and effector confidence are not authored (cut 2026-11-04), their inputs arrive through RM333's Open Targets lane; the normalized machine shape is RM346's (1.0); tradeoff over the per-trait rows is RM327's.

Cut 2026-11-04 by the maintainer, after the final measuring run (probes/LONGEVITYMAP_V2_SHAPE_AUDIT.md §3): causal and effector confidence are not authored. The parquet carries their raw inputs: the fine-mapping posterior, the coding consequence, the L2G score and coloc. The C1–C4 / E1–E4 labels are v2's rubric, i.e. policy, so they live in v2's README and are computed by the consumer, as "evidence role" is. The run computed them on 67 of 75 rows. The 8 hand-curated inputs go in overrides.csv as corrections to the derived inputs. The meta-table keeps tier, age_of_action and its confidence, and gains flags: the maintainer chose it for parity, so every kind of member can carry tags the way variants.csv rows do, such as ap:<strength> and hallmark:…. also_in:<module> stays prose.

Final, 2026-11-04, the maintainer: "go with C". This supersedes both decisions below. The per-locus facts (tier, causal and effector confidence, age of action and its confidence) are columns of the meta-table only. They are never repeated on variants.csv or diplotypes.csv.

  • A single locus's facts are a meta-table row with one member and no finding.
  • A member is an item of a single-statement table. It may be a locus-level reference (a variant_key alone), for a fact that does not depend on the genotype, or a full row's key.
  • APOE ε2 and ε4 are each a one-member row naming their allele.

One new table holds facts and combinations. Priced at about 20 (a new table at about 10, plus five fact columns and the finding's columns), against about 30 for a separate fact table or for facts repeated on the existing tables. The maintainer's standing rule from this decision is in RM28: weight toward fewer entities.

Re-decided 2026-11-04 by the maintainer: no new fact table, and no subject kinds. This supersedes the (subject_kind, subject) key below.

The per-locus facts become columns on the single-statement tables that already exist, such as variants.csv and diplotypes.csv, and on the meta-table's rows. The maintainer: "Authoring surface is human centered. If it were a db it'd be 10x more tables, because many columns are duplicated across individual-loci-type tables and properly normalized db resolves this by pairing adapters. Humans have trouble reading such." So the authored layer stays denormalized on purpose. Compilation may normalize it, which is RM346 (1.0).

What this means for a value that differs between rows. A fact sits on a statement (one genotype row, one diplotype row), so it is a property of that statement. Two rows of one locus may legitimately differ: APOE's ε2/ε4 and ε3/ε4 rows each carry their own age-of-action confidence, which dissolves the ε2 versus ε4 break the archive check found. So no agreement warning is built. When a locus's facts are meant to be identical on every row, that is the author's to keep, and the 1.0 normalized shape will show any disagreement as two values. (Superseded by C the same day: facts are not repeated on rows, and the key rule under RM28 decides what counts as a disagreement.)

Reopened 2026-11-04 by the maintainer: "why can't each part of the combination live in its respective table, and the combination plus its finding in the meta-table? A new table is the most expensive thing." The decisions below stand until the analysis is answered.

Decided 2026-11-04 by the maintainer: a per-locus fact table keyed (subject_kind, subject). It has three kinds:

  • variant: a variant_key;
  • gene: a symbol, for gene-level facts such as LoF burden;
  • haplotype: (gene, allele name), resolved against haplotypes.csv or RM334's HLA allele table.

It deliberately has no region or locus kind. A combination of several subjects, each in a stated genotype state, is defined by RM28's meta-table. Since 2026-11-04 that is also in 0.8, and each combination becomes a fourth subject kind here. Facts about a combination therefore live on this table too, never on a second one.

What the shape was tested against. A subagent checked it against v2's full research archive (data/input/4bf03886-….zip, the seed's 161 loci): 121 fit, 37 strain, 3 break. All three breaks are named alleles, and the haplotype kind holds them:

  • APOE ε2 and ε4 carry different age-of-action confidence;
  • HLA-B*57:01 and HLA-DRB1*15:01 carry facts that belong to the allele, not its tag SNP.

The strains need no new key, but they do need three authoring rules, stated in the proposal:

  1. Which study's fine-mapping posterior sets a causal-confidence level (the seed uses the maximum).
  2. A fact measured on a proxy is marked as such (RM331's columns).
  3. A European-only tier is scoped by ancestry (RM328's derived flag), never transferred.

What was confirmed. VariantRow keys on (variant_key, genotype). v2's tier, causal confidence, effector confidence, age of action, outcome profile and animal support describe the locus, not a genotype, so the plan writes each as a flags token on all three genotype rows. Nothing compares the copies, so an edit to one row leaves the locus saying two things. annotations.parquet is the per-variant table, but it is derived (keyed on the variant-effect pair) and an author cannot write it.

Shapes, priced, neither picked.

  • Typed optional columns on VariantRow, repeated per genotype, plus a new warning code when the rows of one variant disagree. Full price per column; the code is minor-class (RM308's rule).
  • A locus table keyed on variant_key that the per-locus columns live on. Full price, a new table kind. It joins the frozen identity, so nothing is restated. It does not reach a diplotype subject (RM322), and APOE is the module's lead locus.

The decision is where the per-locus axes live. RM324's tier, RM326's derived outcome profile and RM329's age-of-action class all land wherever this decides.

RM324 — there is no evidence-tier column, so the axis that gates visibility is a flags: tier:A token

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor, taken into 0.8 on 2026-11-03 as a priority · Owner format · Motivating case longevitymap v2 requirements §4.1 · for longevitymap v2 · related RM323, RM188 (axis 5), RM294

Residuals RM294

Built 2026-11-04 on 0.8. One tier column on meta.csv (open text) and one tier_scale: in module_spec.yaml (free text, the weighting: pattern), copied into the manifest and listed in REVERSE_RECONSTRUCTED. A tier cell in a module with no tier_scale is refused in validate and compile (@weight-has-no-unit); values are not checked against the scale. A source's own grade beside the module's tier stays RM294's (0.9).

Placement updated 2026-11-04. The one tier column goes on the meta-table only (RM323's final decision, "go with C"). The scale is still declared once per module.

Decided 2026-11-04 by the maintainer: one tier column, with the scale declared once per module. The tier column goes on RM323's fact table. The module names the scale it grades on once in module_spec.yaml, as weighting: names its scale. A module therefore holds one scale, and a source's own grade cannot sit beside the module's tier in this column. RM294 (STRchive's grade) moved to 0.9 for that reason.

Need. v2's tier A–D decides what is scored and what a reader sees by default. The plan carries it as flags: tier:A and derives priority from it. That makes priority (described only as "priority level override") a second spelling of the tier.

What not to reuse. evidence_level is PharmGKB's closed 1A–4 on the PGx tables. Writing a module's own A–D scale into it puts two instruments under one name (P5).

Shape. A value plus the scheme it is measured on, refused without the scheme: the 0.7 StudyRow.confidence / confidence_unit pair is the precedent, and @weight-has-no-unit is why. Full ×2. Where it lives is RM323's decision. Design it with RM188's axis 5 (a salience separate from clinical severity; dna-engine carries a tier) and RM294 (whether a source's evidence grade travels into a module), since all three are one column family.

RM288 — two snapshot builders and the PGx drafter make every caller enumerate their exception family, a question RM101 named and left in a test's exemption block

Severity low · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-29 (PROPOSAL_0_8_PT1) (a public exception base) · Owner enricher (cpic_build, pharmvar_build, pgx_draft) · Motivating case RM101's exemption block in enricher/tests/test_pass_exception_contract.py, "a real question and a wider one than this item", found unhomed by the 2026-09-27 postmortem sweep (P14) · related RM101, RM96, @client-exception-contract

Residuals none

RM101 made every enrichment pass raise one documented type. It exempted cpic_build.build_snapshot, pharmvar_build.build_snapshot and pgx_draft.draft_gene by name. Their callers spell the family out (except (CpicError, CpicBuildError), except (CpicError, *_DRAFT_PRECONDITION_ERRORS)). That works, but it is the list shape: a caller has to know which types to name, which is the drift RM96 was the lesson for. The only record of the question is the comment in the test's exempt set.

Confirmed on 2026-09-27. The three entries are still exempt, and no ROADMAP file names the question.

What to decide. Whether each surface gets one catchable base (a subclass relation over the existing types, which makes a caller's except order load-bearing: @client-exception-contract's AST guard applies), or whether the list shape is kept on purpose and the exemption comment is rewritten as a decision rather than a deferral. A new public exception base is new surface, so building it is a minor.

The first incident, 2026-09-29: RM310. caches._rebuild_cpic named one of CPIC's two error types and a 503 escaped cache rebuild. RM310 patched that one list and left the mechanism here.

What shipped. The entry's second option, decided by PT1: a callee-owned tuple. cpic_build.ERRORS = (CpicError, CpicBuildError, ImportError, OSError), pharmvar_build.ERRORS = (PharmVarError, ImportError, OSError), pgx_draft.ERRORS = (CpicError, DraftError, EnrichmentError, LicenseRefusal, OSError), each beside a comment saying why it is a tuple. Every caller now catches the module's tuple: caches._rebuild_cpic/_rebuild_pharmvar, the cpic build/pharmvar build commands and draft. The CLI's shared _DRAFT_PRECONDITION_ERRORS stays, since the CIViC drafter uses it too, and pgx_draft.ERRORS names those two members itself.

Found while building, and the same item: draft_gene raises LicenseRefusal on a commercial declaration, and the draft command's list did not name it, so draft --use commercial escaped as a traceback. The tuple includes it because the surface raises it, which is what the stub test asserts.

Tests. test_builder_error_families.py: an AST walk finds every try whose body calls one of the three surfaces (by module attribute or imported alias) and asserts a handler catches that module's ERRORS; a second walk refuses CpicBuildError named bare anywhere but its own module. A mutation run (the cache adapter's handler put back to a spelled list) fails both. Each surface is then driven through its real code with stubs, and everything it raised is a member of its tuple: CPIC's 503, PharmVar with no key, and the drafter's licence refusal, unreadable build declaration and client outage. The three stay in test_pass_exception_contract.py's exempt set, with the comment rewritten as this decision. RM310's CACHE_LANES walk stays green.

RM283 — nothing notices the ClinPGx archive the lane builds from going quiet, which is how it served a fourteen-month-old snapshot

Severity medium · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-29 (PROPOSAL_0_8_PT1) · Owner enricher (clinpgx_build, its release.json) · Motivating case RM175's "that gap is the honest remainder", left unfiled, found by the 2026-09-27 postmortem sweep (P10) · related RM175, RM173, @currency-asks-the-source-not-the-cache

Residuals won't fix — the URL audit needs a browser, because every ClinPGx HTML route is a JavaScript shell, so it stays a manual rebuild step

RM175 found the lane building from clinicalAnnotations.zip, retired upstream and frozen on S3 for fourteen months while still answering 200. It shipped a narrow guard, refusing the retired member names, and listed three wider ones it did not build: audit each default URL against the source's listing, record the S3 Last-Modified beside CREATED_*.txt in release.json, and fire when one archive of a multi-archive source is much older than its siblings. It closed with "Nothing built here would notice summaryAnnotations.zip itself going quiet, and that gap is the honest remainder", and gave that remainder no number.

Confirmed on 2026-09-27. clinpgx_build records CREATED_*.txt only. It reads no Last-Modified and compares nothing across archives.

What to build, cheapest first. Record Last-Modified in release.json. That is a new field in a published snapshot's description, so it is minor-class. Then a finding that compares it with the sibling archives' dates on the same fetch, reporting and never refusing (a source going quiet is not a strict matter, @a-source-recuring-is-not-a-strict-matter). The URL audit needs a browser (RM175's trap: every ClinPGx HTML route is a JS shell), so it stays a manual step written into the lane's rebuild runbook, not machinery.

What shipped. clinpgx_build.probe_archive_dates (HEAD the lane's archive and SIBLING_ARCHIVES, following the 303, reading Last-Modified; every failure leg leaves that archive None, since the probe gates nothing) and staleness_finding (a sentence at STALE_AFTER_DAYS = 180 or more behind the newest known sibling, naming any sibling not asked; withheld when there is nothing to compare). build_snapshot(archive_dates=…) writes one key, archive_last_modified, beside dataset and never as it, and returns the dates and the sentence on the result. The two download paths (cache rebuild and clinpgx build) probe after downloading; a build from a local archive writes no key. Tests with stubbed HEADs: fresh, 181 days behind, a sibling missing its header, a sibling that fails, a build that asked nobody, and RM175's incident as the named fixture — the dates S3 served on 2026-09-30, clinicalAnnotations.zip 2025-07-05 against variantAnnotations.zip 2026-09-05, 427 days.

RM263 — a DOI has no route to its PMID, although StudyRow.pmid is the required half

Severity low · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-29 (PROPOSAL_0_8_PT1) · Owner enricher (lookup, literature) · Motivating case S113, the reporter's second candidate fix

Residuals none

What was confirmed. A curator holding only a DOI (what a paper's landing page gives you) can now learn which paper it is (RM262), but not its PMID, and StudyRow.pmid is the column the schema requires. RM50 built the same route for a PMC id through NCBI's converter; a DOI has none. Europe PMC's search answers it: DOI:"10.1038/ng826" returns PMID 11788828, measured 2026-09-25, and covers all of PubMed. NCBI's converter also takes DOIs but only answers for articles in PMC, and Enattah 2002 is not in PMC, so it would miss exactly the paywalled case.

The shape is RM50's, and the open question is the second title. The resolved PMID comes back as an advisory (applied=False, refusal="redundancy_bearing"), never a fill, since pmid is redundancy-bearing. Then PubMed is asked which paper that PMID is, as _check_pmcid does. That gives a DOI-only lookup two titles, Crossref's and PubMed's, and whether a disagreement between them is a warning or only two info findings side by side is the decision still to make. EuropePmcClient has no DOI search today; one method.

What shipped. EuropePmcClient.pmids_for_doi(doi) searches DOI:"<doi>" AND SRC:MED and returns the sorted PMIDs, translating every failure leg to LiteratureUnavailable as lookup does. lookup_citation takes the route only for a DOI with no authored PMID and no PMC-id resolution: _check_doi_pmid offers one PMID as an advisory (applied=False, refusal="redundancy_bearing", source="europepmc") and hands it to _check_pmid, so PubMed's title arrives as its own info finding beside Crossref's; nothing compares the two strings. Two or more PMIDs withhold the advisory and are all named in a warning, and PubMed is not asked about any of them. Zero is said as Europe PMC's answer, not PubMed's. Offline tests cover the four arms (one, several, none, an authored PMID skipping the route) and the existing DOI-only tests now inject a Europe PMC double, since they would otherwise reach the network. Two live tests sit behind JUST_DNA_NETWORK_TESTS=1 (10.1038/ng826 → 11788828, and the Thieme DOI's two titles both info); they passed on 2026-09-30, the first attempt after one transient Europe PMC miss that the lookup reported as "could not be asked".

RM258 — an outage during the literature fetch writes a row that merge-not-clobber never asks again

Severity medium · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-29 (PROPOSAL_0_8_PT1) — found while building RM257 · Owner enricher (literature) · Motivating case S110 — Europe PMC answered HTTP 500 for PMC6463297 on 2026-09-24

Residuals none

What was confirmed. EuropePmcClient.fulltext and the new PmcBiocClient.fulltext both return None for a 404 (no copy) and for a 5xx or a transport failure (never answered). The pass then falls back to the abstract and writes quote_source=abstract with the abstract's count. The row is keyed by PMID and literature.csv is merge-not-clobber, so wanted skips it on every later run: a transient outage becomes a permanent abstract-only pin. Pinned by test_every_way_bioc_has_no_text_reads_as_not_retrieved, whose 500 arm writes exactly that row. That test asserts today's behaviour, not a decision. @unreachable-not-absent at the row level. The reporter named the conflation in fulltext(), and the pin is what it costs.

Rows pinned before RM257 have the same problem without any outage. The BioC rung only runs for a citation the pass fetches, so a module enriched before it keeps its abstract-only rows until literature.csv is deleted. Since 0.7 that delete costs nothing (RM124), and that is the workaround the S110 reply gives. It is still a step nobody will know to take.

Candidate repairs, none chosen:

  1. Write no row when the fulltext could not be asked. Refused in advance: existence, identifiers and the licence were all answered, and answered is per field (@answered-is-not-absent). Dropping those answers to get a retry is the wrong trade.
  2. Re-ask fulltext on every run for any row whose quote_source is not fulltext. No schema change, and it picks up rows pinned before RM257. It costs one paced request per paywalled citation per run, forever, for articles that will never have a copy. Changing the pass's merge from per row to per field is the precedent this would set, and --rederive already has rules for that (@rederive-never-shortens).
  3. Record how the fulltext question ended, as a derived column (fulltext_status, roughly retrieved | absent | unreachable), and re-ask only unreachable, plus null on rows written before the column existed. An optional column on a derived CSV is minor-legal and half-cost (P9). It needs the two clients to stop returning one None for two answers, which is the @client-exception-contract shape. The question for review is whether null on old rows should mean "ask once" or "leave alone".

What shipped, and one departure recorded rather than silent. Candidate 3, with null meaning ask once. Both clients gained fetch_fulltext, which returns text, returns None for a service that holds no copy, and raises the new FulltextUnavailable (a LiteratureUnavailable subclass) for a 5xx or a transport failure. The departure: PT1 said fulltext() itself should stop returning one None. The handler grep found a consumer relying on exactly that: just-module-creator's fetch_fulltext tool calls EuropePmcClient.fulltext and treats None as "try BioC" for Europe PMC's 500s (its F108). A retype would turn a handled outage into a crash there on 0.8. So fulltext() keeps its contract as a wrapper over the three-way method, and the pass uses the new one. The second departure: PT1 listed a non-JSON 200 as the fourth leg to raise on, but BioC's recorded "no copy" reply is a plain-text 200, so it stays absent.

literature.csv gains fulltext_status (VALID_FULLTEXT_STATUS, in just_dna_format.vocab, bound on the field, first seen 0.8.0), outside LITERATURE_FACT_FIELDS so a heal moves no signature. The pass records the status on every row it asks about, and re-asks only the fulltext question for a pinned row that is unreachable, or null and not already matched against a fulltext. An answer rewrites quote_source, quotes_found, the status and fetched_at; a second failure leaves the row unchanged. test_every_way_bioc_has_no_text_reads_as_not_retrieved now asserts absent/absent/unreachable across its arms. New tests: an outage heals on the next run with exactly one request and every answered field unchanged; a second failure leaves literature.csv byte-identical; absent and retrieved rows are never asked again; a row stripped of the column is asked once and the run after changes nothing. The heal sequence run against the pre-RM258 code in a disposable worktree made no second request (requested == []), which is the defect.

RM272 — an answered-but-unplaceable rsID has no structured name in EnrichmentResult

Severity low · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-29 (PROPOSAL_0_8_PT1) · Owner enricher (EnrichmentResult) · Motivating case RM268 and RM271, 2026-09-27

Residuals none

RM268 withholds a live REST locus whose anchor base cannot be read, and RM271 withholds loci whose alleles are not bases; RM274 keeps an indel the reference could not settle, and drops one it showed is a different event. On main all of these are reported by a log warning only, because a new EnrichmentResult field is minor-class (the first RM268 commit added unanchored_rsids there and was fixed forward). A caller reading the result sees these rsIDs only in unresolved, which is silent about why, the gap unreachable_rsids, unconsulted_rsids and allele_mismatches each closed for their state. Add the field (or fields) on 0.8, beside those, and decide whether "anchor base unreadable" (transient, re-run) and "not a base" (permanent) are one list or two. · related RM268, RM271, S20, S85

What shipped. Three EnrichmentResult fields beside unreachable_rsids, unconsulted_rsids and allele_mismatches, each documented with its remedy: unanchored_rsids (the set the pass already kept), non_nucleotide_rsids, and reference_rejected_loci (the stated assumption held: per locus, a field of its own, and it has a reader in the same place the log line had one). The non-nucleotide rsIDs are collected from both Ensembl rungs, since RM271 filters in both: the snapshot through a new optional non_nucleotide= collector on resolver.lookup_loci (additive, the return shape unchanged), and live REST through EnsemblResolver.non_nucleotide_rsids, read by attribute so an injected resolver without it contributes none. The result keeps the lists disjoint by construction: a non-nucleotide rsID some other link placed, or that also failed or went unanchored, is not listed. Tested with one enrich run holding one rsID in each state (the strings live REST served), each named in exactly one list and all in unresolved; the RM274 test now asserts its locus on the result; and both collectors are pinned directly.

RM278 — the compile command cannot pass ensembl_reference or ba1_threshold, so every CLI-compiled manifest has a null ensembl_reference

Severity low · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-29 (PROPOSAL_0_8_PT1) · Owner compiler (cli.py compile) · Motivating case RM218's surfaced, not fixed (§13.8), which left the question open and tracked nowhere, found by the 2026-09-27 postmortem sweep (P6) · related RM218

Residuals none

Confirmed on 2026-09-27. compile_module takes ensembl_reference and ba1_threshold, and just-dna-compiler compile --help offers neither. So manifest.compilation.ensembl_reference cannot be stamped by the shipped command, and a module compiled through the CLI records no reference, whatever it was resolved against. ba1_threshold is the ACMG BA1 cutoff its own docstring says a carrier-allele module would want to move. COMPILER.md states the gap and test_cli_parity.py does not assert compile-flag parity, so nothing will move it.

Why a minor, not a patch. Two new CLI options are new public surface, and main takes none (the RM268 fix-forward). The decision is small: add both, or say in COMPILER.md why the CLI deliberately stays narrower than the API. Either way, extend test_cli_parity.py to assert the decided set, so the next parameter cannot drift in unweighed.

What shipped. Both options, passed straight through: --ensembl-reference (a string, as compile_module takes it) and --ba1-threshold (a float defaulting to the API's BA1_ALLELE_FREQUENCY_THRESHOLD). test_cli_parity.py asserts the compile command's options, with three renames mapped (resolve, strip_identity, authority_key), equal compile_module's parameters minus log_files, provenance_file, logo_file and readme_file, each declared with its reason: they are auto-discovered beside the spec, so an explicit path is an API-only override. A CLI compile with --ensembl-reference ensembl-115 stamps it into the manifest, and a non-numeric threshold is refused. COMPILER.md's gap paragraph, which sat in the middle of the command table, is replaced by the decision below the table, and the COMPILING guide lists both flags.

RM300 — the manifest cannot say how many rows are pathogenic, only how many carry the folded flag

Severity low · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-29 (PROPOSAL_0_8_PT1) (new optional manifest fields) · Owner format (manifest.Stats) + compiler (_variant_stats) · Motivating case S123 in CONSUMER_SUGGESTIONS_HISTORY.md, via RM299 · related RM299, S43

Residuals none

What is missing. stats.pathogenic_count and stats.benign_count sum the legacy booleans, and each boolean folds a tier pair. A catalog facets on the listing without reading the artifact, so it cannot split pathogenic from likely_pathogenic. just-dna-lite's card had to fall back to a tooltip. The reporter's own measurement for just-dna-seq/pathogenic: 403,534 pathogenic rows and 215,095 likely_pathogenic.

The shape. Per-tier counts derived from clin_sig (the effective value, so a boolean-only row still counts through clin_sig_from_booleans where it can), beside the existing fields. The existing fields keep their meaning. Whether it is a count per tier or a mapping keyed on VALID_CLIN_SIG is the one design question: a mapping takes a new tier without a new field. Decide whether distinct variants per tier are wanted too, since the existing counts are per genotype row.

Legality and price. A new optional manifest field is additive and minor-legal (P3). It is not in artifact.digest, and the compiler writes it, so it costs nearly nothing (P9). Not on main.

What shipped. manifest.Stats gains clin_sig_counts and clin_sig_variant_counts, both dict[str, int] validated against VALID_CLIN_SIG, computed by compiler.manifest.clin_sig_tier_counts from each row's effective clin_sig and emitted with every member present in sorted order, zeros included. A row with no derivable tier is counted nowhere, and the field descriptions say how to read that count off the totals. The existing folded counts are unchanged. Stats has no extra="forbid", so a 0.7 reader parses a 0.8 manifest and drops the two fields (no old-reader break). Tested over every reference example: keys and order always; and on the seven whose weights were neither expanded nor dropped, the per-tier row and variant counts equal the ones grouped out of weights.parquet at runtime. A synthetic HFE module shows the two tiers summing to pathogenic_count.

RM313 — RM57's quality_floor_inverted warning reads VCF QUAL backwards, and tells authors so on every compile

Severity medium · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-30 (PROPOSAL_0_8_PT1): the retirement alone would be a patch, and the replacement finding's new code makes the pair a minor · Owner compiler (_check_quality_inversion) + format (the quality_from description) · Motivating case relayed 2026-09-30 by the just-vcf session, which found it checking its own frame schema against VCFv4.5 · related RM57, RM6, VCF_4_4_AUDIT § 5

Residuals RM314 — the neighbouring callable_from text, which reads INFO END where VCF 4.5 made it a cross-sample maximum

The misreading. VCF §1.6.1 item 6 (identical in 4.4 and 4.5): QUAL is "Phred-scaled quality score for the assertion made in ALT. i.e. −10log10 prob(call in ALT is wrong). If ALT is '.' (no variant) then this is −10log10 prob(variant), and if ALT is not '.' this is −10log10 prob(no variant)." On a monomorphic record the assertion is no variant, so QUAL 60 means P(variant) = 10⁻⁶: a confident reference call. QUAL is the confidence in whatever ALT asserts on both kinds of record, and an inclusive floor moves the same way on both. The 4.4 audit's § 5 read it as "almost certainly variant", and RM57 built that into code.

What ships the false claim today. compiler._check_quality_inversion emits quality_floor_inverted in both modes on any requires_callable row with quality_from naming QUAL, saying "a HIGH QUAL says the position is probably variant" (QUAL_INVERSION_PHRASE). The VariantRow.quality_from description says the same, and so do the COMPILER.md catalogue, test_vcf_conformance_warnings.py and the features/ scenario. Its remedy recommends GQ, which Table 2 defines as conditioned on the site's being variant, so it is not a reference-call confidence either.

What survives from § 5. Its second half: reference evidence is an interval (a <*> block; FORMAT LEN in 4.5, with INFO END deprecated), found by containment, with MIN_DP as the right depth. And a narrower true finding: a <*> block usually carries QUAL ., so a QUAL floor on a requires_callable row is a check that cannot run, not an inverted one (@unreachable-not-absent).

The decision. quality_floor_inverted is a permanent key naming a finding that is false (@warning-code-names-the-finding). The patch stops emitting it and corrects the description, the catalogue and the scenario. The code stays in VALID_WARNING_CODES, because removing it is major, and the registry tests have to accept a retired, unemitted member. The honest replacement, a floor on a field the reference record usually leaves missing, is a new code and therefore a minor on 0.8. Whether to build that at all, or only document it, is the call.

What shipped. vcf_checks._check_quality_inversion is replaced by _check_qual_floor_on_reference_evidence, same trigger (requires_callable=true with quality_from naming QUAL, matched as before), new code qual_floor_on_reference_evidence, a warning in both modes, aggregated. Its sentence says the floor cannot be read on the reference record the row is decided from (a block usually leaves QUAL missing, and on a joint-called site QUAL is not this sample's), and it recommends no field. quality_floor_inverted is emitted nowhere and stays in VALID_WARNING_CODES; the new vocab.RETIRED_WARNING_CODES declares it with its reason, and the emission-site walk and the scenario corpus both subtract that set by declaration. QUAL_INVERSION_PHRASE is gone (QUAL_REFERENCE_EVIDENCE_PHRASE replaces it in the re-export shell), and COMPILER.md keeps the old text under Retired phrases for grepping old manifests.

The false claim, shown before it was changed: test_a_requires_callable_row_floored_against_qual_is_reported asserted that the warning contained GQ and MIN_DP, which pinned RM57's remedy, and its docstring restated the inversion. It now asserts the replacement phrase and that neither the inversion wording nor the GQ advice appears. A new test compiles the synthetic row and every reference example and asserts the retired code never appears.

Corrected everywhere the claim was stated: VariantRow.quality_from's description, SCHEMAS.md's consumer-contract paragraph, COMPILER.md's schema-limit paragraph and catalogue, the features/ scenario, and INTEGRATION_0_8.md (the new code, and § 1.1 on the retirement). The 4.4 audit keeps its body as evidence under its dated correction.

RM308 — the conclusion-genotype finding runs only on the authoring surface, so a module nobody linted compiles green with a swapped pair

Severity low · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-29 (PROPOSAL_0_8_PT1) (a new warning code) · Owner format (VALID_WARNING_CODES) + compiler (validate_spec, compile_module) · Motivating case RM279's residual, 2026-09-28 · related RM279, RM309

Residuals RM309 — the negation half of RM279's rule, still unmeasured, whose compile half would join this code

RM279 shipped the rule as a hint because the compile half needs a member of VALID_WARNING_CODES, and a new member is minor-class: a reader pinned to an older just-dna-format refuses a manifest carrying it. So an author who never runs hint or lint_rows still gets a green --strict compile on a swapped pair. The rule is just_dna_compiler.conclusion.conclusion_genotype_mismatches, already separate from hints so the compile path can call it. What the minor owes: one code named for the finding (for example conclusion_names_other_genotype), emission at both validate and compile (@parity-by-check), aggregated by reason, a features/ scenario, and the phrase pinned in the COMPILER.md warning catalogue. It stays a warning in both modes: 10 of 10 is a measurement over one corpus, not a licence to refuse.

What shipped. variant_checks._check_conclusion_genotypes runs RM279's rule (conclusion.conclusion_genotype_mismatches, unchanged) in the shared pre-flight, beside the genotype coverage check, so validate and compile carry the finding once each. New code conclusion_names_other_genotype, actionable, a warning in both modes, aggregated by two reasons because the repair differs: rows that name each other ("look swapped", exchange two conclusions), and a row naming a neighbour that does not name it back ("as if copied", rewrite one). Tested with RM279's real fixtures through a positioned spec and a green --strict compile; a correct module naming its neighbour stays quiet. No reference example fires. The hint keeps its per-row, line-numbered form.

Found while building, and fixed in the same round: the RM275 tests filtered result warnings by .code, but a result's warnings are plain strings (the code is lost at the pydantic field, @finding-loses-its-code-at-a-boundary), so two negative tests there could not fail. Both files now match the pinned phrase and read the code from warnings_summary, and a mutation run (the "both stated" filter removed) shows the empty-cell test failing.

RM275 — seven derived fact tables have no duplicate rule, so two contradicting rows under one key compile green under --strict

Severity medium · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-29 (PROPOSAL_0_8_PT1) (re-sized 2026-09-27, see the last paragraph), with refusal at 1.0 · Owner compiler (_TABLE_DUPE_KEYS) · Motivating case RM107's residual (0.6), "it wants its own item", found unfiled by the 2026-09-27 postmortem sweep (P3) · related RM107, RM109, RM124, RM130

Residuals won't fix — refusing inside a minor would break modules that compile today, so the refusal waits in ROADMAP § The 1.0 cleanup

RM107 widened the duplicate check to sources.csv and wrote down what it left: "The remaining gap is the other fact tables, which have no duplicate rule at all; RM109's own defect produced exactly such a pair and nothing reported it." Walked on 2026-09-27, _FACT_TABLES minus _TABLE_DUPE_KEYS is frequencies, gene_metrics, literature, gene_validity, clinical_assertions, gwas_effects and expression_effects. RM124 and RM130 registered their own tables, and none of these.

Reproduced. reference_examples/hboc_palb2 with its first gene_validity.csv row duplicated and the copy's classification changed from definitive to refuted. compile --strict exits 0, and gene_validity.parquet carries both rows for PALB2 / MONDO:0012565 / autosomal_recessive. A consumer reads one or the other depending on row order.

Two constraints on the build.

  • Derive each key from the merge key the enricher already writes the table by (base.merge_key, @suppression-from-merge-key), never a second hand-kept tuple. gene_validity keeps two rows on purpose when the source's classification drifts (the comment at gene_validity.py:288-311). So "duplicate" means both stated and different under the merge key (@absent-is-not-different), not merely a repeated key.
  • Refusing is a tightening. A published module carrying such a pair compiles today, and P3 says existing modules keep validating inside a major. So the check lands as a warning in both modes on main, and becomes a refusal at 1.0 (a 1.0-tracker line when this is built).

Re-sized to a minor, 2026-09-27, before building. The warning needs its own code, and a new member of VALID_WARNING_CODES is not legibility-only: ModuleManifest.warnings_summary validates every key against that closed set, so a just-dna-format 0.7.2 reader refuses a manifest carrying the new code. That is an old-reader break (the INTEGRATION_0_7 shape), which main cannot take. Reusing an existing code would name the wrong finding (@warning-code-names-the-finding), and a log line alone is invisible to every consumer reading findings. Build it on the 0.8 branch, with the INTEGRATION note that says a reader must be at 0.8 to read such a manifest.

What shipped. A new check, fact_checks._check_fact_rows_contradict, beside _TABLE_DUPE_KEYS and not in it. It groups each of the seven tables' rows by base.merge_key and reports a key under which two rows state different, stated values in one of the table's fact fields (the set its signature already hashes, so a differing fetched_at is not a contradiction). New code fact_rows_contradict, actionable, a warning in both modes, aggregated per table with a count and three example keys naming the differing columns. It runs in the shared pre-flight and reaches the compile through it, once. FACT_CONTRADICTION_FIELDS plus the refusing registry are asserted to cover _FACT_TABLES exactly. The entry's reproduction (hboc_palb2, a duplicated gene_validity row with refuted) now warns under a green --strict; an identical duplicate and a copy leaving the cell empty do not. Shown failing with the call disabled. No reference example fires.

The drift case, measured before settling the rule. gene_validity.csv's deliberate second row on a re-curation never meets this check: ClinGen's assertion_id embeds the curation timestamp, so a re-curation has a new primary key, and the grain fallback includes dataset. The currency checks keep that case.

The old-reader break is recorded in the new INTEGRATION_0_8.md § 1, which this item opened, and refusal at 1.0 is a line in ROADMAP § The 1.0 cleanup.

2026-11-05, RM374: the cross-key form of this gap. One variant's facts under two keys (variant_key vs rsid or coordinate) are compared by fact_rows_contradict (compiler/.../fact_checks.py:75) only within one merge key. Instances: schema frequency.py:78, assertions.py:91, consequences.py:53, expression.py:126, gwas.py:110/131/135. Refusal stays at 1.0 with the rest of this item; a warning is minor-legal.

RM241 — weighting does not survive reverse, so a reversed module has no scale to read

Severity low · Status ✅ SHIPPED 2026-09-30 on 0.8, uncut — a minor, taken into 0.8 on 2026-09-29 (PROPOSAL_0_8_PT1, widened there to every authored field reverse drops, and decided) · filed 2026-09-13 from RM188's ClawBio half · Owner format · Motivating case probes/CLAWBIO_SURVEY.md § The translation, run, last paragraph

Residuals RM270 — a round trip still drops every vrs_id, because no variant parquet carries it · won't fix — provenance and the verification attestation are not in the artifact, so there is nothing to read back

weight is the one magnitude in this format with no unit beside it (@weight-has-no-unit), and RM92 built module_spec.weighting — scale, method, note — to be the place a module says what its weights mean. It is advisory, copied into the manifest, and not reconstructed by reverse_module, in the same class as panel / authorship / license. All of that is documented and, taken one field at a time, defensible: it is not content, so it is correctly outside content_signature.

The survey hit the consequence. Translating ClawBio's nutrition panel forced an honest weighting block to be written — their weights are hand-assigned importances within a nutrient domain, and their scorer normalises by the weight of the SNPs it happened to find, so a domain score is comparable only inside one domain of one run. That block is the single most useful sentence in the translated module. reverse then drops it. So a consumer holding two reversed modules has two weight columns and no way to learn that they are on different scales — which is the exact failure RM92 was built to prevent, surviving in the one path RM92 does not cover.

Three candidate dispositions, and this entry does not pick one. (a) Nothing — write it in the FAQ as a known lossy field and let a consumer read the original spec, which is what reverse's own contract already says. (b) Carry weighting through reverse from the manifest, which is where it already lives — cheap, and it changes what reverse claims to be. (c) Decide the lossy set is right and that the real defect is that nothing warns, the way the dropped verification attestation warns. (c) is the most likely right answer and is the cheapest to test: reverse already emits one warning for a dropped attestation, so a second for a dropped weighting costs one line and tells the author the thing they need to know at the moment it stops being true.

Do not fix this by putting weighting inside content_signature. It is prose about a column, not the column; hashing it would make a reworded note move the digest, which is the defect FAQ already answers twice.

Decided 2026-09-29, and wider than this entry. Probing (c) found weighting is one of several authored fields reverse drops while the round-trip gate stays green, because the gate compares two digests that both exclude the manifest. PROPOSAL_0_8_PT1 § RM241 carries the measurement and the build: reverse rebuilds every authored field the artifact carries, and the gate compares the manifest's authored projection. (a) and (c) are both superseded.

What shipped. reverse_module reads the artifact's manifest.json once and writes back every spec field it carries: the module: block's title/description/report_title/icon/icon_set/color from manifest.display, version (RM103's rule), genome_build, license, weighting, authorship, authority_precedence, panel, and the defaults' curator/method. The README and logo are copied back byte for byte after a hash check against manifest.readme/manifest.logo; a file that disagrees with its record is not copied. The order is an explicit argument, then the manifest, then the bare-directory fallback, and icon/color default to None (API and CLI) so "not passed" is visible. REVERSE_RECONSTRUCTED and REVERSE_EXCLUDED (defaults.priority, with its reason) are asserted equal to the walked ModuleSpecConfig/ModuleInfo/Defaults fields. The reference-example round trip now compares the manifest's authored projection across laps, and test_reverse_reconstructs_the_spec.py sets every field on a copy of hfe_hemochromatosis and asserts two laps. Run against the old reverse, the projection check failed on every example.

One departure from the proposal, recorded rather than silent. PT1 said the manifest carries no defaults and left curator/method to the row-mode guess. It does carry them, as manifest.curator/method, and the guess was worse than lossy on a table-only module: with no weights.parquet there is no mode to take, so every PGx example came back with unknown defaults and its recompiled manifest said so. Both are now read from the manifest, with the mode as the fallback. defaults.priority is the one spec field not written back, because the manifest has no default priority and every row carries its own.

The 0.7 build round

The items PROPOSAL_0_7.md decided on 2026-08-27/28 and the 0.7 batch then built. Every one is additive under Principles 3 and 8; what is kept here is each entry's reasoning, including the repairs it refused, which is the half that would otherwise be re-derived.

The round's twelve are all here as of 2026-08-31, which is when the last four entries left the forward-only files they had been sitting in with a SHIPPED banner on them: RM126 and RM71 from ROADMAP_0_7.md, RM133 and RM134 from ROADMAP.md. An entry marked shipped in a file that describes what is not built reads as late rather than done, which is the state this move ends. The deferral round those two came from closed at the same time — history/ROADMAP_0_7.md keeps it, and everything still waiting moved to ROADMAP_0_8.md. RM83 is in this file as closed, not shipped, and RM139 was filed by the cut itself rather than by the proposal.

RM140 joined them on 2026-08-31 from a consumer report, after the round had closed. It is not one of the twelve and does not reopen the thread; it lands inside the same uncut 0.7.0, because a new optional column is what sizes a release and the number was already decided. PROPOSAL_0_7.md carries its decision as a dated addendum, in the file's own idiom, so the reasoning sits beside the twelve rather than in a thread of its own.

And a second round joined the same uncut release on 2026-09-01: the source-adoption batch, RM163–RM168. Six items filed out of one sweep, every one gated on a probe that had not been run; PROPOSAL_0_7_PT2 is its record. It is a round rather than an addendum — six items decided together against a shared sort rule — which is why it has its own file rather than joining RM140 and RM152 as a third dated note on the first thread. Five of the six build here and RM164 parks on a measured negative, having spun off RM171. What the round is worth remembering for is not any one adoption: five of the six entries said something their own probe contradicted, and then four of the six verdicts the proposal drafted were overturned again in the maintainer pass — so an unprobed entry is a question, and a probed one is still only a proposal.

The round closed the same day it was decided, which is the third drift and the one worth counting: of the five items built, four contradicted their own entry again during the build. RM165's entry proposed drafting four columns RepeatAlleleRow does not have. RM167's three headline measurements did not reproduce — a gene-node count that conflated two id shapes, a locus count off by 34, and an id grammar contradicted by the example printed beside it. RM163 offered overrides.csv as the author's remedy for a finding the overlay cannot reach. RM166's licence motivation was already gone before the build began. RM168 is the only one of the six that held, and it is the one whose questions were cheapest to ask — a directory listing and a 1.1 MB download.

So the three-stage pattern is: an entry states what it believes, a probe contradicts it, a decision overturns the probe's verdict, and a build contradicts the entry again. Each stage was cheaper than the one before, and each caught something the previous one asserted. That is an argument for probing early and for writing entries that can be contradicted, not for trusting any of the four stages on its own.

RM247 — the enricher CLI is dead on a fresh install: a build-isolated grpcio-tools outruns the locked grpcio

Severity high · Status ✅ FIXED 2026-09-20, shipped in just-dna-enricher 0.7.1 · Owner enricher (packaging) · Motivating case a peer session could not run just-dna-enricher draft --gene <X> at all

What shipped, against the three candidate repairs this entry argued. All three, because the first two are independent defects and either alone leaves the tier killable. (1) [build-system] requires pins grpcio-tools==1.83.1 and the runtime floor is grpcio>=1.83.1 — one number, written twice and asserted equal, at the pair RM192 measured and uv.lock already resolved, so no floor bump in RM192's sense. (2) alphagenome_check and expression both guarded their module-scope atlas_client import already and both caught only ImportError, while grpc's bindings raise RuntimeError; both now catch either, walked so a third importer fails by existing — the second guard was found only after the first was fixed. (3) the console entrypoint is imported by a test, so this fails as one named thing rather than as thirty-eight collection errors.

A fourth thing, found by installing the wheel rather than by reading it. just_dna_enricher.resolver imports just_dna_compiler.resolution_findings, a module RM244 created after v0.7.0 — so the enricher wheel declared just-dna-compiler>=0.7.0 and ModuleNotFoundError'd in a clean venv. Exactly the incident the intra-workspace floor guard exists for, arriving by a route that guard does not watch: it compares a declaration against the local tree, where every module exists by construction. test_a_cross_tier_import_exists_in_the_version_its_floor_names reads the dependency's modules off the v<floor> tag and fails on an import the published release does not carry. So just-dna-compiler is cut to 0.7.1 alongside, and just-dna-format stays at 0.7.0 — nothing new crossed into it.

uv run just-dna-enricher <anything> --help raises before Typer is reached:

RuntimeError: The grpc package installed is at version 1.83.1, but the generated code in
just_dna_enricher/generated/_alphagenome_atlas_protos/atlas_service_pb2_grpc.py depends on
grpcio>=1.84.0.

Two floors for one number, and only one of them is locked. [build-system] requires is ["hatchling", "grpcio-tools>=1.68.0"] — a floor with no ceiling, resolved in an isolated build environment that uv.lock does not constrain, so it picks up whatever grpcio-tools is current and stamps GRPC_GENERATED_VERSION = '1.84.0' into the generated bindings. The runtime dep is grpcio>=1.68.0, locked at 1.83.1. The generated module raises at import time when the two disagree. They are the same number — the version that generates the code and the version that runs it — written twice, one pinned and one floating, which is the defect rather than either value.

Blast radius is the whole command surface, not the Atlas commands. cli.py imports alphagenome_check → atlas_client → the generated bindings at module scope, so enrich, draft, literature, pgx, frequencies and every other subcommand die on an Atlas dependency they do not use. 17 test files error during collection and 38 import just_dna_enricher.cli.

Reproduced from clean, so it is not one machine's stale artifact. The generated tree is git-ignored and produced at install; deleting it and running uv sync --reinstall-package just-dna-enricher regenerates the same broken stamp. The repo's full suite was green at 4658 passed on 2026-09-13; the generated files on this tree are dated 2026-09-19. So the breakage arrived with a grpcio-tools release, not with a commit here — which is exactly what an unconstrained build requirement buys.

Do not fix it by bumping the runtime floor without re-reading RM192. That entry measured the Atlas dependency cost at grpcio 1.83.1 / protobuf 7.36.1 — 19 MB of site-packages and +2 packages — and the floor is load-bearing for a tier whose weight is a charter concern. The candidate repairs, in the order they should be argued:

  1. Make it one number. Constrain the build requirement against the runtime lock rather than letting them float apart — the rule is the grpcio floor is whatever generated the bindings, and nothing currently states it anywhere a tool can read.
  2. Import the Atlas bindings lazily, so a grpcio problem breaks the Atlas commands and not draft. The module-scope import is what turns a narrow dependency fault into a dead CLI, and this is worth doing whichever way (1) goes. Note the house rule against inline imports has a stated exception for a guarded optional dependency, which is what atlas is ([project.optional-dependencies]).
  3. A smoke test that imports the CLI entrypoint the way the console script does. 38 test files import just_dna_enricher.cli and all 38 now error at collection, which reads as a broken suite rather than a broken command — and a red collection is a different signal from a red assertion. Whatever shape it takes, it has to fail as one named thing.

Not fixed in the filing session, deliberately: the choice between (1) and a floor bump is a dependency-weight decision with a measurement behind it (RM192), which is @fix-vs-surface — surface it, name why each candidate repair is or is not right, and let the owner decide. The tree is red meanwhile, and that is the state this entry exists to make visible.

And the docs site will not build either, which is the third surface and the one that makes this a release blocker rather than an inconvenience: scripts/gen_cli_pages.py:47 does from just_dna_enricher import cli as enricher_cli to generate the command reference, so uv run --group docs properdocs build --strict dies on the same import. Two of the cut's gates — the suite (17 collection errors) and the docs build — are down on one dependency fault, and neither says "grpcio" in a way a reader would connect to the other.

It is a release hazard, not only a dev-tree one — this is the half that raises the severity. The generated tree is git-ignored but not build-ignored: hatch_build.py force-includes it, so the wheel ships whatever stamp the machine that built it produced. The published 0.7.0 works (a peer session runs it from PyPI and drafted from CPIC on it), because it was built before the grpcio-tools that stamps 1.84.0. A release cut today would ship the broken stamp to every installer, and nothing in the cut checks it — the sweep gate compiles modules, it does not import the enricher's console script. Whatever repair lands, the release procedure needs the smoke test in (3) or the next cut is a coin toss on the build machine's resolver.

Related RM192 (the measured Atlas dependency cost), RM196 (why this tier alone is on hatchling).

What its guards missed, found a day later. RM254: protobuf's gencode/runtime mismatch raises a type neither of this entry's guards caught, so the CLI died again beside anything pinning protobuf<7 (S107). Read the two entries together.

Residuals RM254

RM377 — the two refusals only strict adds carry no code, and their wording was the only way to tell them apart

Severity low · Status ✅ SHIPPED 2026-11-04 on main, uncut — a patch (docs and a test: two phrases published as API) · Owner compiler · Motivating case S129 in CONSUMER_SUGGESTIONS_HISTORY.md (just-dna-registry's liaison seat, 2026-11-04) · related RM131, RM218, RM143, RM378

What was observed. errors is list[str] on every result type, with no code: RM131 classified the warnings channel and left errors as prose. RM218 corrected validate_spec's docstring to say that strict adds two aggregate refusals rather than only promoting warnings: the unresolved-position refusal and build_disagreement_error. A registry grading a dry run treats the two differently (one says resolution was incomplete, the other that two authored files disagree about the genome build), and it could tell them apart only by sentences nothing published or pinned. test_strict_compile.py held "unresolved genomic positions"; nothing held the build refusal's wording.

Sizing. Two items. Codes on errors, with an errors_summary, are a new published vocabulary and a new field on public result types: additive and legal, and a minor (RM378). Publishing the two phrases moves no model, field or message, so it is a patch, and it holds a 0.7 consumer until RM378 ships.

Not taken. Named constants for the two phrases, the way UNJOINABLE_PHRASE and its three siblings are: a new importable name is new public surface, and 0.8 has split compiler.py into a package, so moving both emission sites onto a constant on main would conflict at every merge for a name RM378 is about to supersede. The table in the document is the registry instead, and the test reads it.

Found beside it, and already closed elsewhere. Probing the fixture showed that on main, validate_spec(strict=True, resolve_with_ensembl=False) passes an rsID-only row that compile_module with the same arguments refuses. The CLI's validate has no resolution switch, so only the API reaches it. The 0.8 line closes it as RM367, measured the same day on origin/0.8, so it gets no item of its own here.

Residuals RM378

What shipped. COMPILER.md's Warning texts a consumer keys on gains The refusals only strict adds: the two findings, each with its phrase and what clears it, and the rule that strict compile: opens exactly these two and nothing else, in any list, in either mode.

Tests: compiler/tests/test_strict_refusal_phrases.py reads the phrases from that table, so the document and the guard cannot drift. It walks the compiler package's source for every literal opening strict compile: and refuses one that carries no published phrase, or more than one. It asserts that both entry points return each phrase for its own case and only that one, and that best-effort says the prefix nowhere. Both failures were shown before landing: rewording the build phrase in the document fails two tests, and a third strict compile: literal planted in the package fails the walk. The file passes unchanged on origin/0.8, whose emission sites live in other modules.

RM371 — the enricher spells tenacity's backoff initial, which tenacity 9.2.1 deprecates, so every import warns and a release that drops it would stop the enricher importing

Severity medium · Status ✅ SHIPPED 2026-11-04 on main, uncut — a patch (enricher: a keyword rename and a dependency floor) · Owner enricher (every retried client) · Motivating case S128 in CONSUMER_SUGGESTIONS_HISTORY.md (prepare-annotations, 2026-11-04) · related RM247, RM254

What was observed. tenacity 9.2.1 (2026-10-07) renamed wait_exponential_jitter(initial=…) to multiplier= and warns on the old name. Every retried enricher client builds its wait in a module-level @retry, so the warning fires at import, once per site: 18 sites in 15 modules on main. The floor was tenacity>=9.0.0 with no cap. So the tenacity release that removes initial would make every one of those decorators raise TypeError at import and kill every enricher command, the same shape as RM247 and RM254. The workspace lock held 9.1.4, which is why nothing here warned. 9.1.4's constructor is (initial, max, exp_base, jitter) only, and PyPI has no 9.2.0. So the rename needs the floor raised to 9.2.1.

Sizing. A patch. It touches no model, column, parquet or manifest field, so Principles 3 and 8 do not reach it, and RM254 raised a dependency floor in a patch before. The cost of a floor is that an install which also caps tenacity below 9.2.1 fails to resolve. Install time is the honest place for that to fail. It was measured before choosing: just-dna-lite (>=9.1.4), just-module-creator (>=9) and the marketplace all accept 9.2.1, and dagster does not depend on tenacity. prepare-annotations already floors 9.2.1.

Correction (RM436, 2026-11-12). "just-dna-lite accepts 9.2.1" read its own requirement and missed one it inherits: just-dna-lite depends on google-genai, and every google-genai release caps tenacity<9.2.0, so uv lock with the 0.8.4 enricher failed there (S149). RM436 moved the floor down to tenacity>=9.0.0 and picks multiplier= or initial= in one place by the installed signature; this item's warning stays fixed.

Not taken. Silencing the warning, which would hide exactly the removal this guards against. A <9.3 cap, which would trade a future import failure for a future resolve conflict with every consumer that moves on, and would still leave the warning.

The 0.8 branch carried 21 such calls, 3 more than main (clinvar_gkm.py, ld_pairs.py and literature.py's PMC client). The guard went red there when main merged in, as intended, and the merge converted the three to multiplier= (2026-11-04).

Residuals none

What shipped. All 18 calls pass multiplier=, including cpic.py and pharmvar.py, whose initial=1 never warned but would break the same way. In 9.2.1 initial is only copied into multiplier, and the wait is multiplier * exp_base**(n-1) + jitter in both versions, so backoff timing is unchanged. enricher/pyproject.toml floors tenacity>=9.2.1, and uv.lock moves 9.1.4 → 9.2.1 and nothing else. With the suite's error::DeprecationWarning filter, the locked version makes import itself a gate. python -W error::DeprecationWarning imports all 87 enricher modules cleanly.

Tests: enricher/tests/test_retry_wait_keywords.py walks the package source, so a new client is covered the day it is written, whatever tenacity is installed. It refuses a wait_exponential_jitter call that passes initial= or any positional argument (9.2.1 still binds the first one to initial), or that states no multiplier=. It also asserts the call set is non-empty and that the pyproject floor is at least 9.2.1. Both failures were reproduced before the guard was kept. Reverting one site to initial= fails at import under the locked tenacity. Making cpic.py's call positional, which no import warning sees, fails the walk alone.

RM293 — MITOMAP's : deletions are mintable now that rCRS is vendored, and three texts still say Principle 2 forbids it

Severity low · Status ✅ SHIPPED 2026-09-27 on main, cut 2026-09-27 as v0.7.3 — a patch · Owner enricher (mitomap_build, mitomap_miss_build, the mitomap CLI note) · Motivating case RM273's residual, 2026-09-27 · related RM285

Residuals RM285 — this was its item 1, which it did not name when it shipped; the VUS* reading and the unrated-miss call stay there

MITOMAP writes a deletion right-anchored (refna="TA", regna=":"), and the lane puts those rows in unmintable (47 on the local build) because a VCF pair needs the rCRS base at position - 1. The reason given in mitomap_miss_build's docstring, the mitomap CLI note and ENRICHER.md's bucket table is that Principle 2 forbids these tiers from fetching it. That was never quite the charter (Principle 2 binds format and compiler, not the enricher), and since RM273 the base needs no fetch: _rcrs.RCRS is vendored and verified against ClinVar's chrMT ref alleles (3,104 of 3,104). Minting those rows moves them out of unmintable into photocopy / rated_miss / unrated_miss through the event join, a corrected derivation with no new bucket. Measure how many land where before building, and correct the three texts in the same change.

What shipped, measured. Of the 47 unmintable rows, 39 were : deletions; the other 8 (ref_equals_alt 6, non_nucleotide 2) are unmintable for other reasons and stay. The miss build anchors a : deletion on the vendored rCRS base at position - 1 after checking MITOMAP's deleted bases against rCRS (all 39 agree; one that did not would stay unmintable), writes the VCF spelling into the lane's row, keeps allele_defect as MITOMAP's shape, and joins it through RM273's event key. Rebuilt from the local parents: photocopy 663 → 686, rated_miss 1 → 2 (one uncertain_significance joins the likely_benign), unrated_miss 385 → 400, unmintable 47 → 8. The count is a log line, not a MissBuildResult field (minor-class). The three texts citing Principle 2 (the lane docstring, the mitomap miss CLI note, the drafter note) and ENRICHER.md's bucket table now say what happens instead.

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (it narrows what a *.log ships, and joins 0.8 as filed) · Owner compiler (_collect_logs) · Motivating case the RM337 builder's report, 2026-11-04 · related RM337, RM338, RM347

Residuals won't fix — a hard link reaches outside the module with no symlink at any level, and st_nlink cannot tell an author's own link from a reach outside, so it is reported to the lead rather than guessed at here · won't fix — the copy into the output reads the file again after the check, so a file still being appended can ship past the ceiling; closing it means copying the checked bytes, which is reported to the lead as its own question

0.8, filed 2026-11-04 by the lead as a second-pass item (RELEASE_CYCLE § Minors step 4): found while building RM337, in behaviour RM338 shipped.

One class, four instances. Discovery under logs/ reads whatever the filesystem hands it, and a published file is permanent:

  1. a symlinked *.log ships, even when it points outside the module;
  2. a logs/ directory that is itself a symlink is walked, and everything under it ships;
  3. a text file under logs/ has no size ceiling and is read whole into memory;
  4. an unreadable file (a PermissionError) raises out of the compile instead of staying behind.

The fix, as one rule. Every path discovery considers is resolved and must stay inside the spec directory; a symlink, at any level including logs/ itself, stays behind with log_file_not_shipped's symlink reason (an explicit log_files list is unaffected); text gets the same ceiling as images (LOG_IMAGE_MAX_BYTES becomes one LOG_MAX_BYTES, read from stat before any byte); a file that cannot be read stays behind with a new reason, never an exception. *.log keeps shipping unchecked for content, but not past the symlink and size rules. That last point narrows what a *.log did before RM338, so its CHANGELOG line says so.

What shipped. _reached_through_a_link(path, spec_dir) is the containment rule: a path is a symlink, or its resolved form is not exactly the spec directory's resolved form joined with the path's own relative part. The resolved spec directory is the reference, so a spec directory that is itself reached through a link still ships its own files. _log_left_behind_reason(path, logs_dir, spec_dir) asks it first, for every kind, *.log included; then, for anything but an exact .log, the name-only arms as before (hidden path, SVG, an extension that does not ship); then one try around the stat and the open: over LOG_MAX_BYTES is oversize with both sizes, any OSError is the new unreadable arm, "the compile could not read it". A .log is opened and nothing read, an image reads its magic, text reads whole, now bounded. _collect_logs judges the top-level *.log through the same function, and treats logs/ as a candidate like any path under it: a link is judged and never walked, so one finding names logs. The ceiling is LOG_MAX_BYTES, and LOG_IMAGE_MAX_BYTES stays as a working alias of it: no tag carries the old name yet, but main does, and the next 0.7 patch publishes it, so removing it in 0.8 would be a removal inside the major line (Principle 3). Two sentences moved with the rule, legal because RM337 is uncut: the symlink reason now reads "it is a symlink or lies under one, and a link can reach outside the module", and the oversize reason "it is larger than the ceiling for a file discovery ships". Three choices the contract left open:

  • A link that stays inside the module is refused too. The rule as filed is "a symlink at any level", and a link's target can change after the compile is checked; so logs/again.log pointing at logs/authoring.log stays behind.
  • A directory the compile cannot list is named. Found while building: a walk skips a directory it cannot list or search without a word, so the files under it stayed behind unnamed, the RM337 class again. _listable asks for read and search (os.access, R_OK | X_OK), since a directory with one and not the other hides its files just the same, and an unlistable directory, logs/ included, draws the unreadable reason in place of its files. It ships nothing new and adds no arm.
  • A directory that resolves elsewhere without being a link is judged as one. A Windows junction is a directory to is_symlink(); the walk asks _reached_through_a_link of every directory it meets, so one draws the symlink reason rather than being walked or passed over. No test here can make a junction. A top-level *.log that is a directory is not a log and stays silent, readable or not, as it was before.
  • The intermediate-level half of the rule is driven directly. Python 3.13's rglob does not descend into a linked directory (it yields the link, which draws the symlink reason), so no compile reaches a file under one. The resolved-path comparison is still the rule as filed, and a test drives the real function on such a path, where an is_symlink() on the leaf alone would ship it.

Tests: compiler/tests/test_logs_containment.py, one per instance, red before the code: a symlinked *.log under logs/ pointing outside and one pointing inside; a symlinked top-level *.log; a logs/ that is a link to a directory of valid files (one finding, logs, and nothing shipped); a path under a linked directory, judged directly; sparse .log and .txt files one byte over the ceiling beside a top-level one, and two exactly at it that ship; four files made unreadable (.log, .json, .png, and a top-level .log) plus a directory with no permission and one listed but not searched, in both modes; an unreadable logs/; and an explicit log_files list that still ships a link. The permission tests skip as root, and skip when the chmod does not take (an NTFS mount ignores the mode). RM337's fixture gained an unreadable .json, so its walk over the arms reaches the new one, with the same carve-out. Each mutation turned a test red before the code was kept: no link check, the leaf is_symlink() alone, logs/ walked through a link, the top level not judged, the ceiling on images only, >= at the ceiling, OSError uncaught, a .log stat-ed but not opened, the unreadable arm given not_utf8's sentence, every directory listable, read asked without search, an unlistable directory skipped, and an unreadable top-level directory named *.log judged. A test that refuses the open itself for chosen paths reaches the unreadable arm on a runner that is root, where the mode-based tests skip. One did not, and its guard was removed rather than kept: _listable(logs_dir) before the walk, which rglob on an unreadable directory already makes a no-op.

RM337 — a file under logs/ that is not *.log is dropped from the compile, and nothing says so

Severity medium · Status ✅ SHIPPED 2026-11-04 on 0.8, uncut — a minor (corrected 2026-11-04 from "a patch"; taken into 0.8 the same day, PROPOSAL_0_8_PT2 §5 A7) · Owner compiler (_collect_logs) · Motivating case S125 in CONSUMER_SUGGESTIONS_HISTORY.md (just-module-creator F116, 2026-10-05) · related RM338, RM147, RM308

Residuals none

0.8, decided 2026-11-04. The maintainer told the lead to push its ready-to-build minors into 0.8's scope, and the lead listed this one as ready. It also carries the half of RM338 that needs the new warning code.

Reproduced 2026-11-03 on a copy of reference_examples/apoe_epsilon with six files under logs/ (authoring.log, trace/session-a.jsonl, run.json, notes.md, notes.txt, fig.png): compile_module succeeds, no warning mentions a log, and both manifest.logs and the output's logs/ hold logs/authoring.log alone. Discovery globs *.log at the top level and logs/**/*.log below it, and skips everything else under logs/ without a word. The registry's server-side compile leaves discovery to the compiler, so an upload carries the file and the published version does not. After RM338 synced into 0.8 the set that ships was wider, and the rest still went unmentioned: an SVG, a .bin and a .json that does not parse, beside authoring.log in an apoe copy, compiled green with warnings_summary holding vrs_coverage_incomplete alone.

The patch, as filed. A coded warning, in both modes, naming each file under logs/ that discovery left behind. It changes no verdict and ships nothing new, so it is legal whatever RM338 decides; once RM338 widens the set, the warning names whatever is still left out. An explicit log_files list is unaffected, since it already ships any path it names. The new code owes a features/ scenario.

Sized wrong at filing; a minor (2026-11-04). No existing member of VALID_WARNING_CODES names this finding, and every compile warning must carry one (compiler/tests/test_warning_codes.py), so the item adds a member. A new member is minor-class: Compilation.warnings_summary validates its keys, so a reader pinned to an older just-dna-format refuses a manifest that carries the new code. RM308 is the shipped precedent ("a new warning code, so minor-class"). A logger line would be patch-legal and is not taken: it is not the warnings channel, so the registry's server-side compile, where S125's file goes missing, would still say nothing to the uploader. Borrowing a code that names another finding is refused too (@warning-code-names-the-finding).

What shipped. log_file_not_shipped (actionable), one warning per path under logs/ that discovery leaves behind, in both modes and never a refusal: <path> does not ship with the module: <reason>. (LOG_NOT_SHIPPED_PHRASE is the pinned fragment). RM338's _log_content_agrees returned a bool; it became _log_left_behind_reason(path, logs_dir) -> str | None, which holds every arm of the verdict, the .log short-circuit, hidden paths and symlinks included, and returns the reason or None. One function decides and explains, so the two cannot drift (@answered-is-not-absent). Its fixed sentences, one per arm, are LOG_NOT_SHIPPED_REASONS: a hidden path; a symlink; an image over LOG_IMAGE_MAX_BYTES, with both sizes; an image whose first bytes are not its format's signature, naming the extension; an SVG, "XML that can carry script"; any other extension, naming it and the ones that ship; text that is not UTF-8, with the file offset of the first bad byte (a byte-order mark counted, so the decode strips the mark itself rather than through utf-8-sig, whose offsets start after it); a .json that does not parse; and a .jsonl line that does not parse, numbered with blank lines counted, as an editor counts them. A .json nested past the recursion limit takes the same .json sentence. The reason carries nothing from an interpreter's error message, because the line reaches manifest.json and the release sweep compares it. _collect_logs returns its warnings beside the entries, and compile_module extends the channel with them, so they reach CompilationResult.warnings, manifest.compilation.warnings_summary and the compile output. Three choices the contract left open:

  • A symlink is judged whatever it points at. A link to a directory, or to nothing, was skipped silently by RM338's is_file() filter; now it draws the symlink reason, since discovery never follows it. A dangling link named .log is a symlink too. A link to a file named .log still ships, as before.
  • One line per file, with no cap. The decision was to name each file, so there is no _examples truncation; warnings_summary counts them, and @warning-code-names-the-finding refuses a cap because it hides findings from the author who has the most.
  • validate does not emit it. The pre-flight reads no side-car asset, and a warning owes no validate/compile parity (@validate-refuses-all is about refusals).

Out of scope, as RM338 left it: the top level, where only *.log is discovered and any other file is the spec directory's ordinary tolerance of unknown files; and an explicit log_files list, which ships what it names and draws no warning.

Tests: compiler/tests/test_logs_not_shipped.py. A copy of apoe_epsilon carries files that ship and paths that stay behind, every arm reached (two .json, one of them nested past the recursion limit; a .jsonl whose third line is bad after a blank; latin-1 text, and a .md with a byte-order mark, a bad byte at file offset 5 and a space in its name; a GIF named .png and a PNG named .jpg; a png one byte over the ceiling; a hidden .md and a hidden .svg; a link to a file, a dangling .log link and a link to a directory). In both modes it asserts exactly one finding per left-behind path, each holding its own arm's sentence and no other's, the line number, both offsets and both sizes, the count in warnings_summary, the rest of the channel equal to the pristine apoe compile's, nothing in carried, and both identities unchanged. A second test asserts the sentences pairwise distinct, none containing another, and drives the real function over one file per arm, the arms walked as the registry's keys; others cover lap stability, the explicit list, the top level and the CLI in both modes. Paths are read off a finding by splitting at the pinned phrase, never at the first space. test_logs.py's RM338 "adds no warning" test became "warns only about what stays behind". Each mutation turned a test red before the code was kept: every arm switched off or given another arm's sentence, latin-1 accepted as UTF-8, the offset counted after the byte-order mark, the .jsonl numbering skipping blanks, .log checked, the warning not appended, the channel not extended, and an explicit list running discovery.

Found by review and left as RM338 shipped them, since each changes what ships, not what is said (reported to the lead, unfiled): a symlinked *.log ships, and so does everything under a logs/ that is itself a symlink; text has no size ceiling; and an unreadable file under logs/ raises out of the compile rather than staying behind.

RM347 — the HuggingFace module publisher uploads no logs, although manifest.logs lists them

Severity low · Status ✅ SHIPPED 2026-11-04 on main, uncut — a patch (filed 2026-11-04 by the lead) · Owner enricher (upload._manifest_logs, upload.plan_upload) · Motivating case found while building RM338 · related RM338, RM337, S125

Reproduced by reading the code (2026-11-04). upload._ALLOW_PATTERNS is the artifact parquets, manifest.json, the logo and the README candidates. No logs/ path is in it, not even *.log, so a module published through the enricher's HuggingFace publisher carries a manifest whose logs names files the repository does not hold. verify --check-logs skips an absent log by design, so nothing reports the gap. RM338 widened what logs/ ships at compile, which makes the difference larger: an author who sees log ships: … at compile then publishes a module without it.

The patch. The allowlist takes every path manifest.logs names, derived from the manifest the directory carries rather than restated as a pattern (@publisher-allowlist-derived). A test publishes (plans the upload of) a module with .log, .jsonl and .png logs and asserts each is in the plan. Not decided here: whether a log the manifest does not name, present on disk, is uploaded; the default is no.

Shipped. plan_upload appends every path manifest.logs names to UploadPlan.files, read field by field out of the manifest JSON by the reader the attestation check already used (now one helper, _manifest_document), never a glob. The open default is decided as filed: a file under logs/ the manifest does not name is not uploaded. A named path that is absolute, contains .., resolves outside the module directory through a symlink is skipped with a warning naming the reason, and the publish goes on; there was no path-escape guard elsewhere to match, so this one checks both the spelling and the resolved path. A hidden path is refused on the compiler's terms rather than a second rule: discovery ships a hidden *.log and no other hidden kind, so the publisher does the same. A blanket hidden refusal was written first and withdrawn, because it recreated this item's defect for a hidden .log the manifest names. Whatever upload_folder's default ignore list drops (.git, .cache/huggingface, read from huggingface_hub) is refused even as a .log, since the hub would never send it. A named log absent from disk is skipped quietly, and an absent or unreadable manifest plans no logs, as before. upload_module now passes the plan itself, glob-escaped, as upload_folder's allowlist rather than _ALLOW_PATTERNS, so the dry run is the upload (the snapshot publisher's rule): the hub matches with fnmatch, and a compiler-shipped logs/fig[1].png unescaped selected logs/fig1.png instead. Tests compile a copy of apoe_epsilon with a .log, a nested .jsonl and two .png logs, and check the plan, the unnamed file, the escaping and hidden spellings plus an unresolvable one (a NUL, on which Path.resolve raises), and what huggingface_hub's own filter, default ignore list included, selects from the files on disk; each derivation was mutated once to watch its test go red.

Residuals none

RM353 — the module publisher diverges from what the manifest declares: provenance is never uploaded, snapshot names are not glob-escaped, and a logs-only republish overwrites a version

Severity medium · Status ✅ SHIPPED 2026-11-04 on main, uncut — a patch (filed 2026-11-04 by the lead) · Owner enricher (upload._declared_files, upload.plan_upload, upload._versioned_conflict, upload._literal_patterns) · Motivating case found while building RM347 · related RM347

One class: the publisher's plan and guard are not derived from what the manifest says it holds. Three instances:

  1. provenance.json is named with a sha256 in manifest.provenance.file, and no allowlist includes it, so it is never uploaded;
  2. publish_reference_snapshot passes file names to the hub as glob patterns unescaped (RM347 escaped the module publisher's), so a name with [ selects a different file;
  3. the overwrite guard for data/<name>/v<version>/ compares only artifact.digest, which excludes logs by design, so a second publish with changed logs replaces them without --force.

The fix derives the upload set from every file entry the manifest declares (artifact, logs, provenance, logo, readme), escapes every pattern in both publishers through one helper, and widens the guard's comparison to the declared files' hashes. Not in scope, under the existing rule: the flat data/<name>/ path keeps stale files, since a publish deletes only what was declared (@a-publish-may-not-orphan-the-bytes-it-stops-describing).

Shipped. One helper, _declared_files, reads every file the manifest declares in the module directory out of the JSON _manifest_document returns: artifact.files, logo, readme, provenance (a summary carrying file and sha256, which is why a FileEntry walk never saw it) and logs. inputs and derived are left out, since they describe files beside the spec. plan_upload sends manifest.json plus those files when artifact.files is legible, and nothing else: a parquet an earlier compile left in the directory, or a logo the manifest does not name, now stays behind (the old allowlist sent both, and a stale parquet on the flat path reads to discovery as part of the module). RM347's path guard, renamed _declared_refusal_reason, reads every declared name, so a hand-edited provenance.file of ../x is skipped with a warning; an attested parquet refused or absent still raises rule 1, and an optional one absent is skipped quietly. A declared file whose bytes on disk no longer hash to the stated sha256 refuses the plan (found in review: the guard compares manifests, so a log appended to after the compile would otherwise pass it). With no readable manifest or no artifact.files list the plan falls back to _ALLOW_PATTERNS on disk, as before. _literal_patterns is the one escaping helper, applied to the module publisher's allow_patterns, both of the snapshot publisher's, the declared retirement's delete_patterns (LayoutShift.retires is one name, never a glob) and, beyond the two publishers the item named, prune_repo's delete_patterns, where an unescaped listed name would delete a file nobody was shown. The guard, _versioned_conflict, compares artifact.digest and then every declared file's sha256; a hash that differs, or a file declared on one side only, is a PublishCollisionError whose message says the same compiled data but different declared files and names each one. A declaration with no legible hash is not compared. PublishCollisionError stays the type on main. One test fixture changed with it: the RM199 retirement test passed retires="data/old-*.parquet", a glob the field forbids, and now passes a name. Tests compile copies of apoe_epsilon carrying a provenance.json, a logo, a README and a log, and check the plan against the declared set, an undeclared stale parquet and logo, an escaping provenance.file, a snapshot file data/chr[1].parquet beside a data/chr1.parquet decoy, a retirement and a prune of a [ name, a logs-only recompile at the same version (digest equal, refused, then sent under force), and a log declared on one side only. Each derivation was mutated once to watch its tests go red: the provenance arm, the derived plan (back to the allowlist union), the escaping helper, and the declared-hash comparison.

Residuals none

RM355 — the module publisher reads one manifest three ways, so upload --dry-run tracebacks on every refusal

Severity low · Status ✅ SHIPPED 2026-11-04 on main, uncut — a patch (filed 2026-11-04 by the lead) · Owner enricher (upload.py, cli.py upload) · Motivating case a 0.8 builder's report, 2026-11-04, reading the RM353 publisher · related RM347, RM353

One class: one manifest, several readers and filters. RM353 gave the plan and the guard one reader of what the manifest declares (_declared_files), but three readings are still apart:

  1. upload --dry-run calls plan_upload outside the try that the real run's upload_module sits in, so a refusal the real run reports as a message comes out of a dry run as a traceback;
  2. _module_version opens and parses manifest.json itself instead of reading _manifest_document's object, so the version and the file list come from two reads;
  3. _named_entries keeps an entry whose name is "", which _declared_files drops, so the attested-parquet list and the declared list disagree on the same entry.

The fix, as one rule. One reader of the manifest document and one filter of its file entries, which every helper calls; the dry run goes through the same refusal handling as the real run and prints the same message.

Shipped. One reader: _manifest_document returns the parsed object together with the reason there is none (absent, unparseable, not an object), and _module_version is now a pure function of that pair, so the four version_unknown_reason strings are unchanged. plan_upload reads once and builds the plan through _plan_from_document; upload_module reads once and hands the same object to the plan and to _versioned_conflict, where it used to read the file a third time. One filter: _named_entry keeps an object whose name is a non-empty string, with its sha256 or None, and _attested_parquets, _declared_files and the plan's new refusal all read through it (_named_entries is gone), so the two lists agree about an artifact.files entry named "". The plan refuses that entry, quoting it, rather than dropping it: it is inside artifact.digest, so dropping it quietly would publish a digest no upload can satisfy (@an-absent-input-is-the-unknown-arm-and-a-malformed-one-is-the-refusal; found in review, after a first build that dropped it). It used to refuse too, as attests [''] with a hint to recompile "if the file is missing". An optional declaration naming no file stays dropped, since it is outside the digest. upload --dry-run now calls plan_upload inside the same try as the real run, so a refusal prints the same UPLOAD FAILED: … line and exits 1 without a traceback. The dry run still contacts nothing, so it cannot report a versioned-path collision, which needs the published manifest; the test uses a refusal the plan raises (a declared log appended to after the compile) and compares the dry run's stderr with the real run's. ENRICHER.md's signature block gains upload_module's force and both snapshot functions' keyword-only payload. Tests: the dry run and the real run on one refused module (same stderr, SystemExit rather than the refusal), a counting test over io.open on manifest.json, which every way of reading a file passes through (one read for a plan and one for a publish), and an empty-name entry (absent from both lists, refused with the entry quoted). Each was mutated once and went red: the dry run moved back outside the try, a second read inside the plan (through read_text, then read_bytes), the filter without its empty-name guard, and the refusal removed.

Residuals none

RM354 — the GWAS Catalog retired the legacy REST API the gwas pass reads, so gwas_effects.csv cannot be filled for a new module

Severity high · Status ✅ SHIPPED 2026-11-04 on main, uncut — a patch (filed 2026-11-04 by the lead; widened to the class by the lead the same day) · Owner enricher (gwas, net, and every client in test_client_exception_contract.CLIENTS) · Motivating case the RM333 builder's report, 2026-11-04, recorded in docs/probes/LANES_0_8.md §5.5 on build/RM333 · related RM239, RM333, @client-exception-contract

One class: a source retired an API surface, and the client has no finding for it. GwasCatalogClient asks https://www.ebi.ac.uk/gwas/rest/api/singleNucleotidePolymorphisms/<rsid>/associations (DEFAULT_GWAS_ENDPOINT). That endpoint now answers HTTP 410, "This legacy GWAS Catalog REST API is no longer available", pointing at the v2 migration guide; /gwas/rest/api/v2/associations?rs_id= answers 200. The 410 falls into the generic httpx.HTTPError arm and becomes a plain GwasError, which the pass records as could-not-ask. So every rsID of every new module reads as an outage, nothing is filled, and nothing says the source moved. RM239's posterior is filled only on gwas_effects.csv rows that already exist.

The fix, as one rule. The client moves to the v2 endpoint (its response shape probed from the real answer first, @probe-the-real-file), and a 410 from any endpoint raises a named retired-endpoint error, a GwasError subclass whose message carries the URL and the source's own text, never the generic failure. A subclass makes a caller's except order load-bearing, so the handler shapes are enumerated before it lands. Every other client that maps status codes gets the same 410 arm, since retirement is a currency fact about the source, not one lane's bug.

What the hand-run found (2026-11-04). The legacy path answers 410, text/plain, on every path including /studies/<accession>. v2 answers associations?rs_id=rs4149056 with 20 of 386 per page and a _links.next; size=1000 returns all of them. Three facts shaped the client. The empty answer is a 200 with no _embedded key at all (page.totalElements: 0), for a rare variant and a nonexistent rsID alike, so the legacy guard ("no _embedded.associations means the shape changed") would have refused every clinically-authored module on its first rare variant; it now raises only when the page does not say zero. A 404 stopped being an answer: the only one v2's search gave was a wrong path, so associations_for no longer reads it as "no associations" and gwas left FOUR_OH_FOUR_IS_AN_ANSWER. The effect is one composite string ("0.05 umol/l increase", "-" beside an odds ratio), parsed by one grammar and withheld whole outside it. standard_error has no v2 field and stays null; pmid, accession and EFO trait are inline, so ancestry (/studies/<accession>/ancestries) is the only follow and the request budget on hfe_hemochromatosis fell from 382 to 190. The association ids carried over (legacy 13069 and 55421052 are v2's too), so a legacy-filled table merges rather than doubling. The full field map is ENRICHER.md § GWAS effect sizes.

The class, built in the same item at the lead's call. The contract test written for the GWAS 410 was run over every CLIENTS row and measured the rest of the class: no client named a 410, and six (gnomad, eutils, cpic and its row_count, pharmvar, currency) retried every HTTPStatusError, asking a 400, 404 or 410 three or four times. Now a retry predicate retries transport, timeout, 5xx and 429 only (net.retry_if_transient), and a 410 raises the client's own *Retired, a subclass of its could-not-ask type (net.raise_if_retired builds the one message). Three tests hold it: test_every_client_names_its_410 (an equality with the CLIENTS labels), test_a_permanent_4xx_is_asked_once (400, 404, 410 over every row), and test_no_retry_policy_in_the_tier_retries_a_permanent_4xx, which walks every @retry in the package and asks its predicate directly, so the withholding clients and the builders' download are covered too. Each client's 404 meaning was checked and kept; ENRICHER.md tables it. The handler shapes were enumerated before the subclasses landed: no except in the tier names a sibling narrowing a *Retired could fall into (RateLimitedError, EutilsRateLimitedError, GwasNotFound), and every *Unavailable handler catches it, by design. Each guard was broken once to watch it go red: the 410 arm in gwas, a widened pharmvar predicate, and litvar's 410 arm.

What the code review changed before the close. The effect allele is taken from the snp_effect_allele entry naming the queried rsID (a multi-SNP association's first entry is another variant's); gwas retries a 5xx and a 429 too, which moved its status translation out of the retried body into _get; v2's - is an absent pmid; a templated next link is stripped like every other link; the CLI prints unparsed_effects and unusable; associations_for was a test-only wrapper and is gone. Kept as built: a 404 on the search is could-not-ask and aborts the pass like any outage, and size=1000 was measured to return all 386 associations, not assumed.

Bounded on purpose. The withholding clients (grch37, ensembl, clingen_allele, Crossref, EuropePmcClient.fulltext) raise nothing by contract. A 410 there is withheld like any other failure, and is not retried. A handler that records a client's could-not-ask type as unreachable records a *Retired there too, with the retirement in its reason, since the subclass keeps every handler catching it.

Residuals none

RM338 — which files under logs/ ship: *.log only, a text allowlist, content-checked text, or images too

Severity low · Status ✅ SHIPPED 2026-11-04 on main, uncut — a patch (decided 2026-11-03, unattended) · Owner compiler (_collect_logs); built by the lead · Motivating case S125 in CONSUMER_SUGGESTIONS_HISTORY.md (just-module-creator F116, 2026-10-05) · related RM337, RM147

The ask. The reporter wants a JSON Lines session ledger (search receipts, fetch receipts, decisions) to travel with a module, and offers, in order: decide on content rather than the name (.log, .txt and .md decode as UTF-8, .json parses, every non-blank .jsonl line parses); failing that, the allowlist .log .txt .md .json .jsonl; and images as a question rather than a request (png/jpg can be checked by magic bytes as LOGO_EXTENSIONS already is; SVG is XML that can carry script).

Legality. No schema moves. manifest.logs is a list of FileEntry, and artifact_digest hashes manifest.artifact.files only, so no module's byte or content identity changes. P3 and P8 do not reach it. What it changes is exposure: a module that already has a stray notes.md under logs/ starts shipping it at its next recompile, and a published file is permanent. That is why this waited for a decision instead of being built unasked.

Decided (the maintainer, 2026-11-03): content-checked text, plus images. Of four options put to them, they chose "Text checked + images". Under logs/, .log .txt .md .json .jsonl ship when the content agrees: text decodes as UTF-8, .json parses, and every non-blank .jsonl line parses. png/jpg/jpeg ship when their magic bytes match, as LOGO_EXTENSIONS is checked, and under a size ceiling. SVG never ships, since it can carry script. A file that fails its check stays behind with RM337's warning, naming the reason. Each file that ships and is not *.log is named in the compile output, so an author sees it before publishing. The size ceiling is the lead's constant to pick. The rejected options: *.log only (the reporter's ledger would never reach a published module, because the registry compiles by discovery); an allowlist by extension alone (a binary named .json ships); and text without images (images were raised as a question, and the maintainer took them in). Whether a failed check refuses under strict was not put to the maintainer. The default is a warning in both modes, since this changes no verdict. RM147's advice against a logs/ writer still stands and is not reopened: this carries the consumer's own ledger, it does not give the format a ledger schema.

The split (the lead, 2026-11-04). RM337 became a minor the same day, because its warning needs a new VALID_WARNING_CODES member. So this patch ships only what needs no new code: the content checks, and each newly shipped file that is not *.log named by a standard-library logging line and listed in manifest.logs. The warning for a file left behind, the failed check's reason included, goes with RM337 in its minor. Until then a file that fails its check stays behind exactly as before, with nothing said.

What shipped. _collect_logs walks everything under logs/ and asks _log_content_agrees of each file whose lowercase extension is in LOG_TEXT_EXTENSIONS (log txt md json jsonl) or LOG_IMAGE_MAGIC (png jpg jpeg). Text must decode as UTF-8, a byte-order mark allowed (a Windows editor writes one, and json.loads refuses it); .json must parse as one document, and every non-blank .jsonl line on its own, a line being what ends at \n (str.splitlines() also breaks at U+2028, which JSON allows raw inside a string). A .json nested past the recursion limit raises RecursionError rather than ValueError; it is caught too, so the file stays behind instead of failing the compile. An image must be at most LOG_IMAGE_MAX_BYTES (5 MiB, read from stat before any byte) and begin with its format's magic: \x89PNG\r\n\x1a\n for png, \xff\xd8\xff for jpg and jpeg, so a JPEG named .png stays behind. Each file that ships this way is named by an info line on just_dna_compiler.compiler ("logs/notes.md ships with the module (its content matches its name)") and, because the CLI configures no logging and an info line is therefore invisible there, by a log ships: logs/notes.md line in just-dna-compiler compile. Five choices the decision did not settle:

  • *.log is not checked. A .log under logs/ ships whatever its bytes, as before. Checking it would silently drop a .log with one latin-1 byte that shipped at the previous compile, and RM337's warning, the only thing that could say so, has not landed. Only an exact lowercase .log takes this path; a .LOG is checked as text.
  • The ceiling is 5 MiB. That is the line this repository already draws for anything that travels (a larger asset goes through Git LFS), and it sits far above a figure or a screenshot. An image above it is not a log.
  • Hidden paths and symlinks do not take the new route. A path with any part starting with . under logs/ is tool state (an editor's checkpoint, an agent's settings.local.json), and a symlink can reach outside the module; either would ship a valid file nobody put there to publish, and a published file is permanent. Both stay behind as they did before. A hidden or linked *.log still ships, as it always did.
  • The top level is unchanged. Beside the spec only *.log is discovered; the decision is about logs/. An explicit log_files list still ships whatever it names, checks or not.
  • Text has no size ceiling, as *.log never had one; the decision asked for one on images only.

LOGO_EXTENSIONS turned out to be checked by extension only, not by magic bytes, so there was nothing to reuse: the magic table is new, and the logo is left as it was.

Tests: compiler/tests/test_logs.py. One module carries fourteen files that ship (three .log: one with a latin-1 byte, one under a hidden directory; a .jsonl with a blank line, one with a raw U+2028 in a string, and one with a byte-order mark; .json, and one with a byte-order mark; .md; .txt; png, jpg and jpeg with real magic; an upper-case .JSON) and a png exactly at the ceiling, beside sixteen that stay behind (malformed .json, a .jsonl with one bad line, a GIF named .png, a PNG named .jpg, an SVG, latin-1 .txt/.md/.json, a .json nested past the recursion limit, a .bin, a .zip, three valid files on hidden paths, a symlink to valid JSON outside the module, and a real png one byte over the ceiling). It asserts the exact set in manifest.logs and in the output's logs/, the info line for each newly shipped file and for nothing else, warnings and warnings_summary identical to a compile with authoring.log alone, and both identities unchanged. compiler/tests/test_cli.py asserts the log ships: lines, which failed before the CLI printed them. Each of fifteen mutations (no magic test, no size test, >= at the ceiling, the first .jsonl line only, .json not parsed, latin-1 instead of UTF-8, the byte-order mark kept, splitlines() for .jsonl, RecursionError uncaught, a case-sensitive extension, no info line, .log checked, SVG admitted, hidden paths admitted, symlinks admitted) turned a test red before the code was kept.

Residuals RM337 — the warning naming each file left behind under logs/, the failed check's reason included; the logo stays extension-checked and is not reopened here

RM340 — the VRS-coverage warning counts alleles with no ALT and does not point at the record that says why

Severity low · Status ✅ SHIPPED 2026-11-04 on main, uncut — a patch (message text) · Owner compiler (_vrs_coverage warning) · Motivating case S127 in CONSUMER_SUGGESTIONS_HISTORY.md (just-module-creator F118, 2026-10-25) · related RM251, @unreachable-not-absent, @answered-is-not-absent

What stands of the report. After RM251, source="authored" rows with empty ref/alts are two populations: rows with no rsID, which no refresh can fill, and rows whose live rsID the injected Ensembl snapshot predates, which a newer snapshot would fill. The reporter's correction found the split already stated, by name, in verification.json's rsid_coordinate_agreement record ("absent from this snapshot is not absent from Ensembl"). The rows are truthful; what is missing is the join. The compile warning ("VRS allele identity covers 166/183 … 17 allele(s): no ALT recorded") gives no pointer to the record that explains the gap.

The patch. When the spec directory's verification.json carries an rsid_coordinate_agreement record with pairs not compared, the no-ALT line of vrs_coverage_incomplete says so and names the record. The compiler already reads the block at compile (_read_verification_block). Message text only, under @warning-text-is-api: the existing phrase stays and the pointer is appended. Run schema/tests/test_feature_corpus.py, since features/ quotes emission text.

Not taken. A new status member such as position_only, or a second source value. The reporter argues against the second themselves, and @answered-is-not-absent is the house answer to the first: VALID_RESOLUTION_STATUS is a wire vocabulary every reader of a published resolution.csv shares, and the row was never the untruth. Only the reason it gives is missing, and the reason already exists in the attestation.

Residuals none

What shipped. _vrs_coverage_warnings takes unplaced_recorded and appends a pointer to the no-ALT reason line alone, after its unchanged phrase. Both call sites (validate_spec's pre-flight and compile_module) pass _snapshot_unplaced_rsids_recorded(spec_dir), which reads the block through _read_verification_block, so an attestation these bytes no longer match points at nothing. The record is recognised by compiler.SNAPSHOT_UNPLACED_PHRASE ("absent from this snapshot is not absent from Ensembl"), which just_dna_enricher.enrich now imports to write that same sentence, so the writer and the reader share one constant. The two sides produce the same line, and the existing message dedup collapses it to one. No code and no vocabulary member was added.

Tests: test_fact_tables.py (the pointer changes exactly one line, the no-ALT one, and that line still begins with its old text) and test_verification_block.py (apoe_epsilon carries two no-ALT alleles: an attested record with the phrase adds the pointer on both sides, once in the manifest; a record without it, or a stale one, leaves the line bare). features/compiler/identity_and_vrs.feature has the scenario; COMPILER.md's warning catalogue states the pointer.

RM339 — an interrupted snapshot pull leaves a cache that reads as complete, so it is never finished

Severity high · Status ✅ SHIPPED 2026-11-04 on main, uncut — a patch (enricher only) · Owner enricher (download._provision_snapshot, the parquet resolvers, caches.prepare_lane) · Motivating case S126 in CONSUMER_SUGGESTIONS_HISTORY.md (just-dna-registry warm-caches, 2026-10-08) · related @a-derived-lane-has-parents-and-an-absent-parent-is-not-an-empty-result, @a-failed-fetch-is-not-a-no-op

Reproduced 2026-11-03. A cache directory holding one footer-valid homo_sapiens-chr1.parquet and nothing else: ensure_snapshot returns it without touching the network. if existing and not corrupt: return cache_dir trusts any non-empty set of whole files, and the .part-then-rename staging that keeps each file whole is exactly what makes an interrupted pull look finished: every file present verifies, and the missing ones leave no trace. The lane's resolve() inherits the answer, so warm-caches, its dry run and just-dna-lite's prepare-caches agree the lane is present. In the reported run that was 3 of 25 chromosomes, and enrich would have resolved rsIDs against them silently. Every snapshot sharing the helper has it.

The patch. Trust a cache only when it carries a record of a finished pull and every file the record names is present and whole; without one, fetch what is missing and skip what verifies, which keeps "no network on a warm cache". The reporter's candidate writes that record at the end of a successful pull. release.json is already fetched last, after every parquet, so where a repo publishes one its presence marks a finished pull; whether it lists the files, and whether every lane's repo publishes one, is the first thing to check when building, before adding a file to the layout (locations, and docs/CACHE_SURFACE.md's checklist). Caches provisioned before the record existed either refetch once or are compared with the remote listing the first time the network is reachable; that choice is the build's. Second, smaller: name HF_HUB_DOWNLOAD_TIMEOUT in the error a read timeout raises, since the 10 s default is short for files of 0.5–1 GB.

Residuals none

What shipped. release.json could not be the record: it lists no files, and the Ensembl lane, the reported one, publishes none. The record is a new file, locations.PULL_RECORD_FILENAME (pull-record.json beside data/), kept out of SNAPSHOT_ROOT_FILENAMES so no publish carries it. _provision_snapshot lists the data and the sidecar directories, writes the record atomically, and only then downloads. Written first rather than last, because a record written at the end leaves an interrupted pull looking exactly like a cache from before the record existed.

  • locations.snapshot_record_missing answers three ways: [] (complete), the named files that are absent or fail the footer check (an unfinished pull), or None (no record). Both parquet resolvers return None for an unfinished pull, so cache status, prepare, warm-caches and enrich stop calling it present; Ensembl's prebuilt .duckdb keeps its standing. The footer check moved to locations.parquet_footer_ok, kept importable as download._parquet_footer_ok.
  • A recorded complete cache is not even listed. A cache with no record (built here, or pulled before RM339) is compared with the listing once, fetches what it lacks and gains a record. When the listing cannot be read it is used as it is, with a warning that its completeness is unknown, and no record is written.
  • prepare_lane sends an unrecorded parquet cache in the default directory through ensure once, when the terms permit a pull, and reports pulled if files arrived. An override pointing elsewhere, a gated lane under an unstated use, and a recorded cache stay present as before.
  • A read timeout (httpx.TimeoutException, after the transport's retries) raises the lane's own error naming HF_HUB_DOWNLOAD_TIMEOUT and its current value, and leaves no .part behind.

Tests: test_download.py (an interrupted pull, run through a fake that lets one download through and kills the next, is not resolvable and the next call fetches only the two missing files; a truncated recorded file; a recorded cache asks nothing; an unrecorded one is listed once, completed when partial, and served offline; the timeout message) and test_cache_lanes.py (the prepare route, and the three places it stays present). The resolver half was shown on main first: a cache holding one of a snapshot's files resolved as present. ENRICHER.md's cache pull paragraph, the cache pull docstring and AGENT_NOTES @a-failed-fetch-is-not-a-no-op say the new rule.

RM343 — duckdb 2.0 spells the hash join Hash Join, so a query-shape test goes red on a fresh install

Severity low · Status ✅ SHIPPED 2026-11-04 on main, uncut — a patch (a test's assertion; no package change) · Owner enricher (tests) · Motivating case the liaison's run of the enricher suite under duckdb 2.0.0, docs/UPSTREAM_DUCKDB.md (2026-11-03)

Measured. Under duckdb 2.0.0 the enricher suite gives 2280 passed and 1 failed: test_query_shapes.py asserts "HASH_JOIN" in the EXPLAIN text, and 2.0 prints Hash Join. The plan is the same hash join, and the timing test passes. duckdb>=1.1.0 is uncapped, so a fresh install takes 2.0.

The patch. The assertion reads the operator name in either spelling. No cap, since nothing else in the suite moved. Capping a runtime dependency to keep one test's string would hold every consumer back for a test.

Residuals none

The liaison's ledger (docs/UPSTREAM_DUCKDB.md) keeps the rest of 2.0's read.

What shipped. test_lookup_clin_sig_is_a_hash_join_not_an_or_chain upper-cases the plan text and turns spaces into underscores before looking for HASH_JOIN. The old assertion was run under uv run --isolated --with duckdb==2.0.0 and failed on a plan whose operator box reads Hash Join. The new one passes under the locked 1.x and under 2.0.0.

Severity high · Status ✖ CLOSED 2026-11-04 — the cap was reverted before it was pushed; no cap, the maintainer's decision · Owner compiler (packaging) · Motivating case the liaison's measurement, docs/UPSTREAM_POLARS.md (2026-11-03) · related RM342, RM304

Measured. polars>=1.42.0 has no upper bound. polars 2.0 writes created_by = 'Polars (python) version <v> (build <hash>)' into the parquet footer (pola-rs/polars#29106, following the parquet spec). The liaison compiled three reference examples twice under 1.44.2 and once under 2.1.0. The tables, schema, codec and row groups are equal, but every parquet's sha256 and every artifact.digest differ, while 1.44.2 reproduces itself byte for byte. P4 pins reproducibility to compiler_version, so one compiler release installed beside two polars releases would mint two digests for one spec, with nothing in the manifest saying why.

The patch. Cap polars<2 in the compiler, which the enricher inherits, the way RM304's ga4gh.vrs<2.4 mitigation was shipped. Add a test that reads the footer of every parquet a real compile writes and fails when the installed polars version appears there, so the cap cannot be lifted quietly. It is lifted only by RM342.

Residuals RM342 records the toolchain, so a digest that differs between installs can say why.

Reverted, and the rule that replaced it (the maintainer, 2026-11-04). No cap on polars or duckdb. polars-bio already caps just-dna-lite at polars<2, and a second cap here would block every other consumer. The rule: the liaison decides adoption blockers and hands the lead an adoption map. A pin goes in only when a new major is proven to break something, and stays until support is integrated. When the liaison is unavailable to settle compatibility and work has to move, the lead may pin as a safety. polars 2.x breaks nothing here: under 2.x the tables and content_signature are equal, and the digest moving between installs is what P4 already scopes to a fixed toolchain. The cap and its footer test were removed in the commit after the one that added them, both unpushed. The footer test was dropped as well, because it would go red the day uv.lock moves to polars 2. That move is the liaison's adoption map, item 4: every digest moves once, and the release records that the content is unchanged.

What was built, then reverted. compiler/pyproject.toml pinned polars>=1.42.0,<2, and uv lock changed only the specifier. compiler/tests/test_parquet_names_no_toolchain.py compiles apoe_epsilon and reads each parquet's thrift footer straight from the bytes (the compiler tier has no pyarrow). It fails when pl.__version__ appears there. Run before the cap under uv run --isolated --with polars==2.1.0, it failed on diplotypes.parquet and haplotypes.parquet, naming 2.1.0. Under the locked 1.44.2 it passes. That run checks the liaison's measurement on this machine rather than relaying it.

RM320 — PubMind's terms are answered: the ANNOVAR table is CC BY-NC-ND 4.0, so a module carrying it is non-commercial and the build gates on --use

Severity medium (it moves a compile outcome) · Status ✅ SHIPPED 2026-10-02 on main, uncut — a patch (a corrected terms constant and the gate it feeds; no schema change) · Owner enricher (licensing.py, pubmind_build.py, pubmind_draft.py, caches.py, cli.py) · Motivating case WGLab/PubMind#5, asked 2026-09-27 and answered 2026-09-28 · related RM134, RM289, RM27, S99, @no-named-licence, @acquisition-gate-is-not-a-read-gate

Residuals none

RM134 shipped with PUBMIND_TERMS at None on every axis because no page stated terms for the ANNOVAR-distributed table, and named asking WGLab and CHOP as the only unblock. The postmortem listed it as never asked (P16); it was asked on 2026-09-27. A WGLab collaborator replied that the lightweight PubMind-DB release (aggregated pathogenicity and confidence, via ANNOVAR and Zenodo) is CC BY-NC-ND 4.0. The software and the full PubMind-DB stay under CHOP's LICENSE.md, and the Zenodo CC BY 4.0 label was their mistake, now corrected. The reply covers exactly the file pubmind build reads.

  1. PUBMIND_TERMS is license="CC-BY-NC-ND-4.0", commercial_use=False, share_alike=False, redistribution=True, the reading ARTICLE_TERMS_BY_LICENSE already gives the licence, and a test holds the two equal. license_url is the written answer. NoDerivatives has no axis, so it is in notice.
  2. The compile outcome moves. A pubmind licence row now taints, so a module carrying one compiles only under non_commercial. Before, it compiled under any declaration and the manifest named pubmind in unknown_terms_sources. A module drafted before this keeps its all-null row, because sources.csv merges never clobber; deleting the row and re-drafting records the terms. That is declared here and in the CHANGELOG rather than repaired, because overwriting a recorded licence row is the thing the never-clobber rule protects a curator's hand-edit from.
  3. pubmind build gains --use, and cache rebuild gates the lane. The flag was refused while the gate could only skip; with a no-sale source it answers per declaration, as on clinpgx build. The lane's terms field now carries PUBMIND_TERMS.
  4. The drafter is still not gated, on the same rule as before: reading an operator-built snapshot is not a fetch. Its warning now names the licence and the --use non-commercial the compile will ask for.
  5. pubmind publish still refuses, for a new reason: the snapshot decomposes and normalizes the table, which makes it adapted material, and NoDerivatives bars sharing that. The refusal, the lane's unpublished reason and release.json's notice say so.

RM316 — the annotated_alt element rule counts by ALT position, and VCF 4.5's local-allele fields order their values through LAA

Severity low (medium for the first module that points at an A/R/G FORMAT field with it) · Status ✅ SHIPPED 2026-09-30 on main, uncut — a patch · Owner format (vocab.ELEMENT_RULE_MEANINGS) + docs (the consumer contract) · Motivating case VCF_4_5_AUDIT § 5, 2026-09-30 · related RM53, RM54, RM57, RM313

Residuals none

What 4.5 added. §1.6.2: LAA lists, per sample, which ALT alleles are in play and in what order. Every A/R/G FORMAT field has a local equivalent (LAD, LPL, …) read through it, and a file may carry only the local one. In the spec's example, ALT A,C,T,<*> with LAA=2,4 gives LAD=20,30,10 as REF, C, <*>.

What we say. annotated_alt is "at its index in the record's ALT list, which is element index+1 on a Number=R field". On LAD, ALT C (index 2) is element 1. A module rightly writes source_field=FORMAT/AD. A consumer whose merged 4.5 file carries only LAD, and falls back to it under our sentence, reads the wrong allele's depth: well-formed and wrong.

The patch (text). In annotated_alt's meaning and in the consumer contract: resolve a local-allele field to its global equivalent through LAA before applying any element rule, as §1.6.2 recommends. The value-ranging rules survive unchanged. A local_annotated_alt rule is refused, because it would make the module describe how the consumer's file was merged (P2).

What shipped (text only). ELEMENT_RULE_MEANINGS["annotated_alt"], which the authoring reference prints, now says a VCF 4.5 local-allele field (Number LA/LR/LG) orders its values by the sample's LAA and is resolved to its global equivalent through LAA before this or any rule applies. SCHEMAS.md's element-rule contract gains the paragraph with §1.6.2's worked example, and records that a local_annotated_alt rule is refused (P2). No rule added, no code. RM315 transcribed the L* keys and their Number codes in the same batch.

RM315 — the VCF reserved-key tables we transcribe miss keys the spec reserves, among them RUC, and name no spec version

Severity medium · Status ✅ SHIPPED 2026-09-30 on main, uncut — a patch · Owner format (vocab.VCF_FIELD_NUMBER, VCF_COLLIDING_KEYS, VCF_NUMBER_MEANINGS) + docs · Motivating case VCF_4_5_AUDIT §§ 3–4, 2026-09-30 · related RM53, RM54, RM57, RM313

Residuals none

What is missing. VCF_FIELD_NUMBER claims to transcribe the spec's reserved keys, but it lacks §3's INFO keys (RUC, RN, RUS, RUL, RB, RUB, CIRUC, CIRB, SVLEN, CIPOS, CIEND, CILEN, CICN, …), §4's FORMAT CICN, NQ, HAP and AHAP, Table 2's PP, and every 4.5 key (LEN, LAA, LA, the local-allele family, the base-modification aliases). CICN is reserved in both namespaces with different cardinality, like CN, and is absent from VCF_COLLIDING_KEYS. And no doc a consumer reads says which spec version the tables describe.

Why it bites. binning._VCF_MEASURE_FIELDS names RUC as the field a repeat_count is read from, and RUC is Number=.. Probed on htt_repeat_expansion with source_element emptied: INFO/RUC gives no warning, while FORMAT/AD gives vcf_pointer_unselected_element.

The patch. Transcribe the missing keys, add CICN with its sentence in VCF_COLLISION_REASONS (asserted total), and fix the comment placing the structural keys in §5.6 (they are §3 and §4). Add VCF_NUMBER_MEANINGS entries for LA/LR/LG/M: it is read through .get(..., default), so a missing meaning prints the default silently (@lookup-with-a-default-hides-a-new-member). Assert equality between the codes the table uses and the codes the meanings cover. State "VCF 4.5; a key added after it is unknown and withholds" in SCHEMAS.md and COMPILER.md. Leave the pinned "is not a whole number in VCF 4.4" phrase alone: it is API and still true. The M[0-9]+[ACGTUN] family is a pattern, so its named aliases go in, and the ChEBI-numbered form stays unknown. No new code.

What shipped. VCF_FIELD_NUMBER now holds every key VCF 4.5 reserves: Table 1, Table 2 (with PP, LEN, LA, LAA, the local-allele fields and the ten named base-modification aliases in their M/DPM/ADM forms), and the keys §3 and §4 reserve (the structural, copy-number and tandem-repeat keys, RUC among them). It was extracted from the 4.5 LaTeX and compared back to it: nothing missing, no Number disagreeing. The extractor's header regex also picked up example-only keys (ALLELEID, ASP, RSPOS, dbSNPBuildID), which were left out because the spec does not reserve them. CICN joins VCF_COLLIDING_KEYS with its reason. VCF_NUMBER_MEANINGS gains LA/LR/LG/M. Three tests: the multi-valued codes the table uses equal the codes with a meaning; every key reserved in both namespaces is a named collision (a subset, because AF is a collision by practice); and the audit's probe, INFO/RUC with no element rule, now draws vcf_pointer_unselected_element. All three fail on the old table. The comments and SCHEMAS.md/COMPILER.md state VCF 4.5; the pinned is not a whole number in VCF 4.4 phrase is untouched. No new code: an existing warning fires on more pointers, and an existing collision set gains a member.

RM314 — the reference-block rule we print reads INFO END, which VCF 4.5 made a cross-sample maximum, so a multi-sample file credits one sample's block to another's positions

Severity medium · Status ✅ SHIPPED 2026-09-30 on main, uncut — a patch · Owner format (the callable_from description) + docs (SCHEMAS.md, the consumer contract) · Motivating case VCF_4_5_AUDIT § 1, 2026-09-30 · related RM53, RM54, RM57, RM313

Residuals none

What 4.5 changed. §5.5 moves a gVCF reference block's extent to a per-sample FORMAT LEN. §1.6.1 deprecates INFO END and, when it is present, makes it "the maximum end reference position" over every sample's LEN. §5.5 also says a position covered by a sample's own earlier <*> block carries GT=. for that sample.

What we tell consumers. VariantRow.callable_from's description and SCHEMAS.md's Reference evidence is a block paragraph say a block is "one record with END=", found by interval containment on it. In the record 1 100 . A <*> . . END=199 GT:MIN_DP:LEN 0/0:30:100 0/0:30:10, sample two called 100–109 only, and our rule credits it with 150. For a requires_callable row at 150 that is a confident absence nobody screened for: the direction SCHEMAS.md itself calls dangerous. The GT=. rule errs the safe way, but our text still sends the consumer to the wrong record.

The patch (text only). Read the sample's own FORMAT LEN first, and END only where LEN is absent (the spec's own fallback). A . GT inside that sample's own earlier block is that block's call, not a no-call. Update the callable_from description, the SCHEMAS.md paragraph and its quoted 4.4 record, and the consumer contract. No column, no validator: P3 and P8 are not reached. Severity is stated for the file the spec permits; no real multi-sample 4.5 file with per-sample LEN was measured.

What shipped (text only). VariantRow.callable_from's description and SCHEMAS.md's consumer contract (Reading the VCF the pointers point at) now read a block's extent from the sample's own FORMAT LEN first and INFO END only where LEN is absent, say why (4.5 makes END a cross-sample maximum) with the audit's two-sample record, and read a . GT inside the sample's own earlier block as that block's call. The quoted 4.4 record is gone from the paragraph rather than kept beside a rule it no longer illustrates. No column, no validator, no warning code; nothing pinned the old wording.

RM310 — cache rebuild --only cpic lets a CPIC outage escape as a traceback, and the lanes after it never build

Severity medium · Status ✅ SHIPPED 2026-09-29 on main, uncut — a patch (one handler, no surface) · Owner enricher (caches._rebuild_cpic) · Motivating case found 2026-09-29 while vetting RM288 for the 0.8 pt1 proposal · related RM288, RM97, RM101, @client-exception-contract

Residuals RM288 — which side owns a builder's error list, so the next caller cannot name half of it

Reproduced. caches._rebuild_cpic catches (cpic_build.CpicBuildError, ImportError, OSError). cpic_build.build_snapshot fetches through CpicClient, which raises CpicError on a transport failure or a 5xx (RM97 made it do so), and nothing in cpic_build translates it. With build_snapshot stubbed to raise CpicError("… 503"), _rebuild_cpic raises instead of returning a failed RebuildOutcome. The CLI's cache rebuild loop (cli.py, the rebuild_lane call) and rebuild_caches have no per-lane backstop, so every lane after CPIC in registry order is neither built nor reported. prepare_caches survives only through its catch-all except Exception, which reports the lane as a generic crash.

Why it happened. It is the list shape RM288 records: the CLI's cpic_build_ names (CpicError, CpicBuildError) correctly, and the second caller, written later, named one of the two. That is the drift RM96 was the lesson for, and it is the first incident RM288 had lacked.

The patch. Add cpic.CpicError to the handler, and a test that stubs each builder's client to raise its documented type and asserts every _rebuild_* returns an outcome rather than raising. The test walks CACHE_LANES, never a hand-kept list. Which mechanism stops the next drift is RM288's question, not this one's.

What shipped. _rebuild_cpic names cpic.CpicError beside CpicBuildError, as the CLI's cpic build does. test_rebuild_adapters_contain_their_errors.py walks CACHE_LANES, makes each adapter's first builder call raise its documented type (both of CPIC's), and asserts the adapter returns built=False with the error in its detail. A set-equality guard fails when a lane gains an adapter with no stated errors. With the handler reverted, only the CpicError case fails. Routed by the maintainer through a peer session; the mechanism stays RM288's.

RM290 — the "vindicated" reading of an unmatched overlay row exists for one overridable table, and nobody decided the others

Severity low · Status ✅ SHIPPED 2026-09-29 on main, uncut — a patch (a registry field; no finding moves) · Owner schema (overrides.OverlayTarget.vindication) + compiler · Motivating case S60's "what we are keeping regardless of the shape" and RM117, found unhomed by the 2026-09-27 postmortem sweep (P15) · related S60, S52, RM117, RM137, RM311

Residuals RM311 — the gene_validity.csv case this entry names is not an absence, and it needs a value comparison rather than a classification

S60 found that an overlay row which no longer changes anything can mean the source caught up: the author's judgement was later vindicated and the row can retire. The reply kept it as "a property of the design rather than a nice detail", since S52 had seen the same shape. RM117 built it for exactly one table: VINDICATING_OVERLAY_TABLE = "clin_sig_concordance.csv", which the compiler routes away from the generic "may be mistyped" finding.

Confirmed on 2026-09-27. OVERRIDABLE_TABLES has more members, and every other table's unmatched row still reads may be mistyped. On a table whose values a later source release can change (for example gene_validity.csv, whose classifications drift), that is the wrong thing to tell an author whose correction the source has since adopted.

What to decide. Per table, whether an unmatched update has a vindicated reading, and whether that reading is the only one (as on the concordance table) or one of two, which would be withheld (@two-vocabularies-that-do-not-meet-withhold). Turning the constant into a per-table field on OverlayTarget is internal. Reporting it reuses the existing warning code, so it is a patch.

Decided by the maintainer on 2026-09-29: yes, with concordance's shape as the default. Taken as the shape of the mechanism rather than a reading for every table, because generalising vindication-by-absence would tell an author with a mistyped variant_key that the authorities now agree, which is the misleading message RM117 was built to remove, reversed.

What shipped. VINDICATING_OVERLAY_TABLE became OverlayTarget.vindication, a closed VINDICATION_READINGS member (sole / withheld / none) with a mandatory vindication_reason beside it, and VINDICATING_OVERLAY_TABLES is derived from the registry. The per-table decision, checked against each writer rather than assumed:

  • clin_sig_concordance.csv is sole. It holds contested subjects only and is rewritten whole (concordance.py), unchanged from RM117.
  • resolution.csv is withheld. A re-derivation replaces a subject's locus group whole (RM115) and locus_index is a position in it, so the author's corrected locus can return under another index while the source agrees with them. The generic finding already names every reading.
  • The seven merged tables (frequencies, gene_metrics, gene_validity, clinical_assertions, literature, gwas_effects, expression_effects) are none. Each writer merges and never clobbers, and each key is the source's stable identity, so a source adopting the author's value leaves the row in place and the update keeps matching. An absent row was never written, was withdrawn, or is mistyped, and none of those is agreement.

No finding moves, so warnings_summary on every existing manifest is unchanged, and Principle 3 has no correction to declare. Walked tests pin the set to the concordance record alone, refuse a reading outside the vocabulary or without a reason, and assert that no other table's unmatched update is ever called vindicated.

The entry's premise was partly wrong. It named gene_validity.csv as the table where "may be mistyped" is the wrong thing to tell an author whose correction the source adopted. But a source adopting it there does not remove a row: a newer curation joins the currency group, the corrected one stays (classify_currency deletes nothing), and the overlay still matches. So the author is told nothing at all rather than told the wrong thing. The signal is a value comparison of the overlay against the group's CURRENT row, which is RM311.

RM307 — the AlphaGenome Atlas client has no pacing gate, and the interval one needs is unmeasured

Severity low · Status ✅ SHIPPED 2026-09-29 on main, uncut — a patch (internal behaviour; no schema, no parquet) · Owner enricher (atlas_client) · Motivating case RM280's pacing half, split off when RM280 shipped its retry half on 2026-09-28 · related RM280, RM192, @shared-pacing-gate, @retry-attempt-floor

Residuals won't fix — a daily quota, if one exists: finding it means spending it, and a hit would arrive as RESOURCE_EXHAUSTED, which is already AtlasUnavailable and retried.

What is missing. Most retried clients in the tier wait on a net.PacingGate once per attempt (cpic and ensembl are the other two that do not). AtlasClient does not. RM280 gave it the house retry floor, so JUST_DNA_HTTP_RETRY_ATTEMPTS can now raise its attempts, and those attempts are not paced. The gate is also what counts spent (S95), so an Atlas call is the one upstream attempt a host metering egress cannot see.

Why RM280 did not build it. A gate needs an interval, and nothing settles one. ALPHAGENOME_ATLAS.md records that no quota or rate-limit figure is published and none was measured. Nothing in this repository calls the client from more than one thread, but check_variant_impact(client=...) takes a host's client, so a host threading its work shares one client by following the injection API. That is the S15 argument for making a gate shareable in the first place.

What to decide. The interval: measured against the service, or a stated courtesy value with no upstream figure behind it. And whether AtlasClient takes an injected gate= like the httpx clients, so a host running several clients can hand them one. Internal behaviour either way, so a patch.

Decided by the maintainer on 2026-09-29: measure it, and if nothing needs pacing, record that. Measured with the stub called directly, so no retry could absorb a throttle (ALPHAGENOME_ATLAS.md § 6.7, program in A.8): 479 sequential calls in 90 s, then 1,493 calls from four threads in 70 s (21/s, about 1,270 a minute), all OK. Sixteen threads got less through (16.7/s) and 32 of 1,600 calls hit the 30 s deadline, so concurrency degrades before any quota answers. No RESOURCE_EXHAUSTED in about 3,570 calls.

What shipped. ATLAS_REQUEST_INTERVAL = 0.0, stated as a measurement. AtlasClient holds a net.PacingGate (its own, or one injected with gate=, also on connect) and waits on it once per attempt inside the retry, so gate.spent counts upstream attempts like every other client's (S95). A host sharing one gate across clients sets whatever interval it wants. The probe's "API quota and rate limits. Not measured" line is struck, and a stale pointer in the same probe (A.8 for the two-package recipe, which is A.6) is corrected.

RM279 — nothing checks a conclusion against the other cells on its own row, so a swapped pair compiles green

Severity low · Status ✅ SHIPPED 2026-09-28 on main, uncut — a patch (the genotype rule, as an authoring hint) · Owner compiler (conclusion.py, hints._check_conclusions) · Motivating case consumer-note D14 (the 0.7 idea-book), numbered by the 2026-09-27 postmortem (P7), because an idea-book bullet is not a home · related S68, RM308, RM309

Residuals RM308 (the same finding at validate/compile, which needs a warning code and so a minor) and RM309 (the second rule, a state the conclusion negates, never measured)

What the reporter measured, and what we reproduced. 20 hits in 1,418 rows at about 60% precision by hand. The finds that matter are real curation errors: coronary rs17514846 has its C/C and A/A conclusions swapped, and rs11591147 is scored protective +1.2 on T/T under text saying GG is protective. lint_rows over twelve real thrombophilia rows returned no finding on three more (rs1799963 A/A → "GA carriers have 6.74x risk"; rs2519093 C/T → "TT genotype is associated…"; rs1799889 G/G with state: risk under "…is not increased"). Both measurements are recorded in the idea-book and the consumer-note triage section of this file.

Two candidate rules, neither needing an external source. A conclusion naming a genotype built from alleles at this row's own locus that is not this row's genotype; and a state of risk/protective the conclusion's text negates. The locus restriction is what makes the first tractable (an earlier version flagged "(TG) levels").

Parked on, and the gate is satisfiable now. A measured precision for the locus-restricted rule over the reference examples plus the reporter's corpus. A warning an author reads on every compile at 60% precision is how the channel stops being read (S68). Anyone can run that measurement today, so the gate is not circular. Being a warning with no schema member, it is patch-class once built.

Refuted by the build, 2026-09-28. A warning at validate/compile is a schema member: it needs a key in VALID_WARNING_CODES, and a new key is minor-class. Only the hint was patch-class, and the compile half is RM308.

What shipped, measured. The gate was a precision for the locus-restricted rule, and it was run over 653,706 diploid rows: the six curated v1 ports the reporter measured (1,418 rows, from just-dna-lite/data/interim/v1_port_0_5), reference_examples/, and the registry's cardio, cancer and pathogenic modules. The reporter's reading ("names a genotype that is not this row's") fired 24 times, about 40% real, because a correct row that also names its neighbour ("AA is protective, AC carriers less so") matches. Reading it as names genotypes at this locus and never its own left 14, and four of those were three shapes of prose that are not a genotype: an allele description after an rsID ("rs1042718 (C/A)"), a haplotype across two sites, and (on the registry modules) the row's own gene symbol ("variant in TG"). Excluding those three left 10 findings, all 10 real by hand: rs17514846's swapped pair, five rows carrying a neighbour's sentence (rs1799963, rs1800790, rs17228212, rs2519093, rs6025), rs4977574, rs11591147, and rs17822931's strand-mixed G/G row under TT text. Zero on every reference example.

Where it runs, and why only there. hints.inspect_rows, so hint variants.csv and the creator's lint_rows report it as a warning on the conclusion column, naming the row that carries the genotype the text names, which is how a swap reads as two findings pointing at each other. It does not run at validate or compile. A finding there needs a member of VALID_WARNING_CODES, and adding one is minor-class because a reader pinned to an older just-dna-format refuses a manifest carrying it. The missing-sentinel finding already lives on the authoring surface only, so this is the second such hint, not a new kind. The rule is its own module (just_dna_compiler.conclusion) so RM308 calls it from the compile path without a cycle through hints. Every exclusion has a test that goes red without it, and the two positive tests go red with the check switched off.

RM280 — the AlphaGenome Atlas client has no retry layer of its own and no shared pacing gate, which RM192 said was filed

Severity low · Status ✅ SHIPPED 2026-09-28 on main, uncut — a patch (the retry half; the pacing half is RM307) · Owner enricher (atlas_client) · Motivating case RM192's "What it did not do" paragraph and PROPOSAL_0_7_PT4's Implementation debt list. The 2026-09-27 postmortem sweep (P8) found nothing had been filed · related RM192, RM194, RM196, RM307

Confirmed on 2026-09-27. RM192's client docstring said it carried no tenacity layer over the vendored grpc_service_config.json (@retry-attempt-floor) and no shared pacing gate (@shared-pacing-gate), and no ROADMAP file named either. The channel did take upstream's retry policy from the vendored service config, so the client was not unretried. What was missing was the house layer every other network client has: a floor an operator can raise, and one gate shared across concurrent callers.

What was measured. grpc 1.83.1 caps service-config retries at five attempts, and upstream's config already asks for five. So JUST_DNA_HTTP_RETRY_ATTEMPTS could not raise the Atlas client's attempts, and a tenacity layer stacked on the channel would have multiplied them (5 × N) rather than set a floor. A loopback server answering UNAVAILABLE saw five calls for one stub call under the vendored options, sixteen seconds of grpc backoff, and one under the new ones. _translate also classified INTERNAL as AtlasUnavailable, whose docstring says retryable, and nothing retried it: upstream's config names RESOURCE_EXHAUSTED, UNAVAILABLE and DEADLINE_EXCEEDED only.

What shipped: option (b), the maintainer's choice. grpc's retry is off, and the client retries in the house layer.

  • atlas_client.channel_options() is what connect opens the channel with: grpc.enable_retries = 0, and the vendored config with retryPolicy removed from every method config. The per-attempt timeout stays, since it is a deadline.
  • AtlasClient._call is the one retried method, and all three RPCs go through it. It uses attempt_floor(RETRY_DEFAULT_ATTEMPTS), which is upstream's maxAttempts (5) read from the vendored file. Its wait is wait_random_exponential with upstream's initialBackoff, maxBackoff and backoffMultiplier, which is the form grpc applies them in. It sets reraise=True, so each caller's except grpc.RpcError still translates after the last attempt. Retry inside, translate outside.
  • What it retries is _retryable, which asks _translate whether the status becomes AtlasUnavailable. The retry set is derived from the classification rather than restated beside it, so INTERNAL is retried now, and a code moved between arms moves the retry with it.

What pins it (enricher/tests/test_atlas_client.py). Every grpc.StatusCode except OK is walked, and the expected attempt count is computed from _translate at run time: the floor's value for a retryable status, one for any other. The knob is run at "", 0, 1, 2 and 8. It is a floor, so the low values leave five in place and 8 makes eight. The options test asserts enable_retries == 0, no retryPolicy, and the vendored timeout kept, and a second test probes connect itself for those options. The policy's stop and wait are compared with the vendored JSON read independently. The package-wide roster in test_gated_snapshots.py now lists atlas_client.AtlasClient._call, and its defaults are {3, 4, 5}. test_retry_is_reachable.py does not see this client: its walk resolves only retry_if_exception_type(httpx.…), and _call has no except for it to check. The import-floor test admits tenacity, a core dependency of the tier, so [atlas] is still grpcio + protobuf.

The pacing half was not built. A gate needs an interval. The Atlas publishes no rate budget, and ALPHAGENOME_ATLAS.md records that none was measured. Nothing here calls the client from two threads, but check_variant_impact(client=...) takes a host's client, so "no concurrent caller" is true of this repository and not of its consumers. RM307 carries it.

Residuals RM307

RM297 — the ClinPGx currency check compares a row against an annotation it never cited

Severity medium · Status ✅ SHIPPED 2026-09-28 on main, uncut — a patch (a warning; the check withholds rather than blocks) · Owner enricher (clinpgx.enrich_clinpgx) · Motivating case S122 in CONSUMER_SUGGESTIONS_HISTORY.md · related RM298 (the minor that settles it), @existence-not-identity, @the-signal-may-already-be-firing-with-the-wrong-words, @warning-code-names-the-finding, @rsid-absent-two-readings

Reproduced. just-dna-seq/pharmgkb@1.0.0 was drafted from clinpgx_2025-07-05. It carries three rs116855232 + azathioprine rows citing annotation 1184514050 at 1A. ClinPGx withdrew that annotation before clinpgx_2026-08-05. Run against the newer snapshot, enrich_clinpgx reports module says level 1A, ClinPGx says 3 for all three and unmatched 0. The 3 belongs to a different annotation, 1450934767 (Toxicity, azathioprine;mercaptopurine), which has been in both snapshots.

The mechanism. The lookup tries (annotation_id, genotype), then (rsid, drug, genotype, category), then the bare triple. When the row's annotation_id is absent from the snapshot, or the row has none, the fall-through compares it against whichever ClinPGx annotation shares its category. It then reports a level difference against a record the row never cited, and under strict refuses on it. The same fall-through can also agree silently when the other annotation happens to share the level.

Why the check cannot know better, and why that decides the severity. Nothing marks a row as ClinPGx-derived. sources.csv records ClinPGx per (source, layer), and so does record_draft_provenance. annotation_id is source-agnostic by its own field description ("the source's own accession"), and a curator may author a row from an article, CPIC or DPWG with its own accession or none. So an annotation_id the snapshot does not hold has three readings:

  • ClinPGx withdrew it (the S122 case).
  • It is mistyped.
  • It was never a ClinPGx accession.

A refusal under the third reading blocks a legitimate row with an error its author cannot clear. A row with no annotation_id has the same problem one step earlier.

The patch, decided with the maintainer 2026-09-27: warn, never block.

  • A row whose annotation_id is set and absent from the snapshot stops the lookup. It becomes its own finding, warned in both modes and never raised under strict. The finding names all three readings and says what the snapshot holds at the triple.
  • A row with no annotation_id whose level is compared only through the category or triple fall-through is still reported, but it no longer refuses under strict. The row has not claimed that record.
  • An id that is present but lacks that genotype keeps today's fall-through.
  • A conflict reached through the row's own annotation_id is unchanged. It keeps its text byte-for-byte (@warning-text-is-api) and still refuses under strict.
  • A new ClinPgxResult field is additive. The new warning code needs its features/ scenario.
  • verification.json's findings for pgx_evidence_level counts the new finding, so moving rows out of conflicts does not lower a published number for an unchanged module.
  • The patch loosens strict for fall-through rows. It must declare that in the CHANGELOG entry.

What the patch leaves open is RM298's. Knowing per row that a row cites ClinPGx is what would let a withdrawn annotation block again, and that needs an authored column.

What shipped. enrich_clinpgx collects every row a cited id cannot settle into a new ClinPgxResult.withheld list of WithheldLevels, each carrying one of two lane-local codes (VALID_CLINPGX_WITHHELD_CODES): clinpgx_annotation_not_in_snapshot for a cited id the snapshot does not hold, and clinpgx_level_differs_from_uncited_annotation for a row with no id whose category or triple match carries another level. The first stops the lookup at the cited id and quotes what the snapshot holds at the row's category, or else at its triple. Each lands in warnings in both modes, and the strict gate reads conflicts only. The pgx_evidence_level record counts conflicts + withheld as findings and names the codes in detail, which stays None when nothing is withheld, so a run with nothing withheld writes the record it always wrote. An own-id conflict, and a cited id present without the row's genotype, are unchanged. The codes are not VALID_WARNING_CODES members: that vocabulary is the compiler's, and the finding reaches a compile as verification_findings_recorded, the shape civic_refutation's two codes set. One widening beyond the entry's letter: a cited id absent from the snapshot with nothing at its triple used to be an unmatched miss and is now this finding, because the id is the claim and the entry makes an absent id its own finding.

Tests. enricher/tests/test_clinpgx.py: the S122 shape (a cited id derived to be absent from the slice, at a level its category neighbour does not carry) and a row citing no id both refused under strict on the previous tree and now pass with one withheld each. The record still counts the withheld row as a finding. An own-id conflict keeps its text byte for byte, and the two codes have pairwise distinct sentences. The features/ scenario sits beside @check:pgx_evidence_level.

Residuals RM298

RM289 — two author-facing sentences state something false: PgsRow.training_ancestry's description, and the licence gate's skip for unknown terms

Severity low · Status ✅ SHIPPED 2026-09-28 on main, uncut — a patch (text only) · Owner format (pgs.py) + enricher (licensing.py) · Motivating case RM163's own finding and the S99 reply, both left as sentences, found by the 2026-09-27 postmortem sweep (P15) · related RM163, S99, RM27, @field-description-is-a-claim, @warning-text-is-api

Residuals won't fix — S99's archived reply still calls RM27's axis undesigned, and answered replies belong to the triage seat

  1. PgsRow.training_ancestry said "validated in". RM163 recorded that "the name says training, the description says 'validated in'" and changed nothing. The description is published by describe, requirements and json_schemas(), so it is a claim every author reads.
  2. The skip sentence for unknown terms read as "not recorded yet". S99's reply said the gate's sentence ("terms could not be established, so the data is not used … the absence of a finding either way") reads as not recorded yet when for PubMind it is unsettleable, and called it a patch-level candidate for after 0.7.0.

What shipped. No drafter fills training_ancestry. The one machine that reads it is RM163's drift check, which compares it against the PGS Catalog's dev and eval stages (pgs.COMPARED_ANCESTRY_STAGES, the discovery GWAS excluded on purpose). So the description now says the score was developed and evaluated in those superpopulations, naming both Catalog stages and excluding the discovery GWAS. A dev-only wording would have matched the column's name and contradicted the check, which accepts an evaluation-only ancestry as agreeing. The module docstring and two code comments that quoted "validated in" say the same.

check_declared_use's unknown arm keeps its leading phrase and now says that no declared use changes the outcome, then quotes what is established: the terms' own notice and license_url. Every source held at commercial_use=None today (clingen_allele_registry, gwas_catalog, mane, pgs_catalog, pubmind) is a probed absence whose reading is already recorded in notice, so the sentence reads as unsettleable, and here is why rather than as a constant left unfilled. Two licensing.py comments calling RM27's redistribution axis undesigned now say it shipped record-only.

Why a patch. Both are text: no field, no vocabulary member, no digest moves.

Tests. enricher/tests/test_pgs.py::test_training_ancestry_description_names_the_stages_the_check_compares ties the description to COMPARED_ANCESTRY_STAGES through a stage-to-word map that must cover the tuple exactly. enricher/tests/test_pubmind_licensing.py::test_the_unknown_terms_skip_says_why_the_terms_are_unknown walks every unknown-terms source in TERMS_BY_SOURCE against every declared_use member. Both failed on the previous tree for the stated reason.

RM301 — constructing an enricher client exported the whole .env into the host's environment

Severity medium · Status ✅ SHIPPED 2026-09-27 on main, uncut — a patch (decided with the maintainer that day) · Owner enricher (locations, every credential reader) · Motivating case S124 in CONSUMER_SUGGESTIONS_HISTORY.md, from just-dna-registry on just-module-creator's behalf · related RM102 (reopened by this), RM100, RM176, RM212, @credential-where-read

Residuals none — the cache resolvers' export is RM102's closed decision, kept on purpose

EutilsSettings, CrossrefClient, PmcIdConverterClient and PharmVarClient called load_env() in their constructors, as did net.retry_attempts, the caches PharmVar guard, expression._connect, cli._atlas_client_or_none, upload's three HuggingFace sites and download's two provisioners. load_env is load_dotenv(override=False), so each exported every key in the working directory's .env, not only the credential it read. just-module-creator resolves its settings in layers and tells an author which layer a value came from. After one of these constructors ran, every file value read as an exported shell variable.

What shipped. locations.env_value(var) returns the process environment's value if the variable is present, else the nearest .env's, and writes nothing. The precedence is load_env's: an exported value wins and an exported empty string stays empty. Every credential reader above uses it, so RM100's guarantee (the credential arrives whatever the call order) holds without the export. missing_credential_reason gained a third reading for a key the .env sets empty. net memoizes the file's value once and re-reads the environment on every call.

Why a patch. The export was a side effect, not a promise. The only code it breaks is host code that reads a variable which exists only in a .env, after constructing one of our clients, and relies on us to have exported it. That is the call-order dependence RM100 called a bug. RM102's two rejected repairs stay rejected: no default flips, and nobody's file is filtered.

Tests. enricher/tests/test_env_value_exports_nothing.py constructs the four clients in a subprocess whose only source is a .env. It asserts that each credential arrived and that none of the file's keys is in os.environ, and it fails on the pre-fix tree with the credentials present and the whole file exported. An AST walk keeps load_env() inside locations. test_dotenv_credentials.py's two before-the-fix probes and RM212's structural check now target env_value. The first full run turned up the fix's own side effect: the HuggingFace sites now consult env_value("HF_TOKEN") before get_token(), so the upload tests, which stub get_token(), received the real token from this repository's .env instead of the stub's. HfApi was mocked, so nothing left the machine. An autouse fixture in the enricher conftest.py now sets HF_TOKEN to empty for every test.

RM299 — stats.pathogenic_count says "pathogenic" and counts both pathogenic tiers, per genotype row

Severity low · Status ✅ SHIPPED 2026-09-27 on main, uncut — a patch (field descriptions) · Owner format (manifest.Stats) · Motivating case S123 in CONSUMER_SUGGESTIONS_HISTORY.md · related S43, RM300

Residuals RM300

Stats.pathogenic_count sums the legacy pathogenic boolean over authored variants.csv rows. The boolean folds likely_pathogenic into pathogenic by design (P8 pins it; SCHEMAS.md has said so since S43), and a module carries one row per genotype. The field's description said only "Rows flagged ClinVar-pathogenic". A catalog read just-dna-seq/pathogenic@2.0.0's 617,822 as that many pathogenic variants: twice the module's 308,990 variants, with about a third of the rows likely_pathogenic. benign_count has the same fold and clinvar_count the same grain.

What shipped. The three descriptions say what they count: authored rows, one per genotype, never distinct variants. The two tier counts name both tiers their boolean folds and point at clin_sig for the split. The value is unchanged. Redefining it from clin_sig would change what an existing reader is told without any way to know (the S18 precedent), so a per-tier count is additive and is RM300. schema/tests/test_manifest.py pins each description against the derivation: every tier derive.*_from_clin_sig folds must be named in the description of the count that sums that flag.

RM295 — cyp2d6_structural places CYP2D6*4 at a coordinate whose ref GRCh38 does not have

Severity low · Status ✅ SHIPPED 2026-09-27 on main, cut 2026-09-27 as v0.7.3 — a patch (a reference-example correction) · Owner docs / reference_examples/cyp2d6_structural · Motivating case found by RM291's consumer-join test on 2026-09-27 · related RM291

Residuals none

variants.csv and studies.csv state 22:42127941 C>T for CYP2D6*4's splice variant. GRCh38 has G there, and Ensembl places rs3892097 at 22:42128945 (C/A/G/T), about a kilobase away. The example compiles green because the compiler holds no reference, and no enrich run over it was checked. RM291's test pins the row as its one reference disagreement; correcting the example empties that set. Check the README's prose and any test that reads the example's coordinates in the same change.

What shipped. Both rows moved to 22:42128945 (GRCh38 reads C there; Ensembl's sequence endpoint, 2026-09-27), the example re-closed with just-dna-compiler close, and schema/tests/test_polyploid_genotype.py, which called the old locus "real", now uses the corrected one. RM291's reference-disagreement set is now empty and asserted so, and the corrected row joins ClinVar's own rs3892097 record. The consumer-join fixture was rebuilt to cover the new position.

RM291 — no test does what a consumer does: join a compiled module against an independently normalized VCF

Severity high · Status ✅ SHIPPED 2026-09-27 on main, cut 2026-09-27 as v0.7.3 — a patch (a test only) · Owner compiler (compiler/tests/) · Motivating case the 2026-09-27 postmortem, blindspot B3 and mitigation M4, decided with the maintainer that day · related RM270, RM267, RM273, RM31

Residuals RM270 · RM295

The suite compiles, reverses, recompiles and cross-checks tables against each other, and every one of those checks is internal. None of them joins a compiled artifact against a VCF produced by someone else, which is a consumer's whole operation. That is why the +1 indel respelling (RM31, 2026-08-03) and CCR5-Δ32's dropped carriers (S120) passed every gate for three minors.

The test. Commit a small ClinVar VCF slice covering the reference examples' variants, normalized with bcftools norm -f <GRCh38> (left-aligned and trimmed, as a caller emits). Compile every reference example and join each on (chrom, pos, ref, alt) the way a consumer does. Assert that every row expected to match does, as set equality over the walked rows, never a count. It would have failed on 2026-08-03.

It fails today, on purpose. The respelled indels RM270 names miss. Land it with those rows as an explicit expected-failure set pinned to RM270. A row leaving that set, fixed or newly broken, fails the test, so the set can only shrink when RM270 ships. The fixture is small and travels in assets/, under the ~5 MB LFS threshold.

What shipped. compiler/tests/test_consumer_join.py and assets/consumer_join/ (a 75 KB ClinVar 2026-06-27 slice, ±100 bp around every placed allele row of the GRCh38 examples, split and normalized with bcftools norm -f against Ensembl's GRCh38 primary assembly; and those regions' reference bases, 4 KB). norm realigned 0 of 5,285 records, since ClinVar's VCF is already in caller form. "Expected to match" is haplotype equality over the windows, so it does not depend on the normalization under test; "does match" is the consumer's exact (chrom, pos, ref, alt) join. On the day, over distinct (example, table, chrom, pos, ref, alt) keys ClinVar carries: 613 join and 2 miss, the SHOX pair pinned to RM270. Symbolic alleles (<DEL:4977>, N ref) are outside by rule, and one row whose ref GRCh38 lacks was pinned to RM295, found by this test and corrected the same day (the row now joins, so 614). (An earlier draft of this paragraph said "823 of 825", a count over table rows with duplicates; the test asserts sets.) A row outside every window fails by name, so a new example forces a fixture rebuild. Emptying the RM270 pin was run and turns the test red.

RM274 — a same-size, different-content indel is kept as undecided, and RM31's reference half that would settle it was never filed

Severity medium · Status ✅ SHIPPED 2026-09-27 on main, cut 2026-09-27 as v0.7.3 — a patch · Owner enricher (the hosting filter in enrich.py, the run's sequence proxy) · Motivating case the RM31 residual (0.5), found unfiled by the 2026-09-27 postmortem sweep (P2) · related RM31, RM270, RM273, RM267

Residuals RM272 · won't fix — the compiler's own hosting filter keeps arm 9 undecided because Principle 2 gives that tier no reference

RM31 made the allele-aware filter tolerant of respelling: hosting_verdict strips the flank a collection shares, so {C, CAG} and {AGAG, AG} both reduce to {'', 'AG'}. Different event sizes prove different variants. A same-size pair with different content cannot be told apart without the reference, because inside a repeat it may be one event anchored twice or two events. So the verdict is None and the locus is kept, with a log warning. The RM31 entry says "the enricher can still settle it with seqrepo (not yet wired — see the residual below)". The only other record of that half is a code comment in enrich.py: "doing that automatically is the remaining half of RM31".

What a consumer gets. A kept undecided locus goes into resolution.csv like a confirmed one, and nothing on the row says which it was. When the pair really is two events, the module's genotype is joined to a different variant's coordinate. That is the S117 outcome, reached by a different route.

Why it is not already RM270's or RM267's. Both compare two placements that each carry a position, so a vrs_id settles them. Here one side is the authored genotype of an rsID-only row, and it has no position of its own. The first design question is whether the resolved locus's window is enough to place the genotype's alleles in both frames. If it is not, the verdict stays None and the fix is to count and publish the undecided set (@tautology-zero) rather than keep it silently.

Why a patch. Settling a None into True/False is a corrected derivation of the fill, outside content_signature (@rm43-positional-fill). A structured field naming the undecided set on EnrichmentResult would be a minor, the same line RM272 draws.

What shipped — the design question answered yes. The resolved locus's window is enough: an rsID-only row's genotype has no position, but it claims to be this locus's allele, so the question is whether any spelling of the locus's indel carries the genotype's payload. sequences._indel_payloads left-aligns the locus event and slides it right across its repeat on the reference, collecting every payload (2:166204477 ACAAA>A gives {AAAC, AACA, ACAA, CAAA}); enrich._settle_by_reference runs only on hosting_verdict's arm 9 and answers True when the genotype's payload is among them, False when a same-size alt exists and none is, and None otherwise (offline, an unreadable read, a repeat longer than the window, a genotype that is not one plain insertion/deletion against the empty allele). A settled True keeps the locus as before without the undecided warning; a settled False drops it, named in one aggregated warning, so a module's genotype is no longer joined to a different variant's coordinate. Existing True/False verdicts cannot move: the settle runs on None only. The run's one SequenceProxy is now built above the table and reused by minting and the reference check. No field, no code; the structured undecided set is RM272.

RM276 — draft-repeats drops STRchive's evidence, so a locus STRchive grades Refuted drafts exactly like a Definitive one

Severity medium · Status ✅ SHIPPED 2026-09-27 on main, cut 2026-09-27 as v0.7.3 — a patch (the drafter warning); the column is RM294 · Owner enricher (strchive.StrchiveLocus, strchive_draft) · Motivating case RM170's STRchive half (0.7) and RM165's note, found unhomed by the 2026-09-27 postmortem sweep (P4) · related RM170, RM165, RM66

Residuals RM294

RM165 recorded that STRchive grades every locus with a ClinGen-style validity classification, "a second instance of RM170's problem in a different domain". RM170 then measured that a real draft-repeats --gene DMD run writes a row indistinguishable from HTT's, and it named the STRchive half "a source-adoption question wearing a check's clothes". RM170 shipped the CIViC check, and nothing took the STRchive half.

Confirmed on 2026-09-27. StrchiveLocus still has no evidence field (its docstring lists it as deliberately dropped). In the local snapshot the grades are Definitive 46, Limited 14, Moderate 8, Provisional 6, Strong 4, Disputed 3 (DIP2B, NIPA1, POLG) and Refuted 1 (DMD). An author drafting any of those four gets a pathogenic band with no word that the source itself doubts the association.

What to build, sized by what it adds.

  • Patch: carry evidence on StrchiveLocus and have the drafter warn, naming the grade, for Refuted and Disputed. That is a report with no schema member, and it matches RM170's own severity rule (warn in both modes, never gate: a source doubting itself is not an authoring error). Provisional is STRchive's not yet curated, a nobody-asked rather than a grade, so it is counted and named apart, never read as weak evidence.
  • Minor, decide separately: whether the grade should travel into the module, and if so where. An authored repeat_alleles.csv column costs full price (P9), and the vocabulary is open upstream (combobox: true).

What shipped. The grade is read by a private strchive._evidence_by_locus off the catalogue file the StrchiveCatalogue already records, not as a StrchiveLocus field: a new field on that public dataclass is minor-class, and main is patch-only. draft-repeats names each drafted locus STRchive grades Refuted or Disputed (DMD (Refuted)), names Provisional loci apart as not yet curated, and when no file is readable says the grades were unread instead of staying silent. Notes only, both modes, never a gate. Tests use two real catalogue records (DMD_DMD, SCA_EP400) beside the slice.

RM273 — three more enricher surfaces take an indel's spelling for its identity: the MITOMAP increment, the ClinGen anchor, PubMind

Severity high · Status ✅ SHIPPED 2026-09-27 on main, cut 2026-09-27 as v0.7.3 — a patch · Owner enricher (mitomap_miss_build, clingen_allele.anchor_indel and its CIViC/LitVar callers, pubmind_draft) · Motivating case the 2026-09-27 postmortem sweep (P1), residuals of RM171, RM153 and RM134 · related RM270 (the root: an indel's key is its source's spelling), RM267, RM31

Residuals RM293 · won't fix — LitVar compares a CAID only at the module's own start and withholds elsewhere, so it writes no shifted row · won't fix — mitomap_miss is a derived lane that is never published, so each machine's copy changes only when that machine rebuilds it

RM270 names the artifact key. These are the same mistake one tier earlier, inside the enricher, where it reaches an author as a drafted row or a published count. Each was reproduced on 2026-09-27.

1. RM171's MITOMAP increment calls a ClinVar allele "new". _clinvar_calls joins on the exact (start, ref, alt). Applying both spellings to a GRCh38 chrM window over the local mitomap_miss snapshot: 8 of its 23 miss indels are an allele ClinVar already holds at another anchor, among them 5 of the 6 rated misses the RM171 entry reports as the lane's increment. For example 7471 C>CC and 7472 A>CA are both ClinVar's 7465 A>AC (pathogenic), and 8618 T>TT is ClinVar's 8617 A>AT. The photocopy test has to compare events (a reference window, or the minted vrs_id RM270 describes), and the entry's rated-miss number has to be re-measured.

2. RM153's anchor_indel docstring calls prefix-anchoring "the left-aligned representation VCF requires". That is true only outside a repeat. The registry's interbase start follows HGVS's 3′ rule: rs72613567 (CA2999458) comes back as an insertion of A after 4:87310241, so the anchored row is 87310241 A>AA, where the left-aligned spelling is 87310240 T>TA. rs77944059 (CA180415) is a CAAA deletion anchored at 2:166204477, four bases right of left-aligned 166204473. CIViC and LitVar draft through this function, so their drafted indels carry the right-shifted spelling into authored rows, which RM270 then keys on.

3. RM134's open question is answered, and the drafter still says it is open. PUBMIND_ASSESSMENT § Open questions asks whether PubMind's indels are left-normalized. They are not. Of the 20,006 single-base-anchored indels in the local snapshot, 5,158 have an anchor base equal to the payload's last base, so each could shift left and is not left-aligned. That is decidable from the row alone. pubmind_draft still warns that the rows are "not established to be left-normalized".

4. RM31's genotype-frame half (genotype C/CAG beside ref=AGAG) is a consumer-document gap, not code. It is handled as postmortem D9, not here.

Why a patch. Every repair is a corrected derivation under P3's clause: a bucket reassigned, a drafted coordinate left-aligned, a warning that states a measured fact. None adds a schema member. If the MITOMAP fix wants a new bucket name for "respelled photocopy", that is a new member in a published release.json vocabulary, and it has to be priced before it is built.

What shipped, one commit per part (all cite P1).

  • Part 3, PubMind (75fd810). pubmind_draft._shifts_left reads the fact from the row alone: an anchor base equal to the payload's last base spells an event that also sits one base left. The withheld-indel warning states that count instead of "not established"; re-measured on the 2026-08-24 snapshot, 5,158 of 20,006 single-base-anchored indel rows (4,334 of 16,737 keys). PUBMIND_ASSESSMENT marks its open question answered. The rows stay withheld.
  • Part 2, the ClinGen anchor (f8440b5). anchor_indel's docstring no longer calls its output left-aligned. civic_draft left-aligns the anchored row against one bounded reference window (private sequences._left_align); running off the window withholds under the existing anchor_base_unreadable. LitVar is unaffected, as a residual above says. Correction to this entry's own example: rs77944059's leftmost spelling is 166204470 GAAAC>G, not 166204473 (both are the same event; 470 is the leftmost), checked on Ensembl's GRCh38 bases.
  • Part 1, the MITOMAP increment (this commit). rCRS (NC_012920.1, GRCh38's chrM) is vendored as _rcrs.RCRS, agreeing with all 3,104 ClinVar chrMT ref alleles, so the build stays a function of its two parents. Both sides' indels are left-aligned before the join; a respelled ClinVar call is a photocopy (no new bucket). Rebuilt from the local parents: photocopy 655 → 663, rated_miss 6 → 1, unrated_miss 388 → 385, unmintable 47. The drafter's indel note now says which build compared events.

RM277 — quote_counter_stale tells the author to re-run the literature pass, which skips exactly the rows it is about

Severity low · Status ✅ SHIPPED 2026-09-27 on main, cut 2026-09-27 as v0.7.3 — a patch · Owner compiler (the warning text) + enricher (the merge) · Motivating case S56, whose second candidate the reply said "we would still like", found unfiled by the 2026-09-27 postmortem sweep (P5) · related RM119, S56

Residuals won't fix — an offline run keeps a stale pin because re-deriving it needs the network, and the warning says so

RM119 shipped S56's first candidate, the compile-time comparison. The reply declined the second, recomputing quotes_authored on merge, as enricher work for "the next literature-pass change", and nothing filed it. Several literature-pass changes have landed since.

Confirmed on 2026-09-27, in the code. The warning ends "the sidecar predates the quotes (it is merge-not-clobber, so a re-run keeps the old row); re-run the literature pass to bring the counters and quotes_found up to date" (compiler.py, _check_quote_counter_is_current). Its own clause says the remedy fails. The pass fetches only PMIDs with no row (wanted = [pmid … if pmid not in have]), and pinned rows are never rewritten. The enricher's CLI already gives the working remedy for the same state: "literature.csv already pins their citation and a merge never refetches one — delete it to re-derive". So the two tiers give an author contradicting instructions for one condition.

Build, in order.

  1. The remedy text (compiler): say to delete literature.csv, or --rederive once the pass has it, as the enricher CLI does. The code and its scenario (features/compiler/sidecars_and_orphans.feature, "the remedy is to re-run the literature pass") change together (@warning-text-is-api: the code stays, the remedy sentence moves).
  2. Recompute on merge (enricher): quotes_authored is derivable from studies.csv (RM119's own argument), so the pass should rewrite it on every run, pinned row or not. That is a corrected derivation of a derived cell, with no schema member. After it lands, step 1's text can say a re-run fixes it, and be true.

What shipped — step 2 changed on the way, and why. Recomputing quotes_authored in place was refused: _tally_quotes reads a count mismatch as this pin's quotes_found is about other quotes, so rewriting the count alone attaches the old verdict to the new quotes, and clearing the verdict too would give a null quote_source a second meaning. Instead the literature pass re-fetches a pinned citation whose count no longer matches studies.csv (the same _citations / extract_pmids basis the compile check uses), so the counter, quotes_found and quote_source are re-derived together. Offline returns before that and keeps the pin.

  • The compiler's quote_counter_stale now says "re-run the literature pass online, which re-fetches a pinned citation whose quote count changed and re-checks its quotes (an offline run keeps the pin)", and its scenario moved with it. The code is unchanged.
  • The three "a merge never refetches one — delete it to re-derive" sentences (CLI, coverage line, attestation detail) now name the online re-run, and quotes_unexamined is a guard an online run no longer reaches.
  • What moves: a re-run over a module whose sidecar predates its quotes now rewrites those rows (fetched_at, the counter, the quote verdict). The four published modules with 3,668 quotes pinned at zero are that case.

Tests: test_a_quote_authored_after_the_pin_is_re_fetched_and_checked, test_offline_keeps_a_stale_pin_rather_than_re_deriving_it, test_a_quote_removed_since_the_pin_is_re_checked_not_misattributed.

RM271 — both Ensembl rungs serve a non-nucleotide allele as a resolved locus: dbSNP_novariation, <.>, an empty alts, an N run

Severity medium · Status ✅ SHIPPED 2026-09-27 on main, cut 2026-09-27 as v0.7.3 — a patch (enricher only) · Owner enricher (ensembl._loci_from_rest, the snapshot reads in resolver) · Motivating case found 2026-09-27 closing RM268, checking whether the live rung copies other non-base allele strings through the way it copied -

Residuals RM272 · won't fix — the patch-contig loci an rsID keeps (rs2100212723 now resolves only on HSCHR1_1_CTG3) predate RM271 and are not an allele question · won't fix — scoped to the two Ensembl rungs; the ClinVar and gnomAD links were not probed

What was confirmed, on 2026-09-27.

  • Live REST. Ensembl answers some rsIDs with a mapping whose allele_string is the literal dbSNP_novariation (rs2100212723 on chr1; rs1553119428 on chr1 and two patch contigs). _loci_from_rest takes the first /-token as ref, so resolve_rsid("rs2100212723") returns {'chrom': '1', 'start': 2651767, 'ref': 'dbSNP_novariation', 'alts': None}, and an enrich run with an empty snapshot dir wrote it to resolution.csv as status=resolved. The allele-aware filter did not reject it (genotype C/T). Also seen: rs2101156061 answers G/TTTTTTTTTTTNNNNNNNNNNN, an N run in an alt, which the resolver returned as-is (the enrich run hit a REST 500 on it, so the written row is unconfirmed for that one).
  • Snapshot. The same class sits in the Ensembl VCF-dump snapshot, and enrich --offline against it wrote all three as status=resolved, source=cache: rs2100212723 with alts='', rs1553186440 with alts='<.>', rs2101156061 with alts='TTTTTTTTTTTTNNNNNNNNNNN'. Measured over the snapshot's rs-prefixed rows: 10,065 with an empty alt and 121 with <.>, plus some with N in alt.
  • Not checked: what the compiler does with each shape downstream (<.> is a lengthless symbolic allele, which the compiler drops per @symbolic-alleles; an empty alts and dbSNP_novariation in ref were not followed through).

What it is. dbSNP_novariation and an empty alt both say dbSNP records no variation at this mapping. Writing either as a resolved locus states a position for an rsID whose source says there is nothing to place there. An N run is an allele of unknown sequence. Neither ResolutionRow.ref nor alts has a grammar to refuse them, and tightening one would invalidate existing derived files (P8), the same refusal RM268 records.

Repair (a sketch, unbuilt). Withhold at both reads: a mapping whose ref or any alt is outside ^[ACGT]+$ (after RM268's anchoring of -) is not a locus, counted and warned apart from not-found (a structured field is RM272's, minor). Decide per shape before building: dbSNP_novariation / empty alt look like an answered absence at that mapping, not an unknown, and a <.> may deserve the symbolic allele path instead. Patch scope under P3's corrected-derivation clause, declared in the CHANGELOG, as long as it adds no schema member. · related RM268, RM267, @non-nucleotide-spelling, @symbolic-alleles

What shipped. One predicate, ensembl._placeable_alleles, at every read of both rungs: REST and GraphQL parsing, and the four snapshot reads in resolver (rsID → loci, the position back-fill, the pair check's position set, and the legacy resolve_variants position read). A ref outside ^[ACGT]+$ withholds the locus; an alt outside it is dropped; a locus with no alt left is withheld. REST also serves the literal dbSNP_variant (seen on three of three empty-alt rsIDs sampled); the predicate withholds it the same way. Four <.> and empty-alt rsIDs sampled against REST all read dbSNP_novariation or dbSNP_variant there, so both spell no variation recorded at this mapping.

  • REST returns ([], "ensembl-rest"), the existing answered-empty, when no mapping is left: this is permanent, unlike RM268's unreadable anchor, so it is written as not_found, with a warning naming the rsID. GraphQL answers [] and REST is asked.
  • Snapshot: an rsID whose every locus is withheld is named by one aggregated warning, and no longer gets rsid_unresolved ("not in the injected snapshot"), which would be false.
  • What moves: alts narrows where a placeholder or an N allele sat beside real ones (rs33946775 HBB CA,CC,CG,<R> → CA,CC,CG; rs3838485 GGG,GGGN → GGG); loci with no nucleotide allele leave resolution.csv; an N-masked chrY locus goes, leaving its X twin.
  • No new public surface: the predicate is private, the warnings are log lines, and a structured result field is RM272 (minor).

Tests: enricher/tests/test_ensembl_non_nucleotide.py.

RM268 — the live Ensembl REST rung writes an unanchored insertion into resolution.csv: ref='-' at the interbase start

Severity medium · Status ✅ SHIPPED 2026-09-27 on main, cut 2026-09-27 as v0.7.3 — a patch (enricher only) · Owner enricher (ensembl._loci_from_rest) · Motivating case found while reproducing S117

Residuals RM272 · won't fix — the GraphQL beta endpoint now 301s and answers no bare rsID, so one-sided nodes go to REST · won't fix — stale ref='-' rows in existing sidecars are documented in ENRICHER and CHANGELOG, and --rederive clears them

What was confirmed. EnsemblResolver().resolve_rsid("rs8176719") answers via ensembl-rest with {'chrom': '9', 'start': 133257522, 'ref': '-', 'alts': 'C'}, and rs546596010 likewise (2:26455250 - > A). _loci_from_rest splits allele_string and copies REST's start through, and for an insertion REST's start is the base after the interbase point and - is its spelling of "nothing". ResolutionRow has no grammar on ref, so the row validates and is written. The result is a position one base right of any VCF record, and a ref that ALLELE_PATTERN (^[ACGT]+$) would refuse anywhere authored. The rung only runs for rsIDs the snapshot misses, which bounds the reach and is also why nothing has hit it. Scoped to REST; the GraphQL rung (_loci_from_graphql) was not probed.

Repair. Anchor a one-sided REST allele before it becomes a locus: read the base before the interbase point and prefix both sides (clingen_allele.anchor_indel is the existing pure function, taking an injected read_base), and withhold the locus as unresolved when the base cannot be read, the way caid_unresolved does. Two things to probe before writing the rule: REST's deletion shapes (rs121908745 answers an already-anchored ATCATC/ATC, so not every indel is one-sided) and which coordinate is the anchor, since anchor_indel assumes ClinGen's convention (interbase start is the preceding base) and Ensembl's insertion puts that base at end. This corrects a derivation and adds nothing to any schema, so it is a patch under P3's corrected-derivation clause, declared in the CHANGELOG. Tightening ResolutionRow.ref to the allele grammar instead is refused: it would make an existing derived file invalid, which P8 does not allow within a major.

What shipped. Probed first, on 2026-09-27: REST spells an insertion -/C with start = end + 1 (rs8176719, rs546596010, and rs3917's six insertions at one point), and a one-sided deletion AGTAAG/- over [start, end] (rs3834129). In both the base before the event is start - 1, which is anchor_indel's own convention, so one rule covers both shapes; the sequence endpoint confirmed it (2:201232808..201232814 reads TAGTAAG). Two-sided strings (ATCATC/ATC, TCTT/T/TCTTCTT) need no anchor and read no base.

  • _loci_from_rest anchors any mapping whose allele string holds a -, prefixing every allele with the base at start - 1 through anchor_indel, and returns how many mappings it withheld. rs8176719 now resolves to 9:133257521 T>TC, the ClinVar/dbSNP spelling. Checked live.
  • The base reader is the private EnsemblResolver._read_base (set like _client in a test); unset, it reads through a lazy SequenceProxy. A contig outside the refget table (a patch contig) reads as unreadable.
  • A fourth outcome for resolve_rsid: (None, "ensembl-rest"), Ensembl answered and every locus was withheld. enrich writes no row for it, the same as an unreachable rsID, but names it in its own warning, because the request did not fail. lookup gives it its own finding. An rsID where some mappings anchor keeps the anchored ones.
  • _loci_from_graphql withholds a one-sided node as [], which already hands the rsID to REST. The beta endpoint now 301s and answers no bare rsID, so its convention stays unprobed; it is withheld rather than anchored on a guess.

Not repaired here. A resolution.csv already written with a ref='-' row keeps it, since a sidecar is merged, never clobbered: delete the file or re-run with --rederive. Tests: enricher/tests/test_ensembl_indel_anchor.py and test_an_unanchorable_ensembl_answer_writes_no_row_and_is_named_apart.

Scope correction, same day. The first commit (61c6984) added EnrichmentResult.unanchored_rsids, an EnsemblResolver.read_base constructor field and a public sequences.grch38_base_reader: a new field, parameter and public function, each minor-class under the triage runbook's release table, and RELEASE_CYCLE keeps main patch-only. Fixed forward: the reader is private, the field is gone, and the warning carries the naming. The structured list is RM272, for 0.8.

RM264 — the 0.7.x manifest read an abstract-only miss as a checked quote, and the patch line re-describes it

Severity medium · Status ✅ SHIPPED 2026-09-25 on main, cut 2026-09-27 as v0.7.3 — a patch (format + compiler docstring) · Owner format (the two Literature descriptions) · Motivating case S109, the report behind RM256

The mitigation half of RM256. RM256's fix is a new manifest field, quotes_checked, which only a minor may add (Principle 3), and it lives on the 0.8 branch. Until 0.8 ships, a 0.7.x manifest publishes quotes_found: 0, quotes_unchecked: 0 for an abstract-only miss, the "checked and missed" reading S56 was about, one case over. Principle 3's staleness clause does not let a known-misleading output wait for a version unmitigated, so this patch carries what adds, removes and retypes nothing:

  • Literature.quotes_found no longer claims to count fulltext hits only (it sums abstract hits too), and both it and quotes_unchecked send the reader to abstract_only_count, the one counter on this line that separates an abstract miss from a checked one. quotes_unchecked says it counts citations, not quotes. Neither names quotes_checked, which does not exist here.
  • _literature_block's docstring states the gap; a FAQ entry gives the reading, per manifest and per literature.csv row (quote_source).
  • test_an_abstract_only_miss_is_told_apart_by_abstract_only_count_alone compiles the two modules (abstract miss vs fulltext miss), asserts they agree on the pair a reader looks at and differ only on abstract_only_count, and pins that both descriptions name it.

Refused, as in RM256: redefining quotes_unchecked to count abstract rows (S18: add beside, never redefine). Merge note for 0.8: its descriptions already name quotes_checked; at the first merge of main into 0.8, take 0.8's text for these two fields and keep this test only if its description assertion still holds there.

Merged into 0.8 on 2026-09-29. 0.8's text was taken for both fields, and quotes_checked's description gained one clause naming abstract_only_count as the only sign on a manifest compiled before that field existed. The test stays, with its description assertion moved to quotes_checked (neither 0.8 description of the two counters names abstract_only_count); its behavioural assertion, that the two modules differ on abstract_only_count, is the only test pinning that counter's value. The docstring paragraph was not ported, since on 0.8 it would be false: abstract_only_count is no longer the only counter that separates the two.

RM262 — a DOI answered existence and never identity, although the body naming the paper was already in hand

Severity medium · Status ✅ SHIPPED 2026-09-25 on the 0.8 branch, uncut (enricher) · Owner enricher (literature, lookup) · Motivating case S113 — lookup_citation(doi="10.1038/ng826"), Enattah 2002, came back doi_exists: true with title, journal, year and author all null and no finding

What was observed

Reproduced live. CrossrefClient.exists made the /works/{doi} request, read the status and threw the body away; lookup_citation filled the four identity fields only on the PMID branch, from esummary. So a DOI-only citation got the one answer @existence-not-identity says settles nothing, and findings was empty, so nothing said the title had not been asked for. The reporter's round had four of four authoring runs fall back to a free-text search to learn what their DOI was.

Found on the way: the same method answered True for a 200 that was not Crossref. exists read only the status, so an HTML maintenance page or a CDN interstitial read as "this DOI exists". Reproduced against the pre-fix code in a scratch worktree. It is the fourth leg of @client-exception-contract, on a client the contract suite exempted for a reason about its retry story rather than about what the class promises.

What shipped

  • literature.CrossrefWork (frozen: exists tri-state plus title/journal/year/first_author) and CrossrefClient.work(doi), off the same single request. exists(doi) keeps its signature and is work(doi).exists, so the literature pass and every other caller are unchanged.
  • literature.crossref_bibliographic(message), the Crossref twin of bibliographic: list-valued title/container-title (an empty list is None), the year from issued.date-parts, and the first author as the entry marked sequence: "first", rendered Family GI to read like PubMed's sortfirstauthor, or an organisation's name.
  • A 200 whose body is not a Crossref record withholds (exists=None). CrossrefClient joins WITHHOLDING_CLIENTS, which pins the withheld value on the 5xx, transport and HTML legs.
  • lookup_citation's DOI branch fills the four fields where the PMID branch left them None, and adds an info finding, DOI <doi> names: '<title>' (<author>, <journal>, <year>) — existence is not identity, …, the mirror of the PMID one. A record with no title (datasets, some preprints) says … names no title … rather than returning silent nulls.
  • With both identifiers, PubMed fills and both titles are reported. StudyRow is keyed on the PMID, so its record wins the fields; the DOI's title still arrives in its own finding, so a pair naming two papers shows two titles side by side (@roster-is-as-wide-as-the-tables-it-reads: two answers to one question go side by side).

Refused, with reasons

  • Retyping exists to return the record. Callers outside this repo may hold the bool | None contract, and a retype is major (P3). work sits beside it.
  • Rewriting title markup. Crossref passes JATS tags (<i>) through. The field is for a person to compare against the paper they meant; cleaning it would be a second opinion about the title.
  • The reporter's second candidate, DOI → PMID, in the same change. It is a separate request, a separate client method, and an advisory rather than a fill. Filed as RM263.

RM259 — a position has no gene to ask the Atlas about, so the reverse span lookup ships

Severity low · Status ✅ SHIPPED 2026-09-24 on the 0.8 branch, uncut (enricher) · Owner enricher (gene_spans) · Motivating case S112 — 252 of the longevitymap port's 1,033 rows author no gene

What was observed

enrich_expression needs a gene, because the Atlas's gene filter is mandatory, and the reporter's rows mode keys each window on the row's authored gene. The reporter's census of the derived tables checks out against the models: the variant-keyed sidecars carry no gene, the gene-keyed ones carry no position, and only expression_effects.csv, the output, has both. gene_spans answered symbol → span only. enrich_expression(spec, gene, chrom=, start=, end=) already takes an explicit interval, so the one missing piece was the reverse lookup.

What shipped

gene_spans.genes_covering(chrom, position) → NearbyGenes: every MANE gene on that contig whose span, widened by ATTRIBUTION_HORIZON_BP, covers the position, ordered by (start, gene), or one of two reasons (no_snapshot, no_gene_within_horizon) in NEARBY_REASONS, a map of its own so the two lookups cannot print each other's sentences. GRCh38 only, because MANE is. Measured on the real lane: 50 candidates at 6:26090951 (HFE H63D, the histone cluster) and 34 at APOE's rs429358. That is the answer as it stands: the horizon is the model's own half-window, so each one is a gene the Atlas could attribute the variant to.

Refused, with reasons

  • Narrowing to the nearest gene, or a top-N. That picks a gene on the Atlas's behalf, which is the span-as-attribution failure @gene-map-is-another-sources-attribution forbids, one step removed.
  • A rows mode in enrich_expression upstream. The reporter's planner already exists. A second consumer needing one would bring it here.
  • A per-candidate query per position as the recommended plan. At fifty candidates that is fifty Atlas requests per row. Inverting gene → positions and querying each gene once over the window its positions need is the cheaper plan, and the reply says so. It is the caller's plan, not this function's.

RM257 — PMC's BioC service is the fulltext rung for records Europe PMC calls closed

Severity medium · Status ✅ SHIPPED 2026-09-24 on the 0.8 branch, uncut (enricher) · Owner enricher (literature) · Motivating case S110 — Kunkle 2019, 24 quotes checked against an abstract while the manuscript was open to text mining

What was observed

Reproduced live on 2026-09-24. Europe PMC's search reports PMC6463297 as isOpenAccess: N, inPMC: Y, with manuscript id NIHMS1021255. The pass's is_open and pmcid gate therefore never asked it for fulltext, and fullTextXML answers HTTP 500 when asked anyway. PMC's BioC service answers 200 with 294 passages: 186 of them the reference list, and 27 of them TABLE, including the per-locus tables that hold the module's rows. An article outside the service's set (PMC1050584) answers 200 with a plain-text [Error] : No result can be found. body. That gate had no recorded licence reason, and it arrived in the 0.5.0 commit with the pass itself, so relaxing it for a second host is a coverage change and not a reversal of a refusal.

What shipped

PmcBiocClient beside PmcIdConverterClient, taking the E-utilities gate from the pass (@shared-pacing-gate), and extract_bioc_text, which keeps every passage except REF. The fetch order is Europe PMC fulltext (open records), then BioC (any PMCID Europe PMC did not serve), then the abstract. enrich_literature(bioc=) injects it the way the other three clients are injected. Tests run on recorded answers trimmed to a few passages: the suite's own ClinVar paper re-flagged as a manuscript, the Kunkle manuscript's table passage (a run of tab-separated cells matches as a quote, and a reference entry does not), and the service's "no copy" body. Each rung test fails with the rung disabled, which was checked. Two existing tests had been reaching the live service through a default client, and one of them would have silently changed meaning; both now inject one.

Refused, with reasons

  • A pmc_bioc value in quote_source, or a text_provider column. quote_source records how far the search reached, which is what makes a miss conclusive or not, and a BioC body is a fulltext. A provenance column is legal and half-cost, but nothing reads it; it can be added the day something does.
  • Reading the BioC license infon as the article's licence. "Available for text mining … fair use" names no terms (@no-named-licence), so the row keeps Europe PMC's is_open_access and license.
  • Gating the rung on inPMC or hasPDF. Neither makes it cheaper: an article outside the set costs the same one paced request and answers "no copy".
  • Splitting 404 from 5xx inside this item. Both clients still return one None, and the row it leaves is pinned. That is its own design question, filed as RM258.

What a module already enriched gets from this: nothing, until literature.csv is deleted. A pinned row is never fetched again. The delete costs nothing since 0.7 (RM124), and RM258 is where re-asking belongs.

RM256 — the manifest's citation block read an abstract-only miss as a checked quote

Severity medium · Status ✅ SHIPPED 2026-09-24 on the 0.8 branch, uncut (format + compiler + enricher) — sizes as a minor, a new manifest field · Owner compiler (_literature_block) · 0.7.x mitigation RM264 (split 2026-09-25: the field waits for 0.8, a patch re-describes the counters for the released line) · Motivating case S109 — reading back a rehearsal module with 24 quotes on one paywalled PMID

What was observed

An abstract-only citation stores quotes_found=0, quote_source=abstract: searched, missed, and not a verdict. The enricher's _tally_quotes already counted such a miss as unchecked, so the pass reported quotes_unchecked: 24. The compiler's _literature_block counted quotes_unchecked as citations whose quotes_found is null, so the same row published quotes_found: 0, quotes_unchecked: 0, which is S56's "checked and missed" reading one case over. Reproduced on a single LiteratureRow through _literature_block, and on a second shape the report did not name: 3 of 24 found in the abstract still published the other 21 as checked. quotes_unchecked also counts citations while the two counters beside it count quotes, so no value of it could have answered in the right unit.

What shipped

Literature.quotes_checked, the quotes a retrieved text settled, in quote units, so quotes_found has a denominator it can be read against. The per-row rule is LiteratureRow.quotes_checked() in the format tier: null settles nothing, fulltext settles every quote, anything else settles only its hits. The enricher's _tally_quotes and the compiler's block both call it, so the pass report and the manifest cannot disagree again; an enricher test feeds the rows a real pass wrote into the compiler's block and asserts the two agree. quotes_found's description no longer says "in a fulltext", which was false for abstract hits the block already summed. quotes_unchecked is unchanged and its description now says it counts citations and does not see an abstract-only row.

Why each candidate repair was refused

  • The enricher writing quotes_found as null on an abstract miss (the reporter's first choice). It merges two states LiteratureRow holds apart on purpose: null means nothing could be read, and 0 against abstract means the abstract was read. It also fixes nothing already written, since literature.csv is merge-not-clobber, and it leaves the partial-hit case wrong.
  • Counting abstract-only citations in quotes_unchecked, or moving it to quote units. The field's published description ("citations whose quotes_found is null") is accurate: the value was never wrong, the question was too narrow. Changing its basis or unit redefines a number a consumer already reads, which is the S18 case (add beside, never redefine), and a citation-level count cannot express a paper where some quotes were found in the abstract and others were not.

Scope, stated so it is not re-filed as an oversight. quotes_checked reads the row as written, exactly as quotes_found does. A row whose quotes_authored no longer matches studies.csv is the enricher's unexamined count and the compiler's quote_counter_stale warning, not this counter.

Release class. A new optional manifest field is a minor by the triage runbook's table, so the batch this lands in cuts as a minor. Literature sets no extra="forbid", so an older reader ignores the field. The next release record must declare literature.quotes_checked as an addition on the manifest_fields axis, or the cut's sweep gate will refuse it.

RM255 — lookup_variant(frequencies=True) asked gnomAD nothing for a multi-allelic locus, and said nothing about it

Severity medium · Status ✅ SHIPPED 2026-09-24, released in 0.7.2 (enricher) · Owner enricher (lookup) · Motivating case S108 — fixing a strand-ambiguous GWAS pair against gnomAD MAF, 15 of 25 lead rsIDs answered nothing

What was observed

_lookup_frequencies opened with single = [locus … if "," not in str(locus["alts"])] and returned on an empty list — no request, no finding. Its two neighbouring exits both append an info, so an empty populations from this one read exactly like "gnomAD has no data" for a question that was never put. Reproduced on the suite's own _H63D fixture, which is 6:26090951 C>G,T. A common GWAS lead SNP is usually multi-allelic in dbSNP, so this was most of the reporter's panel.

A second defect inside the first, which the report did not name: single[0] also dropped loci 2..N of a one-to-many rsID, in the same silence.

What shipped

Suggestion (3), which absorbs (1) and (2). Every allele of every resolved locus becomes a chrom-pos-ref-alt id and they go in one fetch_frequencies call — the client batches twenty per request, so a multi-allelic question costs the same one paced round trip the single-allele question did. A caller's alts= filters that set, so naming an allele asks about that allele. Three things that could not be asked now say so instead of returning an empty list: no locus resolved, a locus with no ref/alts, and an alts= naming an allele no locus offers (which names what was asked and what the loci hold). "gnomAD has no record for …" fires per allele, so a locus whose G is known and whose T is not says exactly that.

Two shape consequences, both house rules. Each populations row carries allele, variant_id and vrs_id, because a multi-allelic locus answers with one row per ancestry group per allele and nothing else in the row told them apart; the CLI's population line leads with the allele. And hint.vrs_id, a scalar, is filled only when exactly one allele answered — @vrsid-per-alt again: a first-wins scalar over two alleles labels the hint with one of them and says which nowhere.

RM254 — protobuf's gencode/runtime error is neither of the two types RM247's guards caught, so the CLI died again beside anything pinning protobuf<7

Severity high · Status ✅ SHIPPED 2026-09-21, released in 0.7.2 (enricher) · Owner enricher (packaging, atlas_protos) · Motivating case S107 — just-dna-lite's whole command line, dead on a clean install beside dagster

What was observed

Reproduced by overlaying protobuf<7 on the workspace: import just_dna_enricher.cli dies with google.protobuf.runtime_version.VersionError: gencode 7.35.1 runtime 6.33.6. grpcio-tools==1.83.1 (RM247's pin) stamps protobuf 7.35.1 into atlas_service_pb2.py, whose first statement refuses an older runtime; VersionError subclasses Exception directly, so except (ImportError, RuntimeError) at both module-scope guards and inside _atlas_client_or_none let it through, and the chain cli → alphagenome_check → atlas_client → generated took every command with it — RM247's blast radius, repaired for one exception type and reopened by a third. The [atlas] extra floored protobuf>=5.29.0, two majors below the stamp, so a resolver had nothing to refuse on and the break arrived at import instead of at install.

What shipped

One tuple, bound where nothing can fail to import it. atlas_protos.ATLAS_IMPORT_FAILURES is (ImportError, RuntimeError, VersionError) — protobuf's error when protobuf is present, a never-raised stand-in when it is not — and all three guards name it. The RM247 walk now asserts the name rather than a set each guard spells for itself, and walks the lazy guard inside _atlas_client_or_none too. The protobuf floor is the gencode stamp, protobuf>=7.35.1 under [atlas], read off the generated file by a test the way the grpcio stamp already was: a dagster co-install that asks for the extra now fails to resolve, which is the honest place to fail; one that does not ask for it imports cleanly. A third absence with its own sentence: client_absence() reads the stamp and the installed protobuf from metadata (never by importing) and names both numbers, the usual cause and the fix. A subprocess test simulates the gencode refusal and asserts the entrypoint comes up with the client marked unavailable.

Refused, as the reporter argued: regenerating against a protobuf-6 grpcio-tools trades this break for RM247's. Not done: moving alphagenome_check's import off module scope; the guarded import exists to bind exception classes for except arms, and with the tuple bound in one place a fourth exception type fails the walk by existing rather than escaping.

RM252 — pgx said "no use was declared" about a module whose licence table declared it, and asked the author to say it twice

Severity medium · Status ✅ SHIPPED 2026-09-20, released in 0.7.1 (enricher) · Owner enricher (licensing, every gate with a module) · Motivating case S105

What was observed

enrich_pgx loaded the licence table (it merges into it) and then gated each leg on the --use flag alone, so a module drafted under --use non-commercial was told "cpic forbids sale and no use was declared" by the command that had just read declared_use=non_commercial for CPIC. Reproduced: both legs not_permitted, the row untouched (the merge is never-clobber, so nothing was lost — the defect was the sentence and the skip, not the file). The same shape sat in every drafter: a second draft on the same module, without the flag, would have skipped too.

What shipped

licensing.effective_declared_use(spec_dir, terms, declared_use) — the flag when it states one, else the row recorded for that source at that layer, else unstated — in front of check_declared_use at all nine gates that have a module directory, with the effective value also the one the pass records. PgxResult.recorded_use names the legs whose declaration came from the file and the summary line prints it; the drafters say so in a warning. The flag outranks the file in both directions, unstated on disk is not a declaration, and PharmVar with no row still asks — each pinned. An AST walk asserts set equality over every check_declared_use call site: the nine through the helper, and the cache lanes, which have no module, direct.

Refused: treating a declaration for one source as the module's. declared_use is per source because the terms are; a CPIC row grants nothing about PharmVar (@declared-use-third-axis).

RM251 — a row authoring both an rsID and a coordinate was copied into resolution.csv, and the loci the pair check had already fetched were thrown away

Severity medium · Status ✅ SHIPPED 2026-09-20, released in 0.7.1 (enricher) · Owner enricher · Motivating case S104 — every CPIC-drafted module compiled with "VRS allele identity covers 0/N" and nothing the author could do about it

What was observed

enrich()'s last per-row branch — "already complete, or has a position — a full record, nothing to resolve" — wrote a subject carrying rsid and chrom/start into the table as source="authored", status="resolved", with the authored cells and nothing else: no ref, no alts, so no VRS id could mint. Reproduced on a fresh CYP2C19 draft against the provisioned caches: three rows, all authored, vrs_id empty on every one, and verification.json recording rsid_coordinate_agreement: subjects 3, findings 0 — because the same run had looked the rsIDs up. The pair check rides its rsIDs in the Ensembl cache batch, so the loci were in hand and discarded.

Half the report did not reproduce, and the reply says which half. The consumer read "the coordinate is never compared with what Ensembl holds": it is, by the enricher, and the record attests it. What was true is the other half — the table held a photocopy of the module, so the compiler's cross-check (resolve_from_table._verify) compared the module against itself, and no id existed to mint.

Why reference_examples/cyp2c19_star_alleles disagreed with the consumer's run: its haplotypes.csv was drafted before the 0.5.1 gene.chr join and carries rsid + start with no chrom, so its rows were rsID-only to the resolver and took the forward branch. The join that made a drafted row complete is what moved every later draft onto the verbatim branch.

What shipped

A pair row takes the forward branch when the reference knows its rsID: the same allele-aware filter, the same PAR rule, and the link's source, ref and alts are recorded, so an id mints and the compiler holds two independent values. The authored coordinate is untouched — it is the row's identity and the compiler keeps it; its positional fill completes only the cells the author left empty (ref, for the CPIC shape). A disagreement is now reachable: rsid_coordinate_agreement records it and the compiler's _verify warns in best_effort and refuses in strict, exactly the matrix row for an authored coordinate contradicting the table. Three cases still write the authored row, each pinned: an rsID the snapshot does not know (no link is asked live for a pair, so there is no answer and no negative to fabricate), a reference whose every locus the allele filter rejects (the mismatch is the finding and the row keeps its coordinate), and a run with no Ensembl snapshot. enricher/tests/test_authored_pair_resolution.py carries all seven cases including the round trip through compile_module in both modes.

Not done, deliberately. The consumer's authority-or-shifted column: nothing needs it. The authored coordinate already lives in the module, the table now holds the reference's, and the compiler already compares the two. A recorded table keeps its authored rows under merge-not-clobber; the doc says to delete resolution.csv or run --rederive, which since 0.7 costs nothing.

RM250 — scaffold then draft failed on the scaffold's own placeholders, and the remedy it offered was a parameter the drafters do not have

Severity medium · Status ✅ SHIPPED 2026-09-20, released in 0.7.1 (enricher + compiler) · Owner enricher (spec_genome_build) + compiler (draft.append_rows) · Motivating case S103 — the reference README's recipe, run verbatim, refused

What was observed

spec_genome_build read one field through the whole-file load_spec, so <<REPLACE>> in module.title, module.description and module.report_title — three cells a draft never reads — became "cannot read the module's genome_build", and the sentence ended "or pass genome_build= explicitly", which is enrich()'s parameter and no drafter's flag. With --kind naming the PGx tables, the stub rows refused a second time, as "existing haplotypes.csv does not validate" — the sentence for a broken file, about a row the tool had written itself.

What shipped

The build is read at the answerer. On a SpecError, the yaml is re-read with every placeholder outside genome_build filled by a placeholder and validated again; if that passes, the declared build is the answer. Only the scaffold's own stub is looked past: a misspelt key (genome_bild:), a wrong type, or a placeholder in the build cell still refuse, because reading the default past those would reopen the hole extra="forbid" closed — and the refusal now quotes the residual diagnosis rather than the placeholder sentence that had been hiding it. The remedy clause is gone. The stub row is diagnosed by the bytes, not by the error text: a row carrying the placeholder in any cell is named with its line and the two ways out (delete it, or scaffold without --kind when a drafter will write the table); a row a human broke keeps the plain sentence, and both arms are pinned. The README says why its scaffold line takes no --kind.

Refused: treating a stub-only file as absent. The stub has no natural key to merge on, and writing past it would leave a template row in a table the drafter then reports as valid; deleting it would be the drafter rewriting an existing row. Diagnose, never apply (@specific-rejection).

RM249 — the CPIC drafter said "the snapshot has no row for it" about a drug with 35 rows in that table, all keyed on a gene pair

Severity medium · Status ✅ SHIPPED 2026-09-20, released in 0.7.1 (enricher) · Owner enricher (pgx_draft, both CPIC clients) · Motivating case S102 — one module per gene of ClawBio's panel, and every thiopurine came back "no row"

What was observed

recommendations() keeps a row only when it names one gene, which is right: a row about TPMT and NUDT15 is not a statement about TPMT alone. But the empty result's explanation had three arms and the true one was unreachable on the snapshot path — knows_drug withholds there, so the reader was told the table had no row for a drug with 35 of them. Measured off the snapshot: 18 of 103 drugs are keyed only on a gene pair, 2,656 of 3,411 rows, six pairs, arity never above 2, no drug both ways — the count RM28 had been asking for since the ClawBio survey, now recorded there as its fifth corpus entry. Warfarin has no row at any arity, so the old "dosing algorithm (warfarin)" sentence had been describing a case the arm it sat on did not reach.

What shipped

partner_genes(gene, drug) on both clients — live, from the phenotypes maps; snapshot, from the gene_count > 1 rows — asked first when a drug comes back empty, and settling knows_drug without a second request when it answers. The explanation has four arms now, pairwise distinct and pinned: keyed with a partner (names it, and RM28), a typo, could-not-ask, and listed-with-no-row-at-all (warfarin, reworded to say what it now means). On the snapshot the answer is exact while no drug is keyed on more than one pair, which is CPIC today; the builder keeps no recommendation id, and the docstring says so.

Not done. No two-gene subject: that is RM28's, still parked, and the count is the maintainer's input to it rather than an argument here.

RM245 — a # source: line is a pointer that rots, and 53 of them rotted in one session

Severity medium · Status ✅ SHIPPED 2026-09-18 in the uncut 0.7 line · Owner the corpus (features/, schema/tests/test_feature_corpus.py) · Found by RM149's second pass, which measured the residue and left the repair as a decision for a reviewer

What was observed

Every scenario named its emission site as # source: <path>:<line>. For the 118 registry-tagged ones an alignment check kept the number honest within three lines; for the 110 structural ones the only check was the line is inside the file, which the second pass recorded as a known cost and the first pass had not measured at all.

Then it was measured against an actual session rather than argued. RM244 and RM246 were ordinary code changes — an import block, a shared module, a dataclass field — and afterwards 53 scenarios' # source: lines pointed outside the function they were written against. Not one of them was wrong about the code; every one of them was wrong about where the code is. The registry-tagged half was repaired four separate times during that work by a nearest-site realignment, which is a tool that exists because the pointer is fragile, not a reason the pointer is fine.

What shipped

# source: now names the file, and # anchor: names the symbol — a def or class in it. An anchored scenario carries no line number at all. There is nothing left to decay: a symbol moves with the thing it names, and the guard resolves it through ast rather than grep, because the name appears in its own docstring and in every caller and a grep finds whichever comes first.

The alignment check improved rather than merely survived. It used to be the emission site is within three lines of this number; it is now the emission site is inside this symbol's line range — no slack constant, and the claim is the one a reader actually wants to make. Carrying both an anchor and a line is refused: the anchor is the pointer and the line beside it is the half that rots.

225 of 228 scenarios are anchored. The three that stay line-only are the sites no symbol names — two module-level entries in vocab.py for @reserved verification-check members, and a module docstring in concordance.py. # source: <path>:<line> survives for exactly them, and a scenario with neither a line nor an anchor is refused rather than silently pointing at a whole file.

How the anchors were recovered, which mattered more than the grammar

Deriving each anchor from its current line would have written 53 wrong anchors into the corpus and made them permanent — the drift was already there. So each line was resolved against the revision it belonged to: a registry-tagged scenario's number had been realigned this session and is correct against today's tree, a structural one's had not been touched since the corpus was written and is correct only against the pre-session commit. Reading each against its own revision, then resolving the symbol forward, is the whole of the recovery — and the conversion went green on the first run, over both alignment checks, which is the evidence that it was right.

What is still weak, stated rather than implied

A structural scenario's anchor is checked for existence and not for content: nothing tests that "the position-level join is not a preference" is really about the function it names. That is the same gap the second pass recorded, one layer up — what it is no longer is a pointer that decays on its own.

RM246 — the mode ladder was written in three spellings, so the guard could only see a third of it

Severity medium · Status ✅ SHIPPED 2026-09-18 in the uncut 0.7 line · Owner compiler (ladder, resolution, compiler) · Found by the RM149 corpus's first pass, as finding 2 — a distinction nothing in the tree stated — and sized by the second pass's @ladder equality

What was observed

strict means reproducible artifact, and a check whose severity is the mode says so in code. It said so three different ways:

spelling what it meant sites
(errors if strict else warnings_out).append(f) one sentence, two channels 4 codes
if strict: errors.extend(same messages); return one sentence, two channels — and the symbolic-allele drop suppressed 1 check
ResolutionOutcome.strict_errors a warning paired with a different, longer refusal 3 codes

The third is not a variant of the first: calling those three ladder members and quoting the warning describes a compile that succeeds, and quoting the refusal quotes a sentence best_effort never emits. RM149's first pass could write that distinction down and no more — nothing enforced it, and the second pass's @ladder equality could only walk the first spelling, so it asserted a tag over four codes while its own subject had seven.

What shipped

just_dna_compiler.ladder — LadderFinding(warning, refusal=None) and route(findings, strict=…).

The third spelling is the general case and the first two are it with refusal=None, which is the whole content of the change: a ladder finding carries what best_effort says and, where they differ, the separate thing strict says instead. None is then a claim — the two modes say the same thing — rather than something a reader infers from which spelling a function happened to use.

ResolutionOutcome carries ladders and derives both warnings and strict_errors from them, where strict_errors used to be a settable field beside a separately-appended warning. As two fields either could be populated without the other; as two projections of one list, a refusal cannot exist without the warning it escalates from. plain_warnings is the stored half — findings that never escalate — and every existing reader of .warnings keeps working and now gets both halves.

What is deliberately still two things: what the compile does with an error. Resolution returns a failed result immediately under a strict resolution: prefix, because a module whose identities cannot be reproduced has nothing further worth checking; the allele-membership refusals accumulate, because they are per row and an author wants all of them. That is caller policy rather than severity, and route answers one question on purpose.

The symbolic-allele check keeps its strict parameter for the half that really is mode-dependent behaviour — best_effort drops the unusable rows and strict refuses instead of dropping — while its findings go through route like every other ladder member. A channel does not carry a drop.

The guard, rewritten twice in one sitting

test_the_ladder_tag_is_the_walked_set_of_mode_dependent_codes now walks LadderFinding construction, and the equality widened from four codes to seven — which is the unification proving itself rather than a rename: the three that were @ladder in prose only are now members of the same set.

The attribution had to become per construction, not per function, and that correction is the part worth keeping. The first walk credited every code in the enclosing function, which was right while the ladder was a whole-check property and wrong the moment resolve_from_table held both kinds — it reported nine plain warnings as ladder members because they share a function with two real ones. A code is a member when its CodedWarning sits inside the LadderFinding(…) call; the one fallback, for a ladder handed an already-built finding, applies only to functions with no nested-code ladder, so it cannot re-widen a mixed one.

Beside it, test_no_check_escalates_through_a_spelling_the_ladder_walk_cannot_see refuses the retired (… if strict else …) shape by name. A walk keyed on one constructor is blind to a check that picks a list instead, which is exactly how the ladder came to be three mechanisms reading as one.

RM244 — one code, two tiers, two sentences: the resolution findings now speak through one builder

Severity medium · Status ✅ SHIPPED 2026-09-18 in the uncut 0.7 line · Owner compiler (resolution_findings) + enricher (resolver) · Found by the RM149 corpus's second pass, from a (code, tier) walk the per-code equality could not make

What was observed

just_dna_compiler.resolution and just_dna_enricher.resolver are twins: the second reproduces the first's fill/expand/verify semantics against an injected Ensembl reference instead of an injected resolution.csv, and they deliberately share their VALID_WARNING_CODES members — the enricher's own comment says so, because the finding is the same and the remedy is the same and compile_module puts both paths' warnings in one channel. What they did not share was the words. Nine codes are emitted by both, and seven pairs were a different sentence:

code compiler said enricher said
rsid_unresolved not found in resolution table, position remains unset not in the injected Ensembl snapshot
rsid_without_resolution_label an aggregate over rows, with not an error — a coordinate is a complete identity Position X: no rsid found in Ensembl
resolution_not_injected No resolution.csv and no ensembl_cache injected… Ensembl resolution skipped: no reference cache found (set …)
resolution_skipped_cross_build two sentences of its own, one per fill a third
locus_cannot_host_genotype … rather than emitted as a row asserting an allele it does not have the same sentence, stopping one clause early
rsid_expanded_to_multiple_loci one line per rsID with the real row total (S33), PAR-aware one line per authored row
rsid_ambiguous rsid resolved as AMBIGUOUS … it is a pick, not a finding matches multiple dbSNP ids; resolved to X deterministically

A warning's text is an API a consumer greps (@warning-text-is-api), so one code with two sentences is one code a consumer can only half-match — and the corpus's per-code equality reported full coverage while holding none of the enricher's words for any of the nine.

What shipped

just_dna_compiler.resolution_findings — nine string builders, no imports, called by both tiers.

Placement is the compiler, not the format tier, and not by preference: the enricher already imports just_dna_compiler.resolution.genotype_fits, so that package is already the shared resolution vocabulary across enricher → compiler → format; and when the enricher's deprecated ensembl_cache route is removed at 1.0 the compiler is the sole remaining caller. Nothing in just_dna_format moved and no tier gained a dependency.

A builder returns str, never a CodedWarning. Each tier wraps the text at its own site, so the literal CodedWarning("<code>", …) stays where the code is emitted — which is what every AST guard in schema/tests/test_feature_corpus.py aligns against, and what keeps the (code, tier) equality readable rather than chased through an indirection.

None means this caller cannot establish the clause, and the clause is omitted — the house tri-state applied to a sentence. Four withholds, each a recorded decision rather than a convenience:

  • S61, twice. The enricher's snapshot leg may not say position remains unset, because lookup_variant's live leg has not run and may still place the variant. The same argument covers rsid_without_resolution_label: not an error is a claim about how the run ends, so the enricher passes reassurance=False. Both were nearly lost in the migration — the first was designed in, the second was introduced by taking a default and caught in review.
  • S33. The compiler accumulates one expansion sentence per rsID with the real row total and says which kind of many it is; the enricher's per-row copy stays, because it is on the route that goes away at 1.0 and porting the accumulator into a dying function duplicates rather than shares.
  • The tables. Only the positional fill can name which tables a cross-build skip left unjoined.

ambiguous_pick takes the event as a slot, because the two tiers describe different moments: the compiler reports a label resolution.csv already carries, and the enricher is at the choice, where no table state exists yet. Folding them would have the enricher announce something that has not happened.

What moved, declared rather than silent

Four sentences changed, none of them a phrase a consumer report quotes: the compiler's rsid_unresolved (not found in resolution table → not in the resolution table), its rsid_without_resolution_label and positional cross-build skip (reworded around the shared skeleton), and the enricher's resolution_not_injected remedy (a parenthetical became a sentence). The two consumer-visible phrases from the S61 thread — not in the injected Ensembl snapshot — and the byte-identical rsid_no_hosting_locus pair are unchanged.

What the guards caught, which is the argument for having built them

Three real breaks in one afternoon, none of them by reading:

  1. The dedupe. compile_module runs the pre-flight in best_effort whatever its own mode and de-duplicates on the message; migrating one of the two rsid_unresolved emitters and not the other published the finding twice. test_resolution_coverage_parity went red on the count.
  2. The line shift. Adding an import block moved 77 # source: anchors under the corpus, and the @code:/@check:/@skip: alignment named every one.
  3. A guard I narrowed while widening it. Making # text: search beside the emission site rather than instead of it — which RM244 forces, since a sentence is now assembled from a skeleton in one module and clauses in another — replaced a .py exemption with if not literals: continue, which silently exempts a scenario whose # source: path is a typo. Third narrowing of that same check; it now tracks was any candidate a real module separately, proven red against a fake path.

Two tests that pinned a sentence now derive it from the builder instead: a test that retypes the words pins its own copy, not the one a consumer greps.

RM243 — the paragraph that refuses to state a total stated four of them, summing to 17 of 24

Severity low · Status ✅ shipped 2026-09-13 in the uncut 0.7 line, documentation plus two walking guards; no code behaviour changes · Owner enricher reference + enrich._verification_records · Found by the RM149 Gherkin drafting round, from an AST count of what each module emits

ENRICHER.md's which of these attest paragraph opens by refusing to state a total, on the stated grounds that the two that used to be were wrong twice each and a number in prose is a registry nothing iterates — and then attributed a count to each of four commands. Measured: those four summed to 17 of the 24 emitting members of VALID_VERIFICATION_CHECKS.

claim measured
enrich() attests six 8 — published_refutation (RM170) and evidence_status_currency (RM160)
check-identifiers three 5 — pgs_accession_currency and pgs_metadata_agreement (RM163)
enrich_literature three 3 ✓
five commands one each 5 ✓, but three commands were absent from the sentence — clinpgx check-labels, litvar coverage, alphagenome check

enrich._verification_records' own docstring carried the same wrong six, so the figure was wrong in two places for the same reason: each of the four additions was correct, and none of them moved a number a few lines up.

The repair is RM218's, applied a third time rather than re-derived. That item found the identical class inside compiler.py ("up to twelve in all" against 23 parquets; "six reasons" against 8 return arms) and its conclusion was: state the rule rather than a figure, and assert the property the figure was standing in for. So the counts are gone from both places and the attribution lives in the check table, which already carried it per row and in more detail than the sentence ever did.

RM218's own lesson applied to this entry, too. Its guard's first catch was the repair's prose: a stale figure in quotation marks two lines below the rule reads, to a skimming reader, exactly like the rule. So ENRICHER.md names the shape of what went wrong and does not reproduce the four sentences — and the new guard, which keys on attests <number>, would have caught the draft that did.

Two guards, and the interesting one is the guard I got wrong first. The obvious invariant is the Where cell names the module that emits the record, and it fails on five rows that are all correct: that column names the site of the comparison, and reference_allele is compared in sequences.verify_reference_alleles and attested by enrich. Discovering that by running the assertion rather than reasoning about it is why it is written down here — the column means something narrower than its use suggests, and a future guard will reach for the same wrong version. What is asserted instead is that the pointer resolves: every backticked module.symbol in the cell names a real module of the package, which is the rot a rename actually causes. Which command to run stays prose in the same cell, because it is not derivable from a module name.

The second guard refuses attests <number> anywhere in the reference, pinned on the shape rather than on the old wording — the defect is a figure attributed to a command and would be just as stale spelled four. Both were proven by reintroducing the defect: a mistyped module name and a re-added count each turn the suite red.

RM242 — alphagenome check without an API key raised where it was supposed to attest nobody asked

Severity medium · Status ✅ shipped 2026-09-13 in the uncut 0.7 line, enricher only — one literal and one walking guard; no model, parquet or manifest change · Owner enricher (alphagenome_check.check_variant_impact) · Found by the RM149 Gherkin drafting round, from an AST walk of every skipped(...) call site rather than from a failing run

check_variant_impact's no-client branch wrote skipped(CHECK, "unchecked", …). "unchecked" is not a member of VALID_VERIFICATION_SKIPS — it is one of the per-pass spellings that vocabulary's own comment says the set replaced, and it survived in this one site. The model validates skipped against the vocabulary, so the branch raised ValidationError instead of writing a record.

The path is ordinary rather than exotic, which is what makes this medium rather than low: it needs a provisioned AVI reference, at least one variant whose score straddles the threshold, no --offline, and no client. That is just-dna-enricher alphagenome check run against a local snapshot by anyone who has not set ALPHAGENOME_API_KEY — the default state. The neighbouring --offline branch, three lines up, writes a valid record, so the two absences the file is careful to tell apart behaved completely differently: one attested, the other crashed.

The repair is offline, and the reason is the vocabulary's own rule rather than convenience. offline means the check needs egress and the run had none, which is exactly true of a run with no client; the distinction from --offline — a caller's choice versus a missing credential — is what detail is for, and client_absence() already writes that sentence in its own words (@specific-rejection). The rule is stated in the vocabulary's comment block: the human sentence travels beside the key, never instead of it. Giving the case a member of its own was considered and is the wrong shape: a consumer would have to learn a ninth spelling to be told something detail already says, and the set exists to collapse six such spellings onto one axis.

What was refused: pinning the one branch. A test asserting this call site's reason would pass the day another pass writes no_snapshot, which is the same class of defect one file over. So the guard is an AST walk over every skipped(check, "<literal>") in the workspace, checked against the vocabulary — @registry-completeness, assert an equality over a walked set. It went red on the live defect before the fix and names file and line rather than a count. A reason computed by the caller (AcmgUnavailable.skip, the PGS leg's pair, clinical.tautology_reason) is out of a static walk's reach by construction, and the test says so rather than claiming a coverage it does not have.

Why no test caught it. test_alphagenome_credential_is_read_where_used.py asserts where the credential is read and test_atlas_absence.py asserts what the sentence says; neither constructs the straddling-variant fixture that reaches the record. A branch whose only observable is an attestation nobody asserted is invisible to both — the shape @off-switch-needs-a-probe describes, one axis over: the disabling state was reasoned about and never run.

RM235 — one property over four registries: an outage reports as a broken identifier, and an unreachable EFO reports as clean

Severity low · Status ✅ shipped 2026-09-13 in the uncut 0.7 line, enricher only — a new verdict module, two properties retyped, two CLI branches; no parquet, model or manifest field changes · Owner enricher · Motivating case found while answering S100, not reported by a consumer. Filed on a premise the real code refuted — read the addendum before the body

IdentifierReport.clean is not (stale_rsids or stale_traits or stale_genes or gene_loci or stale_pgs), and check-identifiers --strict exits 1 on it being false. The three stale_* properties select their members differently, and two of the three do not exclude the state that means this registry could not be asked:

property selects an unreachable registry is…
stale_rsids state != "live" counted stale — a dbSNP outage is a broken rsID
stale_genes state != "approved" counted stale — an HGNC outage is a retired symbol
stale_traits state in {"obsolete", "absent"} silently dropped — an OLS4 outage reports clean

Measured against the real models, one row per registry, all three unreachable:

stale_rsids : ['unchecked']
stale_genes : ['unknown']
stale_traits: []
clean       : False        # --strict exits 1

So the same absence is a refusal on two registries and a pass on the third, and neither is right. Both directions break the same rule from opposite sides: the withhold arm must not be reported as a definite answer (@a-withhold-cannot-be-delegated-to-a-default-that-is-a-definite-answer), and one registry's outage may not write a verdict about another's subjects (@one-registrys-outage-may-not-speak-for-another). The refusing direction is the more serious of the two, because it fails somebody's build on a third party's downtime, and the author has no way to clear it.

Why this is not RM234's one-line change. ACMG has a single authority, so nobody asked is one predicate. This property combines four, so its unknown arm is per registry and combines under Kleene rather than withhold-on-any-unknown: a stale rsID found while HGNC was unreachable is still False, and all-clean-with-EFO-unreachable is None. That is a design with combination rules, and the CLI gates an exit code on the result — the widening is not done while a caller still gates on the narrow thing. pgs_metadata.drift's existing separation from clean is the precedent for how the answer gets split rather than overloaded.

Open questions the fix has to settle. Whether --strict refuses, passes or reports separately on an all-unknown run; whether gene_loci (a relationship, not a registry answer) joins the same arm; and whether verification_record for these checks already skips correctly the way ACMG's does, which is what made RM234 cheap — that has not been checked.

Addendum, 2026-09-13 — the measurement above was taken on the wrong instrument

Everything above about unreachable registries is wrong, and the body is kept rather than edited because what it got wrong is the instructive part. The table was produced by constructing IdentifierReport objects by hand and reading the properties off them. The states it gave those objects are not states the real pipeline writes for an outage, and one of them the type does not have at all:

  • RsidStatus.state is live | merged | absent | withdrawn. There is no unchecked member, and check_identifiers never populates report.rsids — rsIDs are checked in enrich(), which says so in its own docstring. stale_rsids is empty in every run of this command. The rsID leg's three-way split already exists one module over and is the pattern this item was asking for: unreachable_rsids (asked, failed), unconsulted_rsids (nobody looked), unresolved (no position).
  • GeneStatus(state="unknown") means HGNC answered and holds the symbol under neither fetch/symbol nor fetch/prev_symbol. That is a broken symbol, not an outage.
  • TraitStatus(state="unchecked") means the CURIE's prefix is outside _ONTOLOGY_IRI — a local fact decided before any request. stale_traits excludes it correctly, and _trait_record already splits unresolvable from asked.

An actual outage raises. Measured by running the real path against a port nothing listens on rather than by building a model:

OntologyClient(ols4_base="http://127.0.0.1:9/ols4", hgnc_base="http://127.0.0.1:9/hgnc")
check_identifiers(spec_dir=…, check_pgs=False, write=False)
→ IdentifierUnavailable: http://127.0.0.1:9/ols4/ontologies/efo/terms could not be reached

The CLI catches that, writes an unreachable VerificationRecord for all five checks with the detail string, prints IDENTIFIER CHECK FAILED, and exits 1. So a registry outage is already a hard refusal carrying a structured reason — which is the intended design and not a defect. @a-disagreement-with-a- document-may-be-in-the-instrument is the rule this item broke, and it was filed by the pass that had just applied that rule elsewhere.

What survives, and it is S100's shape rather than this one's

clean is not (…) over five lists that are empty when nothing was asked, so a run that checked nothing answers True to a library caller. The CLI does not publish that — it prints "no identifiers were checked" instead of the green line (S86) — but the property underneath it is what an in-process consumer reads, and that is exactly how S100 arrived: just-module-creator wraps these as MCP tools and reads the dataclass, not the terminal. RM234 fixed the same vacuity on AcmgReport.clean by widening to bool | None.

The shape to use here is a result type, not a third truth value (maintainer, 2026-09-13). A gate must be binary — a build that cannot be certified is a no, and --strict keeps exiting 1 — so the unknown does not belong in the verdict. It belongs beside it: clean returns a bool-like object, falsy when non-empty, carrying the set of reason codes that made it false, with the empty set meaning true. That keeps if report.clean: working unchanged, needs no tuple in a property's signature, and lets a caller ask why without a second call. Open question it inherits: whether RM234's bool | None is retrofitted to the same shape or left as the one exception, since the two clean properties would otherwise answer in two different kinds.

· from the RM234 investigation · related RM234, RM94, S86, S100

RM234 — AcmgReport.clean answered True about a comparison that never happened

Severity medium · Status ✅ shipped 2026-09-12 in the uncut 0.7 line, enricher only — no parquet, model or manifest field changes; clean retrofitted 2026-09-13 from bool | None to a Verdict by RM235, and nothing_to_check became a pass with it · Owner enricher · Motivating case S100 (just-module-creator), wrapping check-acmg as an MCP tool against enricher 0.7.0 from PyPI

clean was not self.mismatches, and mismatches selects the verdicts not_listed and denied. A run that obtained no SF list gives every row the verdict unchecked, so mismatches was empty and clean returned True — a run that compared nothing reporting as a run in which everything agreed. Reproduced with every cache lane blanked:

version=None  checked=0  clean=True     # no list consulted
version=3.3   checked=13 clean=True     # 13 rows compared, all agree

The two Trues mean entirely different things, and if report.clean: takes the first for a pass. That is the check-that-cannot-fail shape (@tautology-zero), one layer under S54's title-as-quote and one layer over S86's "current out of nothing".

The attestation was already right, which is what made this findable and what shaped the fix. verification_record has always returned a skipped record on both arms — "offline" when no list was obtained, "nothing_to_check" when one was obtained that no row could be looked up in — so the persisted record never claimed a pass while the in-memory property did. The repair is therefore not a second condition beside it: not_consulted names the arm or None, clean withholds where it is set, and verification_record reads the same property. The two answer the same question by construction, and a test asserts that equality across all five arms rather than checking either alone (@answered-is-not-absent — a verdict function with several arms owes a reason function with the same arms).

None, never False. Returning False would say the module disagrees with a list nobody read, which is the report-the-negation move the house algebra refuses; withholding is the third state. The reporter proposed both shapes and named this one as matching the rest of the toolchain.

Behaviour change for callers. None is falsy, so if report.clean: was already correct and stays correct — it is the spelling the CLI's green line uses, and its and report.version guard is now redundant and gone. if not report.clean: newly fires on an unconsulted run, which is the point. check-acmg --strict gates on mismatches and never on clean, so no offline run newly refuses.

One existing test was pinning the defect. test_offline_without_a_snapshot_is_still_unchecked_not_ absent asserted report.clean on an all-unchecked run. Unchecked-not-absent is a real property and the verdict list is what carries it; the clean line was the bug, asserted. It now reads report.clean is None.

The same shape sits one module over and is worse — see RM235, filed from this investigation rather than found by the reporter.

· from S100 (just-module-creator) · related RM235, RM72, RM94

RM233 — main was red on two jobs and green on every local run, and the difference was a colour code

Severity medium · Status ✅ shipped 2026-09-12, test infrastructure only — no package version moves, nothing in a shipped surface changes · Owner enricher tests + the suite root · Motivating case CI run 34703638770 at 2001215, the tip of main

Two tests failed on both Python jobs while uv run pytest was green locally: 2 failed, 4571 passed. Neither failure was about what it named.

test_the_flag_the_refusal_names_exists_on_the_command asserted "--use" in result.output over Typer's --help, and Typer renders through rich, which decides colour from the environment. A GitHub runner gets it; a non-tty local shell does not. With colour on, rich styles the two dashes as their own span, so the flag is emitted as \x1b[1;36m-\x1b[0m\x1b[1;36m-use\x1b[0m and the assertion is false for a flag that is right there in the text — reported as a command missing a flag it declares. Reproduced locally with FORCE_COLOR=1, which is the whole environment difference.

test_a_source_path_that_does_not_exist_is_refused_before_anything_downloads asserted "nothing will fetch it", and that one is not environment-dependent at all: Typer's error box is drawn at a width click.testing.CliRunner pins inside invoke(), so a sentence longer than the box is broken across lines with │ and padding in the middle. It had been passing through a local _unwrapped() helper that collapsed the box — and that is how the two became one item.

The repair is split because the causes are, and one of the two exits was measured shut. Colour is pinned once for the suite: a root conftest.py sets TERM=dumb, which is the value that fixes both halves of rich's styling where NO_COLOR=1 fixes only one and FORCE_COLOR outranks it anyway. COLUMNS was in the first draft beside it and is deliberately not there now: CliRunner pins its own width, so no environment variable can widen the box, and a line that looks like it addresses the wrapping while doing nothing is worse than its absence. Wrapping is handled where it can be, at the match: _unwrapped moves into enricher/tests/conftest.py as cli_text, exposed as a fixture because --import-mode=importlib means a conftest is not importable by name.

The transferable half is the private name. A normalizer for exactly this existed, in test_cache_lanes.py, called _unwrapped, and the second site that needed it could not find it — wrote in result.output, and was the test that went red (@roster-is-as-wide-as-the-tables-it-reads: grep for the question, not the bug; a private name keeps the second caller from finding the first). It also only ever collapsed box drawing, never escapes, which is why it survived colour and the raw assertion beside it did not. cli_text strips both and reads stderr as well as stdout, since Typer writes a BadParameter to stderr and a helper over result.output alone matches nothing for exactly the errors worth asserting on.

Scope, measured rather than assumed: 491 tests across 18 files invoke a CLI, and exactly two were affected — the other 489 pass on the luck of matching a token rich does not split, inside a phrase short enough not to wrap. That is why the colour pin is central rather than per-test: the next one would otherwise be found the same way, by a red main on a green local run.

enricher/tests/test_cli_rendering.py is the guard, and it asserts the property rather than the mechanism — no escape codes in rendered output, a flag name survives whole, and a wrapped diagnostic is matchable through cli_text and not through result.output, so the day the box stops wrapping the helper's reason is reported rather than left standing. Both halves were demonstrated failing first: the flag under FORCE_COLOR=1, the phrase in any environment.

RM232 — a drafted row lands before its licence row, and the seam RM231 built does not reach the compiler's writer

Severity high · Status ✅ landed 2026-09-12, past the v0.7.0 tag — the cut went in at 83b1674 while this was being built, so it is the first item of the next release rather than part of 0.7.0. The number is the maintainer's and CHANGELOG carries both readings: no parquet, no signature, no model and no manifest field (the test 0.5.2 used to take a patch), against a public compiler function growing an optional parameter (additive, so a minor). Not decided here · Owner compiler + enricher · Motivating case the two exemptions RM231 had to name

RM231 folded each enrichment pass's licence row into its data table's commit, so eight passes can no longer write a table and then fail to record what licensed it. Its guard is a roster equality, and to close that roster it had to name five exemptions. Two of them are this item, and they are S98's shape one layer over rather than a different problem:

  • civic_citations.draft_civic_citations gates merge_sources_file on result.added.
  • drafting.record_draft_provenance gates record_source_terms on covered — the scaffold's recorder, reached by civic_draft, mitomap_draft, pgx_draft, strchive_draft and clinpgx_draft.

Both are true only after the compiler's draft.append_rows / append_partial_rows has already renamed the drafted rows into place. A refused merge — a scaffold's <<REPLACE>> placeholder in licensing.csv is enough, which is the S98 trigger and needs no corrupt file — therefore leaves drafted rows in the author's own tables with no licence record. sources.csv is the only file the compile gate reads, so a CPIC-drafted module in that state has no no-sale clause to refuse on.

Why RM231's seam does not already cover it. layout.atomic_writer's before_commit binds one callback to one rename. A drafter appends to several tables — pgx_draft writes haplotypes.csv, allele_function.csv and diplotypes.csv in three separate append_rows calls, each its own atomic commit — so there is no single rename to hang the licence merge on. The compiler's writer never took the parameter, and the enricher cannot reach past it.

The fix, and the two repairs that are wrong. append_rows and append_partial_rows grow the same optional before_commit kwarg, threaded to all three atomic_writer sites, and every drafter passes a licence-commit closure factored out of record_draft_provenance so there is one body and not a second copy of RM228's decision. The callback then fires per file that actually writes, which is the correct grain: append_rows enters the writer only when it has rows to add, so the callback fires exactly when a licence row becomes owed for that table, and merge_sources_file being never-clobber makes N firings write one row.

  • Hoisting the merge ahead of the first append is wrong. covered is added or already_present, and the outcome vocabulary also has differs, appended_unkeyed and invalid — so a run whose rows all differ covers nothing and must write no row (@write-the-sourcerow's converse, S77/RM142). That cannot be known before the append is attempted.
  • Binding it to the first or the last append only is wrong. Last-only leaves tables 1..N-1 committed unlicensed if the merge fails there; first-only misses a run whose first table is all-differs and whose second adds.

record_draft_provenance stays at the tail and keeps all three of its jobs: the already_present-only run covers something, fires no callback, and still owes the row; withdraw_stale_dataset needs drafted computed over every report; the projection restamp is kind-driven. RM228 exists because those were once split.

The residual is stated rather than closed, the same one RM231 accepted: a rename that fails after its before_commit has returned leaves the licence row without that table. Conservative, and the OSError says what landed. Two files are two renames.

Filed at discovery, before the fix was approved — recorded here because the previous state of this gap was two honest exemption reasons in enricher/tests/test_licence_row_inside_the_commit.py and nothing in this file, and the release check is no open RMs, all green. A defect a test documents is not a defect the release gate can see. · from the RM231 handover · related RM231, RM228, RM222, RM142

What shipped. append_rows and append_partial_rows take before_commit, threaded to all three of their atomic_writer sites; drafting.licence_commit is the merge half of record_draft_provenance as a closure factory, so there is one body and the drafters hand the same callable to every append they make. record_draft_provenance calls that body itself at the tail, for the run that covered something and wrote nothing, and keeps the stale-label withdrawal and the projection restamp — both are answers about the run rather than about one table. The pre-flight sits inside the factory rather than in each drafter, so a new provider inherits it.

The guard is an equality from both ends. RM231's roster grows from eight to nine (civic_citations stops being an exemption), the two closures are named as being the callback, and a new walk asserts that every append_* call under just_dna_enricher carries a before_commit — 11 of them, all 11 unbound before this change and all 11 bound after. The AST helper had to learn the difference between a function's own calls and a nested def's: without it, a pass that did exactly what was asked read as a bare recorder, and a callback defined and never passed would have read as safe.

Two behaviour-preserving hoists were needed and are noted where they landed. clinvar_draft and pubmind_draft read their release label at the tail, and clinpgx_draft read its licence text there; the row's contents have to be known before the first write, so the pure reads moved up and the warnings each can raise stayed exactly where they were, gated as they were.

RM231 — alphagenome expression wrote the data, then failed to record its licence, and called that FAILED

Severity high · Status ✅ shipped 2026-09-12 in the uncut 0.7.0 (just-dna-format: one keyword on layout.atomic_writer; just-dna-enricher: one strict reader factored out of the merge, eight pass tails moved inside their table's commit, one AST guard; no schema change) · Owner enricher · Motivating case S98 (just-module-creator, in CONSUMER_SUGGESTIONS_HISTORY.md), a freshly scaffolded APOE module and the guide's own first AlphaGenome command

What it reproduced, and why the severity is high. _write_csv then merge_sources_file, two steps; a scaffold's licensing.csv carrying <<REPLACE>> made the second refuse. On disk: 12,003 rows of commercial_use=False Atlas output and no licence record anywhere. On screen: EXPRESSION FAILED. The compile gate keys on the licence table and nothing else, so the orphaned rows did not merely lack provenance — they compiled clean, as though unrestricted. A module that should be refused became one that is not; that is a licensing hole, not an untidy write. And scaffold → expression is the default happy path, so it landed there every time.

It was eight passes, not one. Grepping every writer (@sidecar-name-and-place's own rule) found enrich, assertions, gene_metrics, frequencies, gene_validity, gwas, clingen and expression with the same tail, each written independently; the eighth's author had read @enrich-is-a-transaction while writing it and still split the two, because the licence row did not read as part of the table. It is, and the fix is one primitive rather than eight edits of opinion.

The seam, and the two candidates it beat. layout.atomic_writer(before_commit=…) runs the callback after the temp file is closed and fsynced and before the rename. The merge refusing removes the temp; a table that fails to serialize never reaches the merge; neither file exists without the other. The consumer's first candidate, write the licence row first — small, idempotent, harmless in one direction — was refused because it is not harmless in the other: a row for a pass that then contributed nothing is the S77/RM142 false statement in a published artifact, and @write-the-sourcerow's converse forbids it. Their second, validate up front, is taken as well (require_sources_file, the strict read factored out of the merge and run before the fetch, so a placeholder fails in a second instead of after a 47-minute query) and is not sufficient, as they said: a concurrent writer or a full disk between the two writes reopens the window the seam closes. The if write and result.written gate is unchanged — a dry run and an empty match write neither file.

The residual is stated rather than hidden. Two files are two renames, and no callback ordering makes them one: the table's rename failing after the licence row's has returned leaves the row for data that never arrived. Conservative, and the OSError raised then names what landed — the consumer's closing ask, that a partial commit say what it committed, answered in the one case that is left. Pinned with a monkeypatched os.replace.

The guard is an equality over a walked set, and it names a gap it cannot close. Every function under just_dna_enricher that records a licence row either passes the merge as before_commit and pre-reads the table, or is listed exempt with its reason. Two of the five exemptions are the same defect one layer over: drafting.record_draft_provenance and civic_citations.draft_civic_citations record the row after the compiler's draft.append_* has landed the drafted rows, and the seam that would reach them is the compiler's draft writer — RM228's surface, handed to its owner rather than folded in here. A guard that names a known gap with its reason is honest; one that cannot see it is not.

RM230 — a leak an exemption hid, a remedy no flag could reach, and a debt that was not owed

Severity high · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 · Owner enricher · Motivating case the last three items of the 2026-09-11 re-derivation's enricher tail (C3, 7.6(a)) plus the debt RM228 recorded against itself

C3 — EuropePmcClient.lookup leaked all three legs, and the exemption that hid it was argued per method. lookup called _get bare and then .json() on the result, so a persistent 503 escaped as httpx.HTTPStatusError, a refused connection as httpx.ConnectError, and a 200 that is not JSON as json.JSONDecodeError — the exact fourth leg test_client_exception_contract.py exists for. Where it lands is what makes it high: enrich_literature calls this inside a try: whose only companion is finally:, verbatim the shape test_pass_exception_contract.py was written to refuse, and that suite's stub raises earlier on the eutils call so the leg was never driven.

The class sat in the contract suite's exempt set behind a note reading "EuropePmcClient.fulltext is deliberately not a leak". That is true of fulltext, which catches httpx and returns None — the tri-state withhold. An exemption is per class and that justification was per method, so it silently exempted a sibling nobody had looked at. This is the RM101/RM208 blind spot in a third form: first a roster's exempt set, then a guard inheriting the roster's exemptions, now an exemption whose reason is narrower than its scope. The note now says to argue from what the class promises.

Removing it exposed a second limitation: covered was keyed on the module, so it could not say that one literature client is covered while two remain exempt — it would have marked all three covered. A per-class covered_classes set is named explicitly beside it.

7.6(a) — the compile named a remedy that did not exist, and the trap is live. identifiers._pgs_source_rows built every PGS row with declared_use="unstated", hardcoded. The academic_research_only class is ScoreRights(commercial_use=False) at the annotation layer, which is exactly where taints_commercial_use reads — so the compile refused, saying "Re-run the enricher with a declared use (--use non-commercial)", and check-identifiers had no --use option. merge_sources_csv is never-clobber, so a re-run could not correct the cell either: the only exit was a hand edit. A refusal naming an unreachable remedy is worse than one naming none, because it sends an operator to a flag they cannot find and implies they mistyped it.

The audit left "does any live score classify that way" undetermined from code, so it was measured: GET /rest/score/all?limit=250 on 2026-09-11 returned three distinct licence strings, and 6 of those 250 matched the phrase — PGS000013 through PGS000017 among them. Reachable, not latent, which is what decided it got a flag rather than a note. The hyphenated spelling the refusal prints is pinned in a test, because the vocabulary member is non_commercial and it only works through check_vocab's separator normalization (@vocab-separator-slip).

The debt RM228 recorded against itself, disproved by writing the test first. That entry said clinvar_draft and pubmind_draft write their licence row on any non-dry run — the shape RM222 found wrong in civic_draft — and owed a fix. They do not: both return early, at "nothing matched; no rows drafted", before the licence write, so the property holds upstream of the gate and covered=True is correct for each. Measured: a --gene filter matching nothing ends with reports == [] and an empty spec directory. The test that would have proved the bug passes unchanged, and that is the finding. It is kept as a pin on the early return — the thing actually holding the rule, which nothing else asserted — so deleting it as redundant, or reordering the licence write above it, fails loudly rather than shipping the RM222 defect into two more providers. RM228's entry and ENRICHER.md are corrected rather than left claiming a debt that does not exist. @client-exception-contract · @write-the-sourcerow

RM228 — drafting was seven grassroots implementations of one mechanism

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 · Owner enricher · Motivating case the long-tail triage of the 2026-09-11 re-derivation (enricher 8.10 #3–#9), where the maintainer's read was that drafting "was created bottom-up and lacks structure — this is a clear sign", and the repair was scoped as a scaffold rather than as four patches

Seven *_draft.py providers turn a snapshot into authored rows. They grew one at a time, and by 0.7 each carried its own copy of the same four decisions. The copies had drifted:

  • clinpgx_draft and pgx_draft recorded a dataset and never withdrew a stale one. A module widened from a newer CPIC or ClinPGx release kept a licence row naming the older one — merge_sources_file is never-clobber, which protects a curator's terms and turns the release label into a false claim. Every other snapshot-drafting provider already withdrew.
  • pubmind_draft imported clinvar_draft._MATCH_ON across modules, coupling two providers' lap-2 matching through a private constant.
  • civic_draft consumed pydantic's rendered error message as an API, branching on "identifier" in message or "positional" in message or "chrom" in message.
  • DRAFT_PROJECTIONS was a hand-kept copy of the drafters' match_on — its own comment pointed at clinvar_draft._MATCH_ON by name.

The measurement that shaped the repair, and refuted the obvious fix. Four providers restated the model's skip rule and two derived it, so "migrate everyone onto the derived one" is the instinct. It is wrong: authoring_requirements("variants.csv") answers any_of: [['rsid'], ['chrom','start']], a grammar that cannot express VariantRow's third clause — ref/alts require chrom and start. The derived implementation therefore accepts {"rsid": "rs1", "alts": "G"}, a partial coordinate the model refuses and a compile would refuse (@identity-whole-or-none). The one provider that looked correct was derived from a subset, and migrating the others onto it would have spread the defect. Constructing the model is the oracle — the only complete one, and the one compile uses. authoring_requirements answers the human-readable which cells are missing and is not the verdict. That also deletes the message parsing: with every non-identity field pre-filled from values the model accepts, any ValidationError reaching the probe is an identity refusal.

The split the scaffold enforces. A skip rule is two rules: the model's requirement, derived and identical everywhere, and the source's precondition, a true fact about that snapshot declared with a reason. Mashed into one list they are indistinguishable — which is the state mitomap_draft's clin_sig clause was in. It gates identity on a column the model does not require, and it turned out correct: a rated_miss carries one by construction, and the guard buys a named refusal rather than a raw ValidationError about a column the author never wrote (@specific-rejection). The reason sat three lines below in a comment, so a legitimate constraint and a genuine misread read the same. SourcePrecondition.reason is a field and a missing one fails at construction. This item predicted mitomap would be its one behaviour change and it was not — the prediction was wrong, and the structure is what made the difference legible.

The import cycle was the diagnosis, not an obstacle. Deriving DRAFT_PROJECTIONS created a cycle the moment the scaffold needed stamp_draft_digest. That revealed draft_digest, stamp_draft_digest and drafted_unchanged had been drafting code sitting in provenance.py all along — a boundary only holdable while the registry was a copy. drafting now owns the registry, the derived projections and the whole drafted-value axis; provenance keeps the DraftProjection dataclass and imports nothing back.

record_source_terms gained license_texts, the same shape RM222 gave datasets one axis over. SourceTerms.row had always accepted one and this function had no way to pass it, so the two PGx drafters that extract a licence file had to build rows by hand — and were therefore outside every other guarantee it gives, including the withdrawal they were missing.

Enforcement is both kinds, because they catch different evasions. test_drafting_scaffold.py asserts the registry equals the *_draft.py modules on disk, and walks each module's AST to refuse a hand-listed identity column (off base.IDENTITY_FIELDS, so it inherits the schema's answer) or a direct merge_sources_file/withdraw_stale_dataset/record_source_terms call. All 18 fail on every one of the seven pre-migration.

Deliberately not unified, because either would change behaviour under cover of a refactor: each provider's covered predicate, and the stale-label wording — two providers ship two sentences and a published warning is an API (@warning-text-is-api).

A debt this entry recorded and then disproved. It said clinvar_draft and pubmind_draft write their licence row on any non-dry run — the shape RM222 found wrong in civic_draft — and owed a fix. Writing the test first refuted it: both return early, at "nothing matched; no rows drafted", before the licence write is reached, so the unconditional-looking gate is guarded upstream and covered=True is correct for both. The test that would have proved the bug passes unchanged, which is the finding. It is kept as a pin on the early return — the thing actually holding the property, which nothing else asserted — so removing it as redundant, or reordering the licence write above it, fails loudly instead of shipping the RM222 defect into two more providers. @drafting-scaffold

RM229 — CacheLane declared no size, so an onboarding offer had to du a box to price one

Severity low · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: one field on CacheLane filled for every lane, one field on LaneStatus, two functions, one number on a rendered line; no schema change) · Owner enricher · Motivating case S97 (just-module-creator, in CONSUMER_SUGGESTIONS_HISTORY.md), building a first-run offer to provision the locally-built lanes

What it reproduced. CacheLane carried everything about whether and how and nothing about how much, so the consumer du'd a provisioned box and kept the table as a dated constant — the hand-kept list RM176 retired for names, kept for a number that drifts faster, and one that cannot say whether it is stale. Their measurement agreed with this box's to the megabyte.

Taken: their option (1), with the canary that makes a declared number honest. approx_mb is an order of magnitude in whole megabytes, rounded up, 1 meaning at most a megabyte; None stays legal and means nobody measured, which is the answer they wanted to be able to report. A declared size is a counted-prose shape — it rots — so the test re-measures every lane present on the machine it runs on and refuses a declared number more than an order of magnitude off. That is the difference between this field and their constant: theirs could not tell a caller it was stale, this one fails a developer's suite when it is. Option (2), the size in release.json, is half taken the cheaper way: LaneStatus.size_bytes measures a present lane from the bytes rather than from a record a builder would have to write, and cache status prints it. Option (3), a Content-Length probe, was not asked for and is not taken: a network call to price a prompt.

The other half is a cost fact wearing a correctness field. parents reads as which digests get recorded, and the consumer found it is also what a blank box pays: mitomap_miss is under a megabyte and its parents are a ClinVar download. provisioning_closure(lane) walks it transitively in registry order, parents first — the sum they had hand-written — and the field's docstring and ENRICHER say so.

What they got right and did not need us for. Classifying acmg by calling prepare_lane and reading the refusal, rather than pattern-matching a <…> placeholder in build_command, is the intended reading: the route depends on the install, not the lane, and only the adapter knows.

RM225 — four stale claims a reader acts on, and the closedness one had drifted three times

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 · Owner format · Motivating case the long-tail triage of the 2026-09-11 re-derivation's schema candidates (D3, D4, D8, D9), walked item by item with the maintainer rather than batch-closed

Four candidates that a first pass reads as nits. Each turned out to be a sentence a reader would act on, and one of them had been written wrong in three separate places.

D3 — actionability is closed, and three places said otherwise. VariantRow.actionability shipped in 0.4.0 and _validate_actionability is check_vocab(...), a closed-vocabulary rejection. Against that: vocab.py's comment said "the field is not built yet, so this is not enforced"; base.vocabulary's own docstring — the helper that defines what closed means — listed the set among the closed=False recommended-but-open ones; and reference.py had already filed the axis under open_recommended in an earlier incident it still carries a note about. The constant's name carried it too: _SEED reads as "suggestions you may extend", which is what the validator refuses. Renamed to VALID_ACTIONABILITY with ACTIONABILITY_SEED kept as a working derived alias (P3), all three sentences corrected, and the SCHEMAS roster gains the row — where RM217's existing guard caught the rename within seconds, which is what that guard is for.

D4 — a dead constant that was not dead, it was unwired. CANONICAL_MT_REFERENCE_SEQUENCES is referenced nowhere in any tier, and the obvious reading is to delete it. The comment one line above explains why nothing enforces it — "not a closed allow-list (future refs exist), the validator rejects only this enumerated landmine" — and that is correct: an allow-list would refuse a legitimate future rCRS revision. But the refusal beside it ends use NC_012920.1 as a literal, restating the value the constant exists to hold. So the set had one real job and was not doing it. The message now interpolates it; the published text is byte-identical (@warning-text-is-api), and deleting the constant would have left the literal behind.

D8 — a comment naming the wrong counterexample, twice. pgx.py says, at two sites, "unlike VariantRow.chrom/StudyRow.chrom, these two models run no chrom validator". Measured: StudyRow.chrom has no validator and no vocabulary marker. VariantRow is the only one of the five models declaring chrom that validates. The asymmetry itself is deliberate and correctly documented — the marker is withheld precisely because nothing rejects, which is the drift D3 is about — so the fix is the counterexample, not the design. Measured across the corpus: 709 chrom cells, 3 non-canonical, all of them in the one table that normalizes. Latent, not live.

D9 — a docstring promising a tri-state the signature cannot express. is_multi_valued_number returns a bare bool and its docstring closed with "withhold, never negate, and never accuse". Checked every caller before touching it, as asked: there is exactly one (compiler._vcf_pointer_warnings), it is if is_multi_valued_number(number): gating whether to raise a warning, so False on an unknown cardinality is the withhold — warning there would be the accusation the sentence forbids. The narrowing is correct at the point where it happens; the sentence was the defect. Docstring now says why the collapse is the contract, and what a future caller needing the distinction must do instead.

The guard is the deliverable. Fixing four sentences fixes four instances; test_closedness_is_measured_not_declared.py is the class. It measures each marked field's closedness by handing its validator a certain non-member, and compares that against the flag the marker publishes — nothing in it reads a comment, a name or a document. A second test walks the constant names out of base.vocabulary's docstring and measures each: run against the pre-fix text it reports ACTIONABILITY_SEED (closed on VariantRow.actionability), which is instance #3, the one no tool could have caught because the marker was right and only the prose was wrong.

Recorded twice over: the grep guard failed on its own author's first run, because the replacement comment explains the defect by quoting the stale claim verbatim — the same trap RM218 hit. It now requires an occurrence to be wrapped in used to say "…", and the lesson is in its docstring: write the guard before the replacement prose. @registry-completeness · @field-description-is-a-claim

RM224 — sidecar_spellings was keyed on the table key only, so the preferred filename missed the deprecated copy

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-format only: one derived map, one public sidecar_key, one normalisation inside sidecar_spellings; no schema change, no spelling added or removed) · Owner format · Motivating case S96 (just-module-creator, in CONSUMER_SUGGESTIONS_HISTORY.md), building remote_derive over the registry's derived-sidecar tarball

What it reproduced. SIDECAR_SPELLINGS is keyed on the table key — sources.csv, the spelling sources.parquet and manifest.sources keep — and the preferred filename is not a key. So sidecar_spellings("licensing.csv") answered the one-tuple of a table it had never heard of, resolve_sidecar never saw the deprecated copy, and sidecar_write_path(spec_dir, "licensing.csv") on a module carrying sources.csv returned the preferred spelling: the collision the function's own docstring says it exists to prevent, reached by following it. A consumer holding bytes — a tar member named derived/licensing.csv, an upload part — has the filename and not the key, so the helper handed them exactly the spelling that did not work.

The fix, and the half not taken. The consumer offered two: normalise inside sidecar_spellings, or document that name is the table key. The first, because the second leaves the next consumer to notice the same thing. _KEY_FOR_SPELLING is the map read the other way, derived rather than written so a second aliased table costs no edit; sidecar_key(name) publishes it; sidecar_spellings looks the key up through it. Every helper that reads spellings — sidecar_candidates, resolve_sidecar, sidecar_write_path, preferred_spelling, the compiler's name sets, draft's spelling map — is fixed by that one line. Refusing a filename was not considered: the helper is most useful exactly where a caller has bytes and a name.

The sharper half is the read side, and it went into the gotcha book. The consumer's first defect was not the write: their displacement diff looked for licensing.csv, found nothing on a spec carrying sources.csv, and reported no rows leaving the table while the replacement went ahead under the other name. A helper whose wrong answer is a plausible path rather than an exception fails quietly in both directions — the shape @sidecar-name-and-place now names.

Pinned by two tests. One walks SIDECAR_SPELLINGS and asserts every spelling of every entry answers the same tuple, the same key and the same preferred name — an equality over the map, so a second alias is covered without an edit. The other is the consumer's measurement reversed, at the root and under derived/, plus the fresh-directory case still creating the preferred spelling whichever name was asked.

RM200 — the Atlas's other twenty-one scorers: what a module can take from them

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 · Owner enricher · Motivating case the AVI artifact is one number per variant with the sign discarded; the API carries direction, tissue and mechanism, and nobody had asked which of it is usable

Everything here is non-commercial. Only AVI_SCORE is a Permissive Use artifact (RM195). Every other scorer is ordinary Output, so it enters under declared_use=non_commercial and needs the second source name alphagenome_atlas — one (source, layer) key cannot carry two licence classes.

Built 2026-09-11, and what shipped is narrower than this entry proposed. The item asked what a module can take from the Atlas's other twenty-one scorers; the answer is RNA_SEQ and nothing else, for the reasons measured below. It ships as expression_effects.csv, the tenth derived-fact sidecar — not as an authored column and not as a finding. That third route is the one this entry's own open question did not consider: RM193's rule is that non-commercial Output never becomes a stored authored value, and a derived sidecar honours it literally while still carrying the per-gene direction a finding would have had to flatten into prose. Half cost under Principle 9 rather than full, and the compile gate stays exactly as data-driven as it was.

The two questions this entry left open are answered rather than deferred: what one cell records is one row per (variant, gene) with the tissue axis collapsed and the gene axis kept, because the gene axis is the whole reason the scorer is worth having; and finding or column is neither, per above. *_ACTIVE and the positional scorers are not adopted — the measurements below stand as the record of why, and nothing about them changed.

The correction this starts from

ALPHAGENOME_ATLAS.md § 4.7 concludes "there is no expression direction anywhere in the model". That is true of the AVI aggregate, whose eighteen features are all MAX_ABS_*, and false of the API. Measured on the live service: is_signed is True for RNA_SEQ, CAGE, ATAC, DNASE, CHIP_TF, CHIP_HISTONE, PROCAP and AVI_SCORE_MODEL_FEATURES. AVI throws the sign away; those never had it thrown away.

1. RNA_SEQ — adopt for drafting

The only scorer with a gene axis. Shape is (genes, tracks) and the gene count varies with the window — 61 genes at one variant, 48 at another, against (1, N) for all twenty other scorers. So AlphaGenome attributes it to genes itself, which is what @gene-map-is-another-sources-attribution requires: a gene claim must come from a source's own per-record attribution, never from a span the caller drew.

Signed, 371 RNA-seq tracks, and at chr22:20002007 it returns 22,631 values across 61 genes. That is expression, per gene, per tissue, with direction — the axis the shipped artifact cannot express.

Per-request only: no bulk copy exists, and at ~1,091 SNVs/s a gene plus its ±512 kb flanks is ~50 minutes (RM194). So it is a drafting surface for named genes, never a genome-wide pass.

2. Positional enrichment of authored rows — the shape is right, the obvious pick was wrong

A module is not gene-scoped: the mandatory gene filter is RM194's drafting constraint, because an unfiltered interval query dies with RESOURCE_EXHAUSTED. For a variant an author has already written, the position is known and a positional score needs no attribution at all.

CHIP_TF is refused on the measurement, and it was the most promising candidate. All 1,617 tracks carry a real transcription_factor_code (CTCF, EZH2, …), so "this variant disrupts CTCF binding" looks sayable. Aggregating |effect| by transcription factor over 751 distinct TFs:

variant PHRED top-3 TFs' share leading factors
chr22:30339156 C>A 84.1 2% ZNF513(1), HMBOX1(1), PCBP1(1)
chr22:20002017 C>A 19.6 3% AGO2(1), IKZF3(1), HMBOX1(1)
chr22:20002007 G>A 10.6 3% NRL(1), ZNF280B(1), ZNF768(1)
chr1:10001 T>A 1.1 1% ZNF48(1), PRDM6(1), SMAD7(1)

Two things kill it. The concentration does not track effect size — the PHRED 84 variant is no more concentrated than the PHRED 1 one — and every leading factor is a singleton track, so the "top TF" is whichever TF happens to be measured once. Naming a TF from that would publish a sampling artefact as a mechanism. Same test sinks a named-cell-type claim from ATAC: top-5 of 167 tracks carry 22% / 15% / 5% of the mass, least concentrated at the most extreme variant.

*_ACTIVE is not what its name suggests, and that is the useful finding. It is an activity level, not a variant effect: raw assay units (ATAC 5.7–31, ChIP_TF 332–475), and swapping the ALT barely moves it. So it does not describe the variant — it describes the locus. "This position sits in open chromatin in these cell types" is exactly the positional annotation an authored row could carry, and it is a different claim from anything the format holds today.

It needs a normaliser, and the metadata has one: every track carries nonzero_mean (167/167 for ATAC), so a level becomes fold-over-typical for that track. Without it a raw 31 and a raw 0.7 are incomparable, and a threshold means nothing — which is why the first pass found all 167 tracks "above 0.5" at every variant.

What has to be decided before building

  1. What one cell records. A per-track vector is not an authored cell. A magnitude, a count of tracks above a normalised threshold, or a top-k of ontology-typed terms are three different claims, and the track vocabulary is mixed — EFO 65 · UBERON 44 · CLO 40 · CL 15 · NTR 3 — so EFO:0001203 MCF-7 (a cancer cell line) and UBERON:0001159 sigmoid colon (an anatomical structure) are not comparable and NTR: is ENCODE's "no term registered".
  2. Whether this is a check or a column. RM193's position is that non-commercial Output enters as a finding and never as a stored value, which keeps the compile gate data-driven. A stored accessibility column would be the first thing to test that.
  3. CAGE was measured on 2026-09-11 and it splits: the ranking fails, the sign holds.
variant PHRED tracks negative top-5 share of 546
chr22:30339156 C>A 84.1 100% 2%
chr22:20002017 C>A 19.6 0% 3%
chr22:20002007 G>A 10.6 2% 4%
chr22:20002123 G>T 3.0 92% 5%
chr1:10001 T>A 1.1 18% 7%

The top-5 share is 2–7% and runs backwards to effect size, exactly as CHIP_TF did, so naming a tissue is the same sampling artefact — the leaders (Jurkat, retina, amygdala) are the top of a flat distribution.

The consensus fraction is a different quantity and it is not flat. 100% and 0% are unanimous predicted loss and unanimous predicted gain of transcription initiation, which is a directional claim about the variant needing no tissue named at all. It is not monotone in PHRED — 19.6 is unanimous-positive while 3.0 is 92% negative — which is what makes it an independent axis rather than a restatement of the score.

So the recordable shape is a consensus fraction, not a top-k, and that is the hypothesis the next scorer should be tested against rather than concentration.

Assayed 2026-09-11 — the full measurement is probes/ALPHAGENOME_ATLAS.md § 6.6

Three assays, and two of them refuted a hypothesis this entry had raised.

Consensus fraction is a property of the scorer, not the variant, so it is not a confidence measure and the shape proposed above is dead. CAGE and PROCAP are near-unanimous at every variant — 97% at PHRED 0.007 — while RNA_SEQ never exceeds 61%. What survives is only that under high consensus the direction is a claim; a record may say which way, never how sure.

RNA_SEQ's lack of consensus is structural, not noise. A variant can raise one gene and lower another, so its tracks should disagree — which is the sharpest argument that the gene axis is the thing to use and a fraction is the wrong summary for it.

*_ACTIVE does move with the ALT, and the maintainer's objection holds for every motif class. Re-tested against motifs found in the artifact's own REF column: ATAC_ACTIVE moves ~16× control in a Z-DNA former, ~15× in a G-quadruplex and ~10× in a poly-T run, reaching 20% at individual loci. So it is mostly positional with a real per-variant component wherever DNA geometry is at stake. The G4 row read background until the probe was fixed — it had been sampling motif centres, which are mostly loop bases, where disrupting a quadruplex requires breaking a tetrad. The signed ATAC channel spreads 27–151% at the same positions, so the model is not insensitive at all; the level is damped, as a level should be.

Positional scorers remain unusable as named claims, now on two independent tests rather than one: ranking fails (top-5 carries 2–7%, running backwards to effect size) and consensus does not discriminate. The track vocabularies also mix cancer cell lines, anatomical structures and cell types under one ranking, with three ENCODE no term registered placeholders.

So the item narrows to RNA_SEQ, and the remaining questions are unchanged: what one authored cell records, and whether non-commercial Output may be a stored column at all or stays a finding as RM193 has it.

Still unmeasured, and it is a use-case question rather than an assay one: whether an averaged locus accessibility buys a module anything. Every number says what the scorers do; none says a consumer wants it. That belongs in USE_CASES.md.

RM194 — gene-scoped SNV subslices, and the ±512 kb horizon

Severity low · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 · Owner enricher · Motivating case slicing the artifact by gene position silently drops promoters, enhancers and other distal variants that act on a gene without sitting in it

Built 2026-09-11. Shipped as just-dna-enricher alphagenome expression, writing expression_effects.csv — a recording pass rather than the drafting provider this entry describes, because RM200 landed with it and the rows belong in a derived sidecar rather than in variants.csv.

Both span forms ship, and the interval wins. The three candidates this entry weighed were the wrong shortlist: a fourth option — the operator supplying --chrom/--start/--end outright — needs no lane, no staleness story and no answer to "what if the span source disagrees with the module", and it is the default route. --gene alone resolves the span from the MANE lane (the only in-tier source with gene coordinates; the Ensembl snapshot is eliminated by its own schema, which has no gene column at all), widened by the ±512 kb horizon measured here. The gene filter is mandatory in both forms, because it is a server-side requirement rather than an optimisation.

Distance is recorded, as this entry required, and it is tri-state. The MANE lane is consulted even when the interval was supplied by hand — those are two questions, and an explicit interval only answers the first. With no lane the column is null and the pass says so, never an interval edge.

Two defects surfaced only by running the real command, both of which every offline test had agreed with: the Atlas wants chr22 on the wire where a module stores 22, and summary.parquet lives under a snapshot's data/ rather than at its root. A fixture confirms the convention its author chose, which is the standing argument for a live leg however small.

The blocker this item carried is gone. PROPOSAL_0_7_PT4 listed the interval RPC as the thing a first cut owes, "including the x-goog-fieldmask header and 32 bp chunking that hand-built requests got wrong". Measured on 2026-09-10 and none of that was the cause:

claim measured
the x-goog-fieldmask header is required no — the same interval answers identically without it; asserted as equality of the two answers, not as "both succeeded"
32 bp chunking is required no — a 128 bp interval answers in one call; the SDK's 32 bp sub-intervals are its parallelism strategy
— Interval.strand must be a real member. Strand has no zero: STRAND_UNSPECIFIED = 0 is the proto3 default, so an omitted strand goes on the wire as a value the server rejects — as a bare INVALID_ARGUMENT naming no field. That was the entire failure
— a filter is effectively required: unfiltered, 32 bp answers with a 43 MB message against a 4 MB receive limit

AtlasClient.score_interval shipped with RM192's commit for that reason — it is the client's missing half, it is now tested (offline and live), and leaving it out would have left the measurement unrecorded in code. This item is now the drafting provider and nothing else.

An upstream bug found on the way, and it is in the pagination: the server returns a next_page_token on an exactly-full final page, and following it is INVALID_ARGUMENT. A 1,000 bp interval (3,000 variants, short last page) correctly omits the token; 1,024 bp (3,072 = six pages of 512) does not. AIP-158 says an omitted token means no further pages, so a faithful client crashes on the one interval width that divides evenly. The SDK has the same loop and never trips it, because 32 bp cannot fill a page. score_interval follows the token but also stops once the requested interval is covered, with an offline regression test.

Why the provider was not built. Two reasons, neither of them the RPC:

  1. It cannot be validated in one night. Measured cost is ~1,091 SNVs/s, so a gene plus its ±512 kb flanks is ~3.3 M SNVs and ~50 minutes per gene. A drafting provider whose only end-to-end test takes an hour per case is not something to land unattended.
  2. Where the gene's coordinates come from is a design decision, not a detail. The provider needs a span before it can query one, and the tier has three candidates (the MANE lane, the Ensembl snapshot, the module's own authored gene) with different currency and different failure modes. @gene-map-is-another-sources-attribution says a source with no gene column is drafted through another source's per-record attribution, never a span — and here AlphaGenome is the attributing source, so the span is only a query hint and the attribution it returns is the claim. Which of the three supplies the hint changes what a stale one does.

What still stands from the design, unchanged and measured: gene attribution reaches ±512 kb and stops dead beyond it (scores returned at +500 kb, nothing at +700 kb — the half-window of the model's 1 MB input); distal scores run ~10× lower than at the gene, so a flat --min-score would silently keep only proximal variants and the distance must be recorded beside the score; and the lane needs a second source name, alphagenome_atlas, because RNA_SEQ output is ordinary non-commercial Output while the AVI artifact is the Permissive candidate — one (source, layer) key cannot carry two licence classes.

RM223 — the upgrade guide was the one maintained doc nothing walked, and four of its counts had rotted

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (docs + one guard; no code change) · Owner compiler (the guard lives beside test_counted_prose.py) · Motivating case a consumer repository measured four of the document's numbers against the installed packages and found all four wrong

INTEGRATION_0_7.md is read once, at upgrade time, by somebody who then acts on it. It said ARTIFACT_PARQUETS goes 19 → 22 where the constant holds 23; VALID_WARNING_CODES had 72 members in § 2.4 and 71 in § 3 where the vocabulary holds 73; and the authoring reference rendered "31 models, up from 28" where it renders 32. Three of the four moved for one reason — the AlphaGenome round landed expression_effects after the numbers were taken — and the fourth was a second copy of the first.

The document already stated the rule it was breaking. Its § 8 says a counted claim in prose rots exactly like a hand-kept list, and §§ 2.2 and 2.3 already tell the reader to derive from ARTIFACT_PARQUETS and OVERRIDABLE_TABLES. The advice was correct and was sitting one paragraph above the numbers that contradicted it, which is the same shape as the three long-tail items in this round: the rule is written down one layer away from where it was broken.

The reason it rotted is narrower than the rule, though, and it is the part worth keeping: test_counted_prose.py reads SCHEMAS.md and COMPILER.md and stops. Nothing walked this file. So the repair is not the four words — it is compiler/tests/test_integration_doc_states_no_registry_count.py, which refuses the shape: a current-size claim about a registry, in any of the three forms this document used. After the fix the document states no size at all, so the absence is the invariant and there is nothing left to value-check. Run against the pre-fix file at 1879a1f the guard reports all four.

What the guard deliberately permits, because its first draft did not and would have been worked around rather than obeyed: a frozen before value (goes 19 → len(ARTIFACT_PARQUETS)), an RM id or release line beside a constant, an enumerated delta, a measurement of a built artifact ("24 parquets" of atlas data is not a claim about ARTIFACT_PARQUETS), and the document quoting its own stale word back while explaining that it was wrong. Three of those five are sentences this item itself wrote.

Not fixed here, and not ours: the consumer also measured expression_effects.csv as present in OVERRIDABLE_TABLES and DERIVED_TABLE_MODELS but absent from their RECOGNIZED_SPEC_FILES, so the overlay grammar invites a correction against a table their rebuild drops. Both of this tier's registries agree with each other; the third is in their tree and is filed there. @registry-completeness

RM215 — allele case is inside content_signature, so one pair had two identities

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 · Owner format · Motivating case found by derivation during the 2026-09-11 blind re-derivation round, beside RM214

ALLELE_PATTERN is ^[ACGT]+$ with re.IGNORECASE, so a lowercase allele is legal, and an allele cell is stored verbatim. Measured on one VariantRow with the genotype spelled four ways:

'A/G'  sha256:ec8c6bcc…      'a/G'  sha256:1653d7ee…
'A/g'  sha256:0b0a1369…      'a/g'  sha256:78cb573e…

Four content identities for one heterozygote, which for a content-dedup key is wrong in exactly the way RM36's build conflation was. content_signature now upper-cases a cell whose grammar is case-insensitive; the four collapse to one, and the survivor is ec8c6bcc…, the value every existing module already had.

This entry was filed for 1.0 and the filing was wrong. It sized the change as major "the same reasoning RM81 applies to a retype", and that citation does not transfer: RM81 is a parquet retype (List(Utf8) vs Utf8), which P3 names explicitly as major-only. Folding at hash time adds, removes and retypes nothing — the authored cell is untouched, model_dump() is unchanged, the parquet column is unchanged, and the round trip is unaffected. What moves is a computed value, which is P3's own corrected derivation case: it "may ship in any release", never silently. RM36 is the precedent in this very function — genome_build was made to feed the hash in 0.5, a minor, on the identical argument: only the modules that were being misidentified move.

The three repairs the filing listed were also not the only options, and the one it did not consider is the cheap one. Upper-casing at the model would rewrite an authored cell; refusing lowercase would be a tightening needing RM52's upgrade procedure; hashing case-insensitively was described as making the signature "stop reading as the bytes" — but the signature has never read as the bytes. It already normalizes 1.00→1.0, column order, and an unset optional column, and allele case under a case-insensitive grammar is the same category. The bullet that says so was already in the docstring.

Scope is measured, not assumed. The fold is driven by a CASE_INSENSITIVE_ALLELE marker and reaches the four columns whose validator is that grammar — VariantRow.genotype, VariantRow.effect_allele, HaplotypeRow.allele, PharmVariantRow.genotype — found by probing all 57 models behaviourally rather than by grepping for the word "allele". Two near-misses are the reason the probe is behavioural: AlleleFunctionRow.allele is a haplotype name (*36+*10) whose validator merely shares a method name, and ModuleSpecConfig.authority_precedence is a list[str] that a string probe trips by its own duplicate check. ref/alts are deliberately out: neither is grammar-checked (both accept zz), because a non-nucleotide there is a spelling defect a later pass diagnoses (@non-nucleotide-spelling) — a field with no grammar has no case-insensitivity to inherit, and folding it would collapse values that genuinely differ.

No published signature moves, measured rather than asserted: 536 marked cells across reference_examples, none carrying a lowercase letter, so the fold is the identity function on every module published to date. That measurement is a test, because the minor-legality argument rests on it.

Nothing is declared in RELEASE_RECORDS, on purpose. The first draft added a DeclaredChange(axis="content_signature", kind="correction") and the record's own invariant refused it — a declared axis must be one the measurement reports as moved, and this one is False because nothing moved. P3's corrected-derivation clause is written for the case where earlier artifacts hold a value we no longer stand behind; zero artifacts are affected here, so there is no movement to declare, and forcing the axis to True would put a false measurement in the record to satisfy a rule about honesty. This entry and the CHANGELOG are the declaration.

Surfaced, not fixed (@fix-vs-surface): derive_variant_key's coordinate fallback does not fold case either — 1:100:a:g,t vs 1:100:A:G,T — firing for a multi-alt row or a non-GRCh38 build, since the VA path normalizes case already. That splits joins and dedup rather than identity and it moves a stored cell, so it is a different item. A parametrized test pins the current behaviour so the note cannot rot into a silent fix. @verbatim-except-order · @registry-completeness

RM217 — two vocabularies were documented in no maintained file at all

Severity low · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (docs + one guard; no code change) · Owner format · Motivating case the same superset sweep that produced RM216

Eight of vocab's 29 VALID_*/RECOMMENDED_* frozensets were named nowhere in SCHEMAS.md, the maintained reference for the tier that owns them. RECOMMENDED_ANCESTRY_GROUPS and VALID_EFFECT_DIRECTIONS appeared in no maintained document at all. The other six were reachable only from INTEGRATION and ROADMAP_HISTORY — files that record what one release did, not files that describe the tier — so a reader who arrived at the reference could not find them from there.

The document already described the mechanism and not the registry, which is the recurring shape: the vocabulary-binding bullet explains how a field carries its members and why there is no central registry, and explains it well. What it did not do is say which sets exist.

The table carries three things and deliberately not the members. Members are authoring_reference() and the constants themselves, and a hand-kept copy of a member list is how SOURCES_FIELDNAMES lost a column (@fieldnames-from-model). A count, an openness flag and a sentence about what the set is for are what a table can hold without rotting — and the count is asserted, so adding a member without touching the doc fails rather than drifting.

Openness is asserted too, because that flag is load-bearing. actionability shipped as an open seed while VariantRow rejected non-members, so a tool offering a novel value got a rejection it had been told to expect. A table mislabelling one would re-create exactly that.

Scoped to vocab's own sets, not the leaves' — spec, binning, pgx, pgs, manifest and sources own theirs, and a central registry would need vocab to import pgx, which is the cycle base's dependency note exists to avoid. The guard says so rather than pretending to be complete over something it is not.

RM222 — the CIViC drafter's licence row: written when it drafted nothing, and carrying no release

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: a gate, an optional parameter, and a docstring; no schema change) · Owner enricher · Motivating case the 2026-09-11 blind re-derivation — docs/audit/ENRICHER_FROM_CODE.md D13–D15

Three findings at one call site, all of them @write-the-sourcerow.

"One that contributed nothing writes none" was a comment, not a gate. The condition was if not dry_run: and nothing else, with that exact sentence directly above it — so a --gene filter matching nothing still wrote a civic row into licensing.csv. A licence row is a claim that the module uses the source; writing one for a module with no CIViC rows in it is a false claim, and the compile gate reads that file and nothing else. Both sibling drafters implement the rule (strchive_draft, mitomap_draft) and test_strchive_draft.py refuses this shape on that path, so the predicate was written down twice already and missing here.

dataset was computed and dropped on the floor. civic_dataset_label(...) reaches every drafted row's conclusion, and record_source_terms had no parameter to carry one — so the licence row read dataset=''. Not cosmetic: SourceRow.dataset is what --verify-datasets compares and what withdraw_stale_dataset withdraws, so a CIViC-drafted module sat outside the currency check every other drafted module is inside. record_source_terms gains an optional datasets mapping; an absent entry still leaves the column unset rather than guessing, which is what the fact passes want.

And the function's own docstring had stopped covering its callers. It read "None of these layers can taint a module: taints_commercial_use requires the annotation layer" — true of the three fact passes it was written for, and false since civic_draft began recording at annotation with an explicit declared_use. It sent a reader to the wrong conclusion about whether a drafting pass can taint. It can; that layer is exactly the one the gate reads.

The test drafts from the checked-in CIViC slice, so both "drafted something" and "drafted nothing" are real runs of the real provider. It is unfiltered for the positive case deliberately — naming a gene couples the test to which genes happen to be in a fixture, and what the case needs is a run that drafted.

RM219 — one fetch in the module whose documented rule is that fetches stage

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: one fetch staged; no schema change) · Owner enricher · Motivating case the 2026-09-11 blind re-derivation — docs/audit/ENRICHER_FROM_CODE.md D9

download.py states the rule at length and applies it everywhere but one line: "Staged through .part like every other download here, because a failed one is not a no-op. HfFileSystem.get creates the local file before it discovers the remote path is missing." The parquet fetch, the sidecar fetch and the root-file loop all stage. _provision_root_file_snapshot staged its payload and then fetched release.json straight to the target two lines later.

The cost is a state change, not a stray file. An absent label is nobody said; a present-and-unreadable one is the description is corrupt. A 0-byte release.json reads as the second: _json_parses rejects it and LaneStatus reports release_unreadable, sending an operator to re-pull a lane whose remote simply has no description to give (@an-absent-input-is-the-unknown-arm-and-a-malformed-one-is-the-refusal).

The test's fake reproduces the documented client behaviour rather than assuming it — get creates the file and then raises, which is the only reason the bug existed. A fake that raised without touching the filesystem would have passed against the unfixed code.

RM220 — the offline flag meant two different things, and the gated pass had the ungated one

Severity high · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: one gate; no schema change) · Owner enricher · Motivating case the 2026-09-11 blind re-derivation — docs/audit/ENRICHER_FROM_CODE.md D5

Two readings of the flag coexisted and nothing said which applied where. pgx makes it absolute, and test_pgx_licensing.py asserts it by name: "An injected live client is not a loophole: offline outranks the injection, because a live client under a flag documented as making no egress is exactly the failure RM38 closes." gwas does not, and says so in its own docstring: "An injected client still wins, because handing over a transport you already hold is not egress."

expression had gwas's shape against pgx's situation. Its gate was if offline and client is None:, and the AlphaGenome Atlas is licence-gated — its Additional Terms bar classes of holder outright — so an injected client fetched from a gated source under a flag documented as making none. @flag-means-same.

The axis the two readings differ on is the source's licence, and that is now written down in ENRICHER.md rather than inferable only by reading three modules. gwas keeps its behaviour on purpose: the GWAS Catalog is ungated, its docstring argues the case, and changing a stated contract for a Python-API caller is a decision rather than a repair.

The licence gate was masking the egress hole, which is why the test declares its use. With declared_use at its default the run is skipped by check_declared_use anyway, so a test that left it there would have passed against the unfixed code — the second gate standing in for the first. Declaring the use removes it and leaves only the gate under test.

RM221 — three help texts, a size, a "vendored", and a count: five claims that had stopped being true

Severity low · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (help strings, comments and one doc paragraph; no behaviour change) · Owner enricher + format · Motivating case the 2026-09-11 blind re-derivation — docs/audit/ENRICHER_FROM_CODE.md D1–D4

Rich ate the extra's name out of three rendered help texts. Typer renders through Rich, which reads a bare [word] as a style tag, so atlas --help printed "Needs the extra" and atlas generate --help printed "which is in and deliberately not in" — telling a new user nothing at all about which install to do, on the first screen they read. Escaped.

Two declarations of the extra's size disagreed, 22 MB against 19 MB, and the file carrying the measurement is the one that was right: enricher/pyproject.toml records 19 MB in a clean venv on 2026-09-10, and 22 MB is the grpcio release current at the design round. The stale figure had reached five places — including two paragraphs of ENRICHER.md written earlier the same day by the pass that added the AlphaGenome §, which is how a superseded number propagates.

"Vendored" survived RM196 in two places. The atlas group help and ENRICHER.md both said the bindings are generated from sources vendored in docs/vendor/alphagenome_protos/, while atlas generate --help two lines away said "The sources are not vendored" — and the directory holds a README and nothing else. The second is what the code does.

And a count beside its registry, one tier over (D4): VALID_VERIFICATION_CHECKS' first block read "enrich writes these six" while enrich writes eight — published_refutation and evidence_status_currency are filed under the next heading with — enrich beside them, so membership was right and the sentence had drifted. This is the failure verification.py's docstring records correcting three times, one file from where that lesson is written down, and it survived because the existing guards assert membership of the whole vocabulary and no test read a block. The number is gone and test_verification_record.py now walks both sides — the names enrich._verification_records passes to ran/skipped, and the names commented — enrich in vocab.py.

RM218 — the counted-prose rule reached docs/ and stopped at the source

Severity low · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-compiler only: comments, one docstring pair, and a floor promoted to an equality; no behaviour change) · Owner compiler · Motivating case the 2026-09-11 blind re-derivation — docs/audit/COMPILER_FROM_CODE.md §§ 13.4–13.6, 13.8

test_counted_prose.py exists because the same number went stale twice, and its _DOCS constant scopes it to the documentation tree. The same class was live in compiler.py itself:

claim measured
"up to twelve in all" (the module docstring's parquet count) 23
"There are six reasons … and a reader needs the six" (_vrs_gap_reason) 8 return arms
"covered three of the sixteen names" beside ARTIFACT_PARQUETS true as history, read as current

_vrs_gap_reason is the instructive one: RM5 added the symbolic class and RM59 the unobservable class, each correctly, and neither moved the number two paragraphs up.

No number was re-counted. Both sentences state the rule now, and the guard asserts the property each was standing in for — for the parquets, that the docstring names the constant; for the reasons, @answered-is-not-absent's actual requirement that the arms be pairwise distinct, which a count never checked. Eight arms returning six distinct strings would have satisfied the old sentence exactly.

The guard's first catch was the repair's own prose, which is worth keeping: the replacement docstring quoted the stale phrase verbatim while explaining it, and a stale figure in quotation marks two lines below the rule reads to a skimming reader exactly like the rule.

A floor became an equality (§13.5). _build_weights states its 39 columns twice by hand — its own comment says so — and the guard was required.issubset(...) over a 15-name literal, leaving 24 columns unwatched. @registry-completeness says equality over a walked set, never a floor; the declared schema is now that set, the emitted parquet must match it exactly, and a second test compares the function's two hand-kept halves to each other. No live drift was found, so this is an unguarded invariant rather than a broken one.

And a docstring that over-claimed, in both copies of itself (§13.6). validate_spec's said strict "changes severity only; it never adds or removes a finding". Two findings are aggregates with no best_effort counterpart sentence — the unresolved-position refusal and build_disagreement_error — whose best_effort rung is a different sentence firing in both modes, so strict genuinely adds them. The code is right and the sentence was wrong: the contract the two commands share is that validate(strict=x) and compile(strict=x) reach the same verdict, not that the two modes of validate differ by a severity column.

Surfaced, not fixed (§13.8): ensembl_reference and ba1_threshold are compile_module parameters the CLI cannot reach, so manifest.compilation.ensembl_reference cannot be stamped by the shipped command at all. Neither is a defect and neither is a decision anyone took — test_cli_parity.py does not assert compile-flag parity — so COMPILER.md records the gap and leaves whether to close it open. That question is RM278 (filed 2026-09-27).

RM216 — fifty-one error types named nowhere, in the § titled what a caller catches

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (docs + one guard; no code change) · Owner enricher · Motivating case the superset sweep of the 2026-09-11 blind re-derivation — every identifier the from-code snapshot names, grepped against the maintained document

The sweep the round owed and had not run: take each *_FROM_CODE.md, pull every backticked identifier, keep the ones the package actually defines at top level, and grep them against the maintained doc. 341 real surfaces came back absent across the three tiers. Most are legitimately delegated — per-field and per-column names are @fieldnames-from-model's business and belong in the snapshot, not in a hand-kept table. Error types are not, because a consumer writes one in an except.

ENRICHER.md's exception-contract § carried the ten-row pass→type table a consumer usually needs, and the tier defines 83 classes. Fifty-one of them appeared nowhere in the document, so a consumer meeting ClinPgxUnavailable, GatedSnapshotError or AtlasRefMismatch had nothing to look it up in.

Grouped by what raises them rather than alphabetically, because the groups are the contract: a runtime pass's type is what a consumer catches, a client's is what the pass translates and the consumer never sees, a builder's belongs to cache rebuild, and the snapshot readers' are FileNotFoundError subclasses on purpose.

The third column is a ladder, not a set, and a second test asserts it really is one. A subclass makes a caller's except order load-bearing (@client-exception-contract), so a reader uses that column to decide which handler comes first — a row claiming a narrowing that is not one would have them order handlers against a hierarchy that does not exist. AtlasRefMismatch is the single entry two levels deep.

Equality, not containment, since the table says about itself that it is every type this tier defines: a name in it the package does not define sends a reader looking for a class that is not there, which is the same defect one direction over. Builtins are dropped rather than the pattern narrowed — the pattern is what makes a new error type join the roster by existing.

RM213 — merge_key raised for a missing key and collapsed silently for an empty one

Severity low (latent) · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-format only: one guard; no schema change) · Owner format · Motivating case the 2026-09-11 blind re-derivation — docs/audit/SCHEMAS_FROM_CODE.md D1, measured

The function's own docstring states the failure it must produce: a caller reaching here for an unkeyed kind has a bug, and a silent () would merge every row into one. It raised AttributeError for a model declaring no key and returned () for one declaring an empty key. MeasureBinRow declares exactly that, as a base-class default meaning subclasses set this.

Measured: two MeasureBinRows differing in every column returned equal keys.

Latent rather than live, and worth saying so. measure_bins.csv is authored while merge_key serves the machine-produced sidecars, and every MeasureBinRow subclass overrides the default — so nothing reaches it today. What made it worth fixing is that the next kind to inherit the default and forget would find the collapse in a merge pass rather than here, and a docstring that promises a failure is a claim like any other.

hints.table_key is deliberately unchanged. It reads the same falsy value as no declared key and answers None, which is correct for its own question — does this table publish a key a consumer can join on? This one asks what two rows' identity is, and there is no empty answer to that.

RM214 — the allele grammar is case-insensitive and the ordering rule beside it was not

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-format only: a sort key; loosening only, so no authored value moves) · Owner format · Motivating case the 2026-09-11 blind re-derivation — docs/audit/SCHEMAS_FROM_CODE.md D2, measured

vocab.ALLELE_PATTERN carries re.IGNORECASE, so a lowercase allele is a deliberately legal spelling. The unphased ordering rule next to it used a plain sorted() — ASCII, which puts every uppercase letter before every lowercase one. So of the four case spellings of one heterozygote:

A/G  accepted        A/g  accepted
a/g  accepted        a/G  REFUSED

The same unordered pair, two answers, decided by which half the author happened to shift.

The key is str.casefold and the sort is stable, so every value that sorted before still sorts and nothing already authored moves. It only stops refusing the mirror spelling, which makes this a loosening and therefore minor-legal (P3 bars tightening, not widening).

What it deliberately does not do, and why that is the interesting half. It does not make the pair canonical: A/g and a/G are both accepted and hash differently under content_signature, because the cell is stored verbatim. @verbatim-except-order is exactly on point — the rule normalizes the ORDER and nothing else, and the exception it names is an encoding that lies about its own order, which is what ASCII was doing here. Normalizing allele case is a different act: it would move the signature of every module carrying a lowercase allele, which is a question about what an identity key means and therefore 1.0 work. Filed as such rather than smuggled into a minor.

RM212 — the AlphaGenome key in a .env was invisible to the two paths that read it

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: load_env() at two call sites, and the refusal gains its diagnosis; no schema change) · Owner enricher · Motivating case the 2026-09-11 blind re-derivation — docs/audit/ENRICHER_FROM_CODE.md D12, measured with a real .env

@credential-where-read has two clauses and only the first was kept. Reading os.environ at the point of use is one; a guard in front of a loader must load too is the other. expression._connect — the one function in this tier whose own docstring cites the rule — read the variable without calling load_env(), and nothing else on alphagenome expression's path loads a .env. So a key that lives only there, which is where this workspace's does, was invisible, and the pass refused with ALPHAGENOME_API_KEY is not set while the file sat in the working directory.

cli._atlas_client_or_none had the same gap with a quieter failure: it degrades to a printed sentence rather than raising, so alphagenome check reported no ALPHAGENOME_API_KEY, so nothing was refined and fell back to the knot table's interval for rows the Atlas could have refined. Two sites, one omission, which is why one test asserts both.

It is the same incident one lane over, and caches._rebuild_pharmvar already carries the comment: the PharmVar lane reported "no key" and never built on the one machine most likely to have one, because PharmVarClient.__init__ loaded the .env and the guard in front of it did not. That comment ends a pre-check that answers differently from the code it is guarding is worse than no pre-check — this is the same sentence with a different variable.

The refusal now names which absence it is. missing_credential_reason was already the tier's answer to export FOO= being strictly stronger than never setting the variable (load_env uses override=False, so a present-but-empty value is kept); both AlphaGenome messages said only "not set", which sends an operator with an exported-empty shell to the wrong fix. Both states are asserted.

One rule violation fixed on the way: cli._atlas_client_or_none carried an inline import os, which is not the guarded-optional-dependency exception the function's other inline import is. It is at module level now.

RM210 — one finding, two counts, because the two sides were handed two views of the table

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-compiler only: one argument changed; no schema change) · Owner compiler · Motivating case the 2026-09-11 blind re-derivation — docs/audit/COMPILER_FROM_CODE.md § 13.2

_cross_check_literature runs on both sides of the validate/compile pair and every message it builds embeds a count. compile_module de-duplicates the second run on the message string, which is exactly as safe as the two runs seeing the same input. They did not: the pre-flight got loaded_kinds (the tables as loaded), the compile its own kind_rows (the tables after _apply_symbolic_drops).

One table is both droppable and citing, which is the whole mechanism. pharm_variants.csv is in _SYMBOLIC_DROPPABLE_TABLES and in the citing kinds, so a pharm row that carries an unusable symbolic allele and cites a PMID is citing to one side and gone to the other. Reproduced on reference_examples/pgx_slco1b1_simvastatin plus two cells:

literature.csv describes 1 citation(s) … ['99999999']
literature.csv describes 2 citation(s) … ['29165669', '99999999']
warnings_summary: {'literature_row_uncited': 2}

Two contradictory published claims and a count of two for one finding. The existing guard asserts len(warnings) == len(set(warnings)), which two distinct strings pass.

The repair is to make the inputs agree, not to stop re-running. @no-rerun-with-counts forbids re-running a check whose message embeds a count; running a check on both sides is the normal case here and the rule says so. The pre-flight had already computed survivors — the same post-drop view — three lines earlier for the positional fill, so this is one argument, not a new code path.

Which of the two sentences is right matters, and it is the post-drop one: the dropped row is not in the artifact, so the citation it carried really is orphaned there. Publishing the pre-drop count would describe a module that was never compiled.

Scope stated rather than narrowed. The same input reaches citation_not_in_pubmed and the quote-counter finding, which share the function; all three are fixed by the one argument.

RM211 — @parity-by-check, on the sibling RM93 left behind

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-compiler only: four checks gain a pre-flight call site; no schema change, no message change) · Owner compiler · Motivating case the 2026-09-11 blind re-derivation — docs/audit/COMPILER_FROM_CODE.md § 13.3

The compile-side per-model closures are where parity keeps failing, and the reason is structural: a table is loaded in both commands, so a pass auditing table by table sees it covered and stops. @parity-by-check exists because of that. RM93 moved _check_frequency_arithmetic out of one such closure and left its sibling behind — _check_gene_metrics_arithmetic is the same validate-by-redundancy over a sidecar's own numbers, needs no output_dir, no reference and no resolved row, and stayed compile-only for two releases. A module whose oe_lof disagrees with obs_lof / exp_lof passed a green validate and warned at compile.

Four moved, each with what makes it legal under the standing exemption — what stays compile-only is a check reading resolved rows, not the word "resolution":

check why it is pre-flight-legal
_check_gene_metrics_arithmetic reads one sidecar's own columns and nothing else
_cross_check_gene_metrics keyed on gene, which is authored and which nothing fills
_cross_check_gene_validity same key, one table over
_check_declared_license_agrees sources.csv against module_spec.yaml's own license: — two authored files, no join

And five deliberately did not move, recorded because an exemption nobody writes down is re-derived as a bug next round. _cross_check_frequencies, _cross_check_clinical_assertions, _cross_check_gwas_effects and _check_ba1_lint are keyed on position or variant_key, and an rsID-only authored row has no coordinate until resolution runs — asking them early would report every such row as an orphan, which is a worse answer than a late one. _source_checks is the other kind: its used_sources is complete only once every sidecar has been read, and sources.csv is last in _FACT_TABLES precisely so the compile can ask it against a full set. Asking it in the loop would answer over a partial set and warn about orphans that are not.

No new dedup was added, which is worth saying because the neighbouring closures carry one. The fact-table extend site already filters every check's warnings on the message (@first-fact-check-on-both-sides: dedupe where the results are collected), so the two newly-doubled findings are covered by the mechanism that was already there — and neither message embeds a count, which is what makes the two runs byte-identical.

RM207 — the one refusal that is fatal in both modes was asked of the wrong key, on the wrong side

Severity high · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-compiler only: one loop replaced by three shared helpers, and four lines in the pre-flight; no schema change, no published text change) · Owner compiler · Motivating case the 2026-09-11 blind re-derivation round — docs/audit/COMPILER_FROM_CODE.md § 13.1, written from the code with the maintained doc unread

Two defects with one root, and the second is the one that mattered. resolve_from_table ended with a loop over patched — the rows after the fill and the expansion — looking each one's variant_key up in the injected table. But the table is keyed by the key the author wrote, and the loop at the top of the same function says so (resolution.get(v.variant_key)). For a row the fill merely completes, the two strings are equal and the check worked. For a row the table expands, they are not: update["variant_key"] = derive_variant_key(...) mints the locus's ga4gh:VA.… id, and looking that up in a table keyed by rs111033563 misses every time.

So the refusal the code's own comment calls "fatal in BOTH modes" was silently skipped on exactly the rows that expanded. Reproduced on reference_examples/hfe_hemochromatosis with one extra resolution row: a module carrying a withdrawn rsID on a two-locus variant compiled clean, success=True.

And the check only ever existed on the compile side. resolve_from_table is called from compile_module and nowhere else, so where it did fire, validate reported the spec valid in both modes and a plain compile then refused it — the sequence test_validate_agrees_with_compile.py's own docstring calls "the one thing this command must never do". The standing compile-only exemption does not cover it: what stays compile-only is a check reading resolved rows, and this one reads the injected table's own rsid_status column, needing no output_dir, no reference and no resolution having run. That is the same test unresolved_subjects was factored out under (S76), and the repair is the same shape — withdrawn_refusals, ambiguous_refusals and ambiguous_warnings are now shared predicates both sides call.

Sentences, not subjects — a deliberate difference from unresolved_subjects beside it. That one returns names and lets each caller phrase them, which is safe because both phrasings are one clause. These interpolate two things, the subject and the retracted rsID, and the standing rule is share the predicate and copy the error; a two-interpolation sentence copied into a second caller is precisely how the two drift. So the sentence is shared and there is one of it.

The channel prefixes are copied, and that was the deciding constraint. compile_module publishes these as resolution: … and strict resolution: …, and that text is what a consumer greps (@warning-text-is-api). Emitting the bare sentence from the pre-flight would have changed the published string on every module that carries one — so only the channel label is restated, and a test asserts set(validate.errors) == set(compile.errors) rather than "validate also said something".

Refused: re-deriving the check in the pre-flight. A second implementation beside the first is the drift the shared predicate exists instead of, and it is what unresolved_subjects's docstring already argues at length one function up.

The ambiguous arm rode along because it is the same loop and the same key bug, one severity down: strict-only, so validate --strict is where it has to appear. compile_module runs its pre-flight in best_effort whatever its own mode, so the strict arm there is validate --strict's and the compile reaches the identical text by its own path.

RM208 — two clients put the translation inside the retry, so one never retried and one never translated

Severity high · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: the _request/_get split on two clients; no schema change) · Owner enricher · Motivating case the 2026-09-11 blind re-derivation round — docs/audit/ENRICHER_FROM_CODE.md D10 and D11

One root cause, two opposite symptoms, which is why they are one item. Every other client in the tier keeps the retrying half in its own function and the translation outside it — eutils._request / _get, cpic._request, gnomad._request. Two clients never got that split, and each broke a different half of @client-exception-contract's "retry, then translate, both legs".

CrossrefClient.exists never retried. Its decorator asked for attempt_floor(3) on (httpx.TransportError, httpx.TimeoutException); its body caught httpx.HTTPError, the superclass of both, and returned None. So a ConnectError became a withhold before tenacity could see it. Measured against a transport that refuses every time: one upstream request, not three — and attempt_floor, the knob @retry-attempt-floor exists so a deployment can raise, moved nothing at all.

GwasCatalogClient never translated the leg the retry gives back. _get re-raised transport errors bare so tenacity could match them, which is correct, and with reraise=True nothing caught the last one once the attempts were spent — so associations_for raised a raw httpx.ConnectError at a caller told to expect GwasError, while the body's own docstring said "Both legs are translated". Measured: the httpx type, after three attempts.

The guard is static and walks the package, because the defect is a shape. Neither instance is visible in a passing test or in review — the decorator and the except are forty lines apart and each is individually correct. test_retry_is_reachable.py walks every @retry-decorated function in the package and refuses any whose body catches an ancestor of a type its own decorator retries. A handler whose entire body is a bare raise is exempt by construction, since it swallows nothing.

It walks the package rather than the roster on purpose. test_client_exception_contract.py could not have caught either one: literature.CrossrefClient and gwas.GwasCatalogClient both sat in that file's named exempt set, and a guard that iterates a roster inherits the roster's exemptions — the RM101 blind spot, one file over. GWAS's exemption is now removed rather than re-argued, and the reason it was wrong is worth keeping: it argued from the type that is raised (GwasError is both the client's and the pass's, so no cross-module mismatch), which cannot see a leg raising a different one.

gwas joins FOUR_OH_FOUR_IS_AN_ANSWER, and for its own reason rather than OLS4's: the Catalog holds only variants carrying a published association, so a 404 is absent and associations_for turns it into the empty answer [] — the third outcome that has to stay distinct from could-not-ask.

RM209 — the publish half walked the root-file registry and the pull half did not

Severity high · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: one hand-kept tuple replaced by the registry it copies; no schema change) · Owner enricher · Motivating case the 2026-09-11 blind re-derivation round — docs/audit/ENRICHER_FROM_CODE.md D8

RM198 added avi_knots.parquet to locations.SNAPSHOT_ROOT_FILENAMES and only one side noticed. upload.py walks that tuple; download._provision_snapshot iterated (RELEASE_FILENAME, SNAPSHOT_LICENSE_FILENAME) inline. So the publisher sent the file and the puller never asked for it.

The consequence is a lane that cannot be used. The AVI lane stores no PHRED — it is an exact within-corpus rank, so the 466 KB knot table is what reconstructs it, and alphagenome check refuses a snapshot without that file. cache pull alphagenome_avi therefore produced a snapshot whose scores nobody can rank, which is the one thing RM198 existed to prevent.

Two docstrings said the opposite in as many words, which is the part worth keeping: "That file travels because SNAPSHOT_ROOT_FILENAMES names it, not because this function does", and "_provision_snapshot fetches the root files from SNAPSHOT_ROOT_FILENAMES for every lane, so this needs no special case". Both were written when the registry was introduced and describe the design rather than the code — a registry with a hand-kept copy of itself beside it (@registry-completeness), where the copy is the thing that runs.

The test asserts the equality, not the file. What the provisioner asks the remote for is compared as a set against the tuple, so a registry that grows by one is covered without anybody remembering. The named assertion for avi_knots.parquet sits beside it as the second test, because that filename is what a reader greps after alphagenome check refuses. Absence stays non-fatal and .part staging is asserted: a repo publishing none of the three root files still provisions, and leaves no truncated stub.

RM206 — LookupClients had three lazy-build semantics and the call site could not tell which

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: one method and one lock on LookupClients, CLIENT_FIELDS derived, nine legs rewritten onto it, five public calls closing the bundle they build; no schema change) · Owner enricher · Motivating case S92 (just-dna-registry, in CONSUMER_SUGGESTIONS_HISTORY.md), hosting the five lookup_* surfaces behind one process-wide bundle

What it reproduced. The bundle's docstring says to hold one because a fresh client per question discards the pacing state — and six of the eight legs did exactly that whenever their field was unset: clients.x or X(), closed in a finally. Two legs (ensembl, grch37) assigned back onto the caller's bundle instead. The consumer filled six of eight fields and had an unpaced-egress bug on precisely the leg whose absence mattered, pmc_idconv, which read identically at the call site to grch37, whose absence did not. Their fix was to fill all eight and stop reasoning about it, which is the right consumer move and the wrong thing to require.

One path, and the lock that makes the assign-back a property a caller can see. ensure(name, factory) reads the field under the bundle's own lock, builds on None, stores, returns. The name is checked against CLIENT_FIELDS first, because a plain dataclass accepts setattr on any spelling and a typo would build a client per call forever while looking exactly like the lazy path. close() walks the same tuple, derived from fields() rather than the hand-kept eight it was (@registry-completeness). The consumer's other candidate — one constructor that fills every field — was not taken: it makes eight connections for a one-shot hint trait, and the property wanted is uniform, not eager.

Ownership follows construction. With the legs no longer closing what they build, a bundle a lookup_* call makes for itself (clients=None) would leak every connection it opened; each of the five now closes its own in a finally, and an injected bundle is never closed by a call. Pinned by a monkeypatched client that counts its closes across both shapes.

The CPIC half is the consumer's, and said so. pgx_draft.draft_gene takes client=, so a host shares pacing by holding one CpicClient and passing it; a cpic field on a bundle nothing in lookup reads would be a promise the module cannot keep, and their snapshot-only answer is a fine one.

RM205 — the lookup surface put absolute snapshot paths in its payload

Severity low · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: one field on VariantHint, two label substitutions, three recording sites; no schema change) · Owner enricher · Motivating case S93 (just-dna-registry, in CONSUMER_SUGGESTIONS_HISTORY.md), exposing lookup_variant over HTTP from a box whose layout is not the caller's business

What it reproduced. _lookup_from_cache wrote str(reference) into hint.checked and interpolated the same path into the unreadable finding, while the live leg wrote ensembl-rest into the same set. A host therefore scrubbed: every known snapshot path mapped back to its lane name, inside finding prose too — and, as the consumer said, that audit has to be repeated every time a field is added and silently stops being complete.

The shape, taken as proposed. The set was already half right — ensembl-rest is exactly the kind of member it wants — so the cache case now writes the link's label (ensembl, clinvar), the finding reads {label} snapshot unreadable: …, and the path moves to a structured field, snapshots, keyed by the same labels and filled for every snapshot the lookup opened or tried to open, the clin_sig and PubMind legs included. That makes the payload safe by construction: one field carries a path, a host drops it, nothing else is audited.

A behaviour change on a read field, and why it is not a break. A reader that matched the old str(path) members of checked now sees lane names. checked is documented as what was consulted and the consumer who reads it asked for this; a path in it was the defect, and the value that replaced it is the one ensembl-rest already set the pattern for. The path is not lost — it moved.

What stays. _brief(exc) is duckdb's first line and may name the file; that is upstream's sentence, kept as evidence rather than rewritten, and a host that scrubs has one predictable place left to look rather than an audit.

RM204 — cache status was CLI-only, so every consumer re-derived the projection it renders

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: one dataclass and one function in caches, cache status rendering from it, one new rendered state; no schema change) · Owner enricher · Motivating case S91 (just-dna-registry, in CONSUMER_SUGGESTIONS_HISTORY.md), serving GET /caches from a box holding some of the snapshots

What it reproduced. RM176 made the registry a walked list and left its status half as the loop inside cli.cache_status_(): resolve(), release_label(), print. A consumer serving the same answer over HTTP wrote the loop again, and had already been bitten at exactly this spot — their two projections drifted by seven lanes. Two projections of one registry is the shape RM176 exists to end, and this one was ours.

The third state, and why the name is occupied rather than the consumer's partial. A directory that exists, is non-empty and holds no snapshot is the target prepare_lane refuses to build over (provisioning never deletes), and cache status rendered it as absent — an instruction to run a pull that was going to decline. The consumer renders it partial. Not taken, because the state is defined by a fact (holds no snapshot) and not by a cause: a build that failed after its downloads is partial, a foreign parquet is not, a stray .part beside a deleted payload is neither, and prepare refuses all three alike. occupied names what the operator has to do — move it aside — without guessing what put it there. LANE_STATES is a closed set of three, so a renderer can walk it.

looked_in is on the record because status and prepare do not read the same directory. resolve() reads the lane's env_var first; prepare's refusal is about default_dir(). An override pointing at a junk directory reads occupied here while prepare would build into an empty default that the override then hides, so the status names which directory its verdict is about rather than leaving the operator to guess between two.

The two rendered lines that existed are byte-identical (@warning-text-is-api: test_pubmind_cli greps one of them, and an operator's script may grep either), and the present-and-unreadable release.json case moved from an inline if in the CLI to a field, release_unreadable, so a consumer gets it without re-deriving that check too.

RM203 — PacingGate could not report what it spent

Severity low · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-enricher only: one integer field on PacingGate, one increment under the existing lock; no schema change) · Owner enricher · Motivating case S95 (just-dna-registry, in CONSUMER_SUGGESTIONS_HISTORY.md), building a caching proxy that meters egress per upstream

What it reproduced. The gate is the one object every egressing client waits on, and it recorded nothing but last. A host wanting to charge a caller for the upstream calls its request actually made had to charge by the request's shape instead — an upper bound it had to label as one, and one that bills for a call a snapshot hit never made.

The counter, and what one increment means. spent is bumped inside the slot lock, so it is exact under the thread sharing S15 made a contract. Its unit was checked rather than assumed: gnomad._post and eutils._request call wait() inside their @retry-decorated body, so one admission is one upstream attempt, and a 429 retried three times counts three. That is the honest number for metering — the attempts are what the upstream saw.

Refused: a waited total. Not asked for, and the sleep happens outside the lock by design (the lock covers the bookkeeping, not the wait), so a seconds-slept total would need the lock re-taken after the sleep or a planned wait recorded before it. Neither is worth a second number nobody asked for; a host that wants it can difference two clock readings around the call.

RM201 — a declared correction said what a release did, never which modules it did it to

Severity medium · Status ✅ shipped 2026-09-11 in the uncut 0.7.0 (just-dna-format only: one optional field on DeclaredChange, one predicate, one filter on RecompileAnswer, three declarations filled; no parquet, manifest or vocabulary change) · Owner format · Motivating case S90 (just-dna-registry, in CONSUMER_SUGGESTIONS_HISTORY.md), found adopting needs_recompile for a re-publish sweep

What it reproduced. DeclaredChange had five fields and none of them stated reach. Over 0.6.6 → 0.7.0 the corrections are gene_validity.classifications (RM108) and gene_metrics.parquet plus gene_metrics.signature (RM110); each detail names the block it reaches in prose, and the model could not, so a sweep routing on kind == "correction" minted a fresh immutable PATCH for every module in a catalogue to repair a value most of them never carried. The consumer's two pre-checks were right too: unmeasured is a different axis (a module the sweep could not compare, not a change that applies to a subset), and AUTHORED_ROW_DERIVED_FIELDS cannot help because a compiled parquet is nothing a consumer can recompute locally.

Why the consumer was right to refuse the workaround. target is spelled three ways — a dotted manifest path, a parquet filename, file:column — and reading its first segment as "the block a module must carry" works until a fourth spelling arrives, silently. That is a consumer re-deriving a rule from a field's spelling, and the rule is ours to state.

The shape, and the two candidates refused. The consumer proposed requires_block: str | None with None meaning every module. Refused on the algebra: None is never a definite answer here, and the case that proves it is already in the table — RM121's stats.genes correction reached a real subset (modules whose lead table named no gene while another table did) that presence cannot spell, because every module carries the field. That correction must be able to say unstated, and a consumer must keep it; making None mean every module would make the honest answer and the definite one the same value. So requires: tuple[str, ...] | None — a conjunction of dotted manifest paths, spelled as manifest_fields spells them, () for every module, None for unstated. A prose applies_when beside RosterEntry.condition was the second candidate and was not taken: the roster's condition is checkable because compilation.dropped_rows shipped, and a prose-only reach here would be readable by an operator and filterable by nobody, which is the state the report describes.

A necessary condition, said out loud. ("gene_metrics",) over-approximates RM110's true reach — the snapshot route, @constraint-two-releases — in the safe direction, so reaches() is documented asymmetrically: False is the certain answer and the only one acted on, True is not excluded by what the record states, None is unstated. declared_for drops only False, the Kleene fold, because the two mistakes cost differently — a change kept needlessly is one wasted version number, bounded by the self-interval; a change dropped wrongly is a module serving a value we have said is wrong.

Forced rather than defaulted. The record's own rule is that the measurement forces the declaration; this field gets the same treatment one level down: a test asserts, as an equality, that the corrections with an unstated reach are exactly RM121's pair, so a correction added without deciding its reach fails the suite instead of reading as unstated. Every required path is walked against the manifest models by the test helper manifest_fields already uses, not a second walker. The grammar's boundary is on the field: presence of a path is all it says, and a value or membership predicate would be a separate field, audited per Principle 5 rather than grown onto this one.

RM202 — a publish_repo that nothing could reach, and the guard that was missing on one side

Severity medium · Status ✅ shipped 2026-09-11 (just-dna-enricher only: one CLI command, one lane field, one guard) · Owner enricher · Motivating case the maintainer asked for the publish command and there wasn't one

What was wrong. RM198 wired alphagenome_avi's publish_repo, asserted the field was set, and shipped. cache rebuild --publish walks lanes that have a rebuild adapter — which is every publishable lane but this one, because its source sits behind an eligibility gate and there is nothing for an unattended rebuild to fetch. So the lane advertised a repo that no command could send anything to, and the only generic publisher was clinvar publish, which is the wrong name to hand an operator for AlphaGenome.

Why the tests passed. They asserted the registry's data — lane.publish_repo is not None, lane.unpublished is None — and the one publish test called plan_reference_snapshot directly, bypassing the CLI. Nothing invoked a command. @registry-completeness is usually about a list that falls behind the set it lists; this is its neighbour: a field can be set correctly and mean nothing, if no path acts on it.

The guard already existed on the other side, which is the sharp part. test_every_build_command_the_registry_names_is_one_the_cli_answers_to walks the real Typer tree for every lane's build_command, and it exists because cache status once printed two commands that do not exist. The publish side had no equivalent, so the same class of defect had one door open.

What shipped. just-dna-enricher alphagenome publish, a CacheLane.publish_command field, and test_every_publishable_lane_can_actually_be_published — which asserts the biconditional: a lane with a publish_repo is reachable by a rebuild adapter or by its own publish command, exactly one of the two, and if it names a command that command answers --help in the real CLI. A lane that names a publish command with no repo fails too.

Measured while scoping it: of nine lanes with a publish_repo, eight ride cache rebuild --publish and alphagenome_avi was the only unreachable one. The hole was exactly one lane wide, which is why nobody had met it.

RM199 — the description is the last thing a publish sends

Severity medium · Status ✅ shipped 2026-09-10 (just-dna-enricher only: a size threshold, a two-phase publish, one registry reordered) · Owner enricher · Motivating case the AVI lane is 32 GB and upload_folder is a single atomic commit with no resumption

Revised the same day it shipped, by a deprecation warning in a real publish. The size branch below is gone: huggingface_hub 1.x makes upload_folder multi-commit itself and deprecates upload_large_folder, which now emits a FutureWarning naming upload_folder as the replacement. So the threshold, its two constants and the whole large path are removed, and one upload_folder carries every payload.

Two consequences worth keeping. The RM186 collision dissolved rather than being solved — upload_folder takes delete_patterns, so a declared retirement rides the payload call again and the refusal this function used to raise is deleted; a guard now asserts the retirement is on the payload commit at 6 GB as well as at 1 KB, since a small-snapshot test would not have exercised the branch that used to exist. And the one-commit guarantee is upstream's business now: a large upload is several commits either way, so it holds for payloads that fit in one and is the Hub's to keep for those that do not. That is a weaker promise honestly stated rather than a strong one quietly broken.

The lesson is the ordinary one and it still cost a revision: heed terminal warnings, deprecations especially. This one appeared the first time an operator ran the command against a real repo, and nothing in the test suite would ever have raised it — the tests mock HfApi, so a deprecated method on a MagicMock warns about nothing.

Two changes, and only one of them is about size.

release.json goes last, on every path. It is what a puller reads to learn which release it holds, so a publish that lands the description and then fails leaves a snapshot that reads as provisioned and is not — @a-publish-may-not-orphan-the-bytes-it-stops-describing reached from the other direction. The payload is one commit and the description is a second, which costs one extra commit on a path that was already going to be several.

The ordering lives in SNAPSHOT_ROOT_FILENAMES, not in the publisher. Putting RELEASE_FILENAME last in the tuple means the plan a --dry-run prints is already in the order the upload sends, so the two cannot disagree. That is the same lesson as @publisher-allowlist-derived one turn further on: the promise and the act are one list.

Above 5 GB the payload goes through upload_large_folder. Not a performance dial — an atomicity one. upload_folder is a single commit with no resumption, which is right for a snapshot measured in megabytes and wrong for 32 GB, where a transport failure at 30 GB starts over. The large uploader chunks, retries per file and resumes, at the cost of not being atomic, which is exactly why the threshold exists rather than always using it. Every lane but AVI is orders of magnitude below it.

A collision between two rules, refused rather than resolved silently. RM186 promises that a declared retirement rides in the same commit as the file replacing it, so a reader never sees the repo with neither or both. upload_large_folder takes no delete_patterns and is inherently multi-commit, so that guarantee cannot be honoured on the large path. The publish raises, naming both rules, rather than quietly doing the deletion in a separate commit and leaving exactly the window RM186 exists to close. No lane is in that state today; the refusal is there for the one that will be.

A second copy of the root-file bug, fixed in passing. plan_reference_snapshot has two branches, and only the parquet one had been moved onto the registry by RM198 — the payload-only branch (STRchive, ACMG) still carried its own hardcoded pair, so a lane of that shape gaining a root file would have dropped it exactly the way the parquet branch dropped LICENSE.txt. Both walk the registry now.

What the tests pin. That the union of the two commits equals the plan, because splitting an upload may not drop a file; that release.json is in the second call and not the first; that a sub-threshold snapshot still goes out unchanged; that the large path is chosen by measuring the payload rather than the directory, so a description cannot tip the decision; and that a retirement on the large path refuses before either uploader is called.

RM197 — the ALT column that a proof made unnecessary

Severity low · Status ✅ shipped 2026-09-10 (just-dna-enricher only: the lane's parquet schema, a widening step, a public to_long, five tests; no consumer-visible join change) · Owner maintainer · Motivating case the lane is published to HuggingFace now (RM198), so transfer size binds where local disk never did

What shipped. One row per position with three ALT-score columns, and no stored alt: chrom, pos, ref, alt0, alt1, alt2. 3.371 B/row against 3.882 long — 29.7 GB rather than 34.2, a 13% saving that is simply not writing pos three times. pos costs 1.249 B/row even perfectly delta-encoded, so it is the whole of the difference.

The column disappears because of a proof, not an assumption. Which base each column means is {A,C,G,T} − ref ascending — a function of ref alone, so nothing has to travel beside the data. That is only well-defined if every locus really carries all three, which was measured over the whole corpus before anything changed: across 24 contigs and 8,812,917,339 rows, rows == 3 × distinct positions exactly (2,937,639,113 of them), pos sorted, alt strictly ascending within a position, and no alt equal to ref — so three distinct non-ref bases must be all three of them. Zero violations.

Two earlier attempts at that check were OOM-killed: group_by(pos).agg(...) and n_unique both have to hold billions of keys. Counting boundaries in a sorted column holds nothing, and did the whole genome in 178 seconds. The measurement technique is the transferable part.

It is not a schema break, and that is the point. to_long() recovers (chrom, pos, ref, alt, score) rows from the stored ones with no lookup table, so alphagenome_check's join is unchanged — it converts the handful of rows it already filtered to. The test proves the round trip against the published source text, not against another derivation of the same parquet.

A proof taken once is a proof about the artifact that existed then, so the builder re-runs it on every build and refuses a locus that breaks it. Padding a missing ALT with a null would silently redefine what alt1 refers to at that locus — a table that reads fine and answers wrongly, which is the failure mode this whole round kept meeting.

The defect the genome-wide build found, and every test in the file passed while it was there. _stream_lines yields whole lines; a locus is three lines. So a chunk boundary falls inside a position roughly once per chunk, _widen saw two ALTs where the file has three, and the build refused at chr1:1196920 — a locus the source carries in full. The docstring on _widen asserted the opposite ("a chunk boundary cannot split a locus"), which is the same shape as everything else this round found: a plausible claim nobody had checked.

_build_contig now carries the trailing partial locus into the next chunk and emits the final one after the loop — without that second half every contig would silently lose its last position. The fix belongs there rather than in _widen, which cannot tell a truncated locus from a malformed one and should not guess.

The fixture could not see it. The committed slice is 4 MB and the chunk size is 64 MB, so every test built in one chunk. The regression test builds the same slice at 64 KB — hundreds of split loci — and asserts the table, the knot table and the row counts are identical to the single-chunk build, including that the contig's final position is still present. Demonstrated failing on the unfixed code before being kept: it refuses at chr22:20000624. An assertion that the build merely succeeds would have been satisfied by dropping the partial rows.

What was measured and rejected. One column per base with the ref slot null — the obvious alternative — is worse: 3.677 B/row, because the nulls cost more than dropping alt saves. And setting row_group_size explicitly remains worse at every value tried; the default adaptive sizing is what responds to the data.

RM198 — the lane that publishes a file the publisher did not know how to carry

Severity medium · Status ✅ shipped 2026-09-10 (just-dna-enricher only: a layout registry, a provisioner, a repo id, three lane fields) · Owner enricher · Motivating case the AVI lane became publishable when RM195 closed, and wiring it found the publisher would have dropped the one file that makes the snapshot usable

What it wires. ensure_alphagenome_avi_snapshot, DEFAULT_ALPHAGENOME_AVI_REPO_ID, and the lane's ensure / publish_repo, with unpublished removed — the roster asserts that biconditional, so a lane cannot both publish and excuse itself. cache status, cache pull, prepare and upload all pick it up from the registry with no per-lane branch, which is what RM176's registry was for.

The lane is still the odd one out on the build half. rebuild stays None with its unbuilt reason intact: this tier cannot fetch the 88.5 GB source, because the eligibility clause bars classes of holder outright. So it is pullable without being buildable — an operator who may not download the artifact can still provision the re-encoded snapshot, which is the entire point of publishing it.

The defect it found, and it is the third of its exact shape. plan_reference_snapshot collected data/*.parquet, the sidecar directories, and then a hardcoded pair — release.json and LICENSE.txt. avi_knots.parquet is a root-level sibling of data/: one small parquet, not a directory of them. It would have been dropped silently, and the published snapshot would have looked complete — every score present, release.json valid — while nothing on the other side could reconstruct a PHRED, because the artifact deliberately does not store one. alphagenome check refuses such a snapshot outright, so the failure would have surfaced far from its cause.

That pair was itself a repair: LICENSE.txt is only in it because publishing a share-alike snapshot had already gone out without the terms it exists to carry (@publisher-allowlist-derived). So the names moved to locations.SNAPSHOT_ROOT_FILENAMES and the publisher walks them — the same move CACHE_LANES is, one layer down. A fourth such file added to a lane and not to the registry now fails a test rather than a publish.

What the test asserts is the walk over a real built snapshot, not the constant against itself: the plan for the fixture build must contain the knot table, and every root file actually on disk must be carried. A test comparing SNAPSHOT_ROOT_FILENAMES to a literal would have passed while the publisher ignored it.

RM196 — the repository stopped carrying somebody else's source and started carrying a pin

Severity medium · Status ✅ shipped 2026-09-10 (just-dna-enricher only: a build-backend change for that package, a resolver, a build hook, five files removed from docs/vendor/) · Owner maintainer · Motivating case pip install just-dna-enricher[atlas] installed two packages and then could not import the client

What it was. RM192 vendored upstream's .proto sources and generated the bindings into a git-ignored tree. Neither docs/ nor generated/ is in a wheel, so an installed package had no sources to generate from and no bindings to import: the extra worked from a checkout and nowhere else. The client's import was guarded and named the command, which made the failure legible rather than absent, but it was still a broken install path.

What was measured before choosing. Three things, and two of them shrank the problem:

  • The build backend is declared per package. The ROADMAP entry said changing it "touches how all three packages are built"; that was wrong. just-dna-format and just-dna-compiler stay on uv_build and only the tier that runs protoc moved.
  • hatch-protobuf cannot do this job, checked rather than assumed: its options are generate_grpc, generate_pyi, generators, import_site_packages, library_paths, output_path and proto_paths, and none rewrites an import. The rewrite is the entire safety property — without it the generated package is literally named alphagenome and shadows the real wheel — so the plugin would have produced exactly the artifact test_the_generated_bindings_do_not_shadow_the_upstream_package exists to prevent.
  • A custom hatchling hook does, in about thirty lines, which is what upstream AlphaGenome itself does for the same reason.

What shipped, and it is not any of the three options the entry listed. The maintainer's shape: the repository carries neither the sources nor the bindings — it carries the pin. atlas_protos.fetch_protos() downloads the five files from google-deepmind/alphagenome at a pinned commit and verifies each against a recorded sha256; hatch_build.py runs that and protoc at build time; and both trees are git-ignored and deliberately not build-ignored, so an sdist and a wheel carry the files while the repository's history does not.

Why a commit id and a digest. A commit id proves what git had; a digest proves what arrived. The fetch crosses HTTPS to a CDN, and a pin is worth exactly what something checks it against — the same reason SourceRow.license_sha256 exists. A file already on disk and matching is left alone, so the build is offline after the first run; a file that does not match is re-fetched rather than trusted, because the only thing worse than no pin is a pin nobody acts on.

Three defects the real build found, none of which a plan would have:

  • The Apache-2.0 LICENSE is at upstream's repository root, not beside the protos. A single-directory assumption 404s on it, so the pin maps each file to its own upstream path.
  • Hatchling globs LICEN[CS]E* for the package's own License-File metadata, so a fetched file called LICENSE was both added to the archive twice and advertised as just-dna-enricher's licence — which it is not. It ships as alphagenome_apache-2.0.txt, outside the glob.
  • force_include duplicated every file, because the trees sit inside the declared package and hatchling already walks it. artifacts is the mechanism for build-time output that lives in the package tree and is deliberately absent from version control.

Verified from a clean venv, not from the checkout that built it: the wheel installs with grpcio and protobuf alone, the bindings import, the service config and upstream's notice are present, and importlib.util.find_spec("alphagenome") is None — no shadowing.

What docs/vendor/ keeps. The four terms documents and the download page, and the README there now says why: those are evidence about licensing, which is exactly the kind of file that should be frozen in the repository rather than re-fetched. Upstream's source code is the opposite kind.

RM195 — the most consequential claim about a source, resting on a page nobody had saved

Severity medium · Status ✅ resolved 2026-09-10 (just-dna-enricher only: one SourceTerms field, one pinned vendor document, two tests) · Owner maintainer · Motivating case RM191 needed to state whether AVI may be used commercially, and no document in the repository said

What it was. The AlphaGenome Services Additional Terms define a "Permissive Use Downloadable Artifact" class and grant it commercial use outright — then delegate membership of that class to the download section of the Atlas website. Four terms documents were pinned in docs/vendor/ and none of them named a single artifact. The page is a sign-in-gated single-page app that serves 185 KB of navigation chrome to curl. So the claim "AVI may be sold" — the most consequential single fact about this source, and one that would sit inside a signed module's attribution ledger — rested on one reading of one page the repository could not check.

What shipped in the meantime, and why it was not a placeholder. commercial_use=None. Unknown is a value, None is never False, and @no-named-licence already settles what follows: unknown commercial terms warn rather than gate. So a module carrying AVI compiled under declared_use=commercial with a warning, rather than either refusing or silently asserting a permission nobody had established.

What resolved it. The maintainer saved the page from a signed-in browser. It carries its content as embedded JSON rather than markup, which is why fetching it had failed and why the extraction beside it is the greppable half:

"Permissive Use Downloadable artifacts for commercial and non-commercial use" — AVI SNV scores, avi_scores_snvs_tabix.zip, 88.5 GB

"Downloadable artifacts for non-commercial use only" — AlphaGenome SNV merged splicing scores (20.6 GB), AVI SNV feature importance scores (283.9 GB)

It confirmed the probe's reading rather than overturning it, which is worth stating plainly: four of that document's claims had already been refuted by measurement, so the prior was not good. It is also independent confirmation of why alphagenome_avi_build refuses the other two artifacts by name — they really are a different licence class.

commercial_use=True. The page is pinned as docs/vendor/alphagenome_download_page.html.gz (1.1 MB gzipped, from 7.1 MB — the complete document travels rather than an excerpt, and it stays under the Git LFS threshold) with alphagenome_download_page.txt beside it carrying the extraction and the uncompressed sha256. The test asserts against those bytes, not against a constant: if the file is dropped, or upstream reclassifies and it is re-saved, the test fails rather than going on asserting yesterday's permission.

redistribution=True, and it is the one value on this row that rests on judgement. The page classifies use, not sharing. Prohibition 1 separately bars passing Output to a commercial organization "aside from indirectly via a scientific publication, open source release or to support journalism", and the maintainer read an openly published snapshot as an open source release within that carve-out on 2026-09-10. No document in docs/vendor/ says so in as many words, which is why this entry names the reading as a reading.

What makes it defensible in practice rather than only in principle is restriction 3b, which this lane already honours in fact: a published snapshot carries the "Use restrictions" section as LICENSE.txt beside the data, so a puller receives the terms with the bytes rather than a link to them, and license_sha256 pins which version they got.

The three axes now rest on three different kinds of ground, and the row cannot show that — a consumer reading sources.csv sees three booleans. commercial_use=True and share_alike=False are documented; redistribution=True is decided. test_the_three_permission_axes_each_rest_on_a_different_kind_of_ground is where that distinction is written down, so anyone revisiting the reading knows which of the three to revisit. Wiring the lane into cache pull / upload is RM198.

RM193 — the three questions a nine-billion-row file on your own disk cannot answer

Severity medium · Status ✅ shipped 2026-09-10 in the uncut 0.7.0 (just-dna-enricher plus one new VALID_VERIFICATION_CHECKS member in just-dna-format — additive, minor-legal under P3/P8; no column, no table, no manifest field) · Owner enricher · Motivating case PROPOSAL_0_7_PT4

What shipped. alphagenome_check.py and just-dna-enricher alphagenome check <spec>, plus the variant_impact_agreement check member. Reports, never repairs (@enrichment-is-validation).

Most of it never touches the network, and that is the design rather than a fallback. Without --threshold there is no question RM191's snapshot cannot answer, so the pass is entirely offline. With one, the knot table says — from 466 KB, before a single request — which variants sit inside a PHRED interval spanning the cut, and only those are asked about. threshold_is_safe() answers the prior question ("can I cut here at all?") for the same 466 KB, and genome-wide the answer is yes at every integer threshold from 1 to 50 except 3.

The refusal is the item's spine. Rebuilding the PHRED column by RPC is 272 days and ~92 M requests at the measured rate, and prohibition 3 governs the result, so a check that could start down that road has to stop. refinement_cap refuses before any request is spent, and the message names the knot table — because what the caller actually wants, which rows are affected and by how much, is already on their disk. test_an_unbounded_refinement_is_refused_and_names_the_cheaper_answer asserts the stub's call log is empty, not merely that an exception was raised.

Four no-answer reasons, kept apart (@answered-is-not-absent, @unreachable-not-absent): ref_mismatch (the Atlas validated REF against GRCh38 and named the real base, which @va-omits-ref says only this tier can discover), not_scored (an indel, or a quantile saturated off the top of the float32 scale — the artifact reaches PHRED 89.451 where the API caps at 72.247), unreachable (asked, no answer — and deliberately no finding, since a bad minute at Google is not a claim about the caller's data), and offline/no_client (nobody asked). A fifth, absent_from_snapshot, is the local artifact's own silence. None of them is a zero, which matters at a scale where the corpus holds 672,931 genuine ones.

It emits its own check member rather than a second reference_allele. The Atlas answers the REF question too, but that check belongs to enrich and compares against the reference sequence; letting an Atlas outage write a skip against it would make one registry's availability speak for another's question (@one-registrys-outage-may-not-speak-for-another). Two sources, two checks, side by side.

A silent-wrong-answer bug the tests caught, and it is the kind worth recording. VariantRow normalizes chrom through vrs.normalize_chrom and stores 22; AlphaGenome ships UCSC-style chr22 and indexes it that way. Joining the module's spelling straight onto the snapshot matched nothing — and produced no error, just every variant reported absent_from_snapshot, which reads exactly like an artifact that does not cover them. Found only because a test asserted a positive count rather than the absence of a crash. artifact_contig() converts at the boundary, one direction, and a test asserts the two spellings give the same answer rather than that neither is empty.

The [atlas] extra stays optional, and a test proves it in a subprocess. atlas_client imports grpc, so a module-level import anywhere on the CLI's import graph would make RM192's 19 MB extra a requirement of the whole tier — undoing the thing RM192 measured its way out of. Both cli.py and alphagenome_check.py guard it, the latter binding a never-raised class rather than None so the except arms stay well-formed. Checked with grpc blocked at sys.meta_path in a child process, because in this environment the extra is installed and an in-process assertion would pass for the wrong reason — the same trap test_imports_stay_within_the_declared_floor avoids with an AST walk.

What it does not do. No new stored column from any of the Atlas's other 21 scorers. They are ordinary Output — non-commercial, notice-bearing — so they may enter as findings under declared_use=non_commercial and never as values, and the existing data-driven gate needs no new axis for that.

RM191 — nine billion scores, and the column that is a function of another column

Severity medium · Status ✅ shipped 2026-09-10 in the uncut 0.7.0 (just-dna-enricher only: a new builder module, a new cache lane, a new CLI command, a new SourceTerms entry; no model, no authored column, no manifest field) · Owner enricher · Motivating case PROPOSAL_0_7_PT4, against ALPHAGENOME_ATLAS.md §§ 1.4, 4.4–4.9

What shipped. alphagenome_avi_build.py and just-dna-enricher alphagenome build --input, writing <out>/data/alphagenome_avi-<contig>.parquet + avi_knots.parquet + release.json + LICENSE.txt, and a fifteenth CACHE_LANES entry. --input is required and there is no default URL: the artifact is 88.5 GB behind a sign-in whose eligibility clause bars classes of holder outright, so acquisition is the operator's act under their own acceptance (@acquisition-gate-is-not-a-read-gate).

PHRED is not stored, and the 466 KB that replace it are the item. Measured over all 8,812,917,339 rows, PHRED ≥ p keeps 10^(-p/10) of the corpus to four significant figures across four decades — it is an exact within-corpus rank, a function of raw_score, and 24.7 GB of it. The knot table carries the curve instead, and it carries the interval rather than a point: the artifact prints raw_score to four significant digits and PHRED to six, so one printed score can span many ranks. Publishing a midpoint would turn a measurable ambiguity into an invisible one. That interval is what makes threshold safety decidable — a threshold is unsafe iff it lands inside a knot's span, checkable from 466 KB without reading a data row. Genome-wide, exactly one knot straddles any integer threshold from 1 to 50: 0.00076, 676,356 rows, PHRED 2.99961 to 3.00027. Every other threshold is decided.

Two measurements corrected the proposal, and both are recorded rather than worked around.

  • Size — and the correction is the finding, not the number. The first build measured 4.878 B/row → 43.0 GB and this entry said so, adding that the proposal's 34.4 GB "reproduces in neither layout". That was wrong, and it was wrong because the measuring instrument was the defect. The builder assembled each contig with scan_parquet(...).sink_parquet(...), which fragments the result into one arrow chunk per morsel — 1,432 for chr22 — and parquet writes at least one row group per chunk, inside each of which a sorted pos has almost no run left to delta-encode. Varying nothing but the chunk count on the same frame: 1–64 chunks 3.871 B/row, 128 chunks 3.904, 1,432 chunks 4.892; pos alone goes 1.249 → 2.067. Reproduced independently on a different slice, where the cliff sat between 512 and 1,432 — around twenty-odd thousand rows per chunk both times, which is why the cap ships as a rows-per-chunk floor as well as a chunk count. The shipped builder assembles in bounded groups and measures 3.882 B/row → 34.2 GB, so the proposal's figure was right all along.

Two things fell out of it. row_group_size set explicitly is worse at every value tried (4.7–5.1 B/row) — the default adaptive sizing is what responds to the data, so the obvious tuning knob is the wrong one. And a wide-by-position layout measures ~29.7 GB against ~34.2, a real but much smaller gap than the first (bugged) comparison implied; RM197 carries that as an open question rather than as a 31% saving over a number that was never real. - Losslessness is about the decimal, not about a float round-trip. Int32×10⁵ is exact for a value printed to five decimals, and the builder checks it — _scaled_scores refuses a value that does not land on the grid rather than rounding it, so the guarantee holds over every row written rather than over the 900,003-row slice it was measured on. But recovering a float with raw_score_e5 / 1e5 disagrees with float(printed) on 53% of rows: the division rounds a second time and lands one ulp off. The test compares in Decimal, and both the module docstring and the test say why — asserting it the obvious way would have weakened the claim to whatever a tolerance admitted.

What the tests pin, all against a committed 1.2 MB slice of the real artifact (assets/alphagenome/avi_chr22_slice.tsv.gz) with expected values re-derived from its own text: the decimal round-trip; the refusal when a score carries more precision than the scale; that PHRED is absent from the parquet and present in the knots; that sum(n) over knots equals the rows written and every stored score has a knot; the threshold-safety property at seven thresholds with zero misclassifications; and that the one straddling knot really has rows on both sides of 3.0 — without which the safety test would be @tautology-zero, which is why the slice was cut around that locus rather than anywhere.

Built genome-wide, and every number cross-checks against something measured independently. The 88.5 GB artifact re-encodes in 85 minutes on twelve tabix streams to 34,291,319,173 bytes over 24 parquets — 3.891 B/row:

built here measured elsewhere
rows 8,812,917,339 the probe's corpus size, § 4.4
knots 41,474 41,474 — the sibling session's independently-built table
negative raw_score 4,344,533,049 (49.30%) 49.30%, § 1.4
genuine zeros 672,931 672,931, § 1.4
straddling knots 1 (0.00076, n=676,356, PHRED 2.99961–3.00027) 1, and only at threshold 3

The knot table was compared against docs/probes/alphagenome_knots/avi_knots.parquet — built by a different session, from a different pass over the same bytes — knot by knot rather than by count: zero raw values in one and not the other, zero n disagreements, zero phred_lo disagreements. source_sha256 is 46434eab0ddc73ef…, and release.json pins the artifact's own 2026-08-27 stamp, which is what § 2.7c resolves the applicable terms against.

Two defects the real artifact found that no fixture could. pl.len() is UInt32, so summing the per-contig knot tables wrapped 8,812,917,339 to 222,982,747 — exactly − 2·2³² — and only the reconciliation guard saw it, after 65 minutes of building. And read_local_scores joined before filtering, which on 34 GB is not slow but fatal: the first smoke test was killed by the OOM killer on a twelve-variant module. It now selects parquets by contig from the filename and filters pos inside the scan, where row-group statistics skip almost everything; the same query takes 4 seconds. A third, smaller: subjects counted decided + unanswered and a straddling variant is legitimately in both, so a three-variant module published four.

"No threshold" was the right default, and the evidence arrived after the decision. The artifact ships the whole corpus with the sign intact, on the argument that a cut is a consumer's slice. The ClinVar join measured beside this round (probe § 4.10, 21 of 24 contigs) shows a threshold is a real triage rather than only a size dial — PHRED ≥ 20 keeps 97.63% of pathogenic variants while discarding 94.3% of benign and 99% of the corpus, 98× the baseline — and it independently confirms § 4.7's reading of the sign, with 0.16% of pathogenic scoring negative against 34.35% of benign. Neither result changes what shipped, and the reason is the caveat attached to them: ClinVar is an ascertained set skewed to coding changes, so part of that enrichment is "AVI recognises coding damage", and the table is not evidence about regulatory variants. A default cut baked into the artifact would have carried that bias into every consumer; offering the whole corpus plus a knot table that says which cuts are safe leaves the choice where the caveat can travel with it.

Absence is row-absence. AVI covers ~95% of the assembly and writes 672,931 genuine zeros, so an unscored position has no row and a scored-zero position has a row holding zero. The test asserts set equality over (pos, ref, alt) in both directions, because a count cancels an invented row against a dropped one.

Two registry guards caught real defects rather than needing to be widened, which is the shape @registry-completeness predicts. test_the_lane_that_reads_its_release_differently_is_exactly_the_one_named rejected a release_label that was byte-identical to the default — a duplicate that would have drifted — and it was deleted. test_every_builder_module_has_a_lane_and_every_lane_but_one_has_a_builder rejected a module named for something other than its lane, and the module was renamed to alphagenome_avi_build.py rather than excepted, exactly as its own docstring instructs. That test also had to be split: having a builder module and having a rebuild adapter stopped being the same property, because this lane has the first and cannot have the second.

commercial_use is None, not True — see RM195. Unknown is a value.

RM192 — half a gigabyte of wheel for a service whose scores are plain bytes

Severity medium · Status ✅ shipped 2026-09-10 in the uncut 0.7.0 (just-dna-enricher only: a new [atlas] extra, two new modules, one new CLI command, the alphagenome extra deleted; no model, no parquet, no manifest field) · Owner enricher · Motivating case PROPOSAL_0_7_PT4, against ALPHAGENOME_ATLAS.md § 6.2

What it reproduced. uv add alphagenome resolves to 47 packages and 550 MB — anndata, pandas, scipy, zarr, h5py, numcodecs, pyarrow, matplotlib, seaborn, pyfaidx, absl-py, fsspec — against a tier whose entire runtime list is httpx/tenacity/huggingface-hub/typer/ga4gh.vrs. Six of the twenty declared dependencies are never imported on any scoring path, and atlas.py imports anndata at module level, so even the SDK's own import costs 242 MB. CONSTITUTION Goal 2 makes that a dependency-tier question rather than a disk-space one.

What the measurement changed. The probe's first answer was "a 22 MB client exists and is not declarable" — the light path being pip install --no-deps alphagenome grpcio protobuf, a deployment recipe rather than a dependency specifier. Reading the upstream repository refuted the second half: github.com/google-deepmind/alphagenome is Apache-2.0 and ships the .proto sources its own wheel generates bindings from. So the light path is declarable, and this is one of the four claims in that document that upstream prose got wrong and bytes corrected.

What shipped. enricher/src/just_dna_enricher/atlas_client.py (the three Atlas RPCs with the transport's exceptions kept inside), atlas_protos.py (the generator), just-dna-enricher atlas generate, and enricher/tests/test_atlas_client.py — 25 tests, now inside testpaths, all 25 green including the four live ones against the real service. Dependencies are the new [atlas] extra: grpcio + protobuf, measured at 19 MB and +2 packages in a clean venv on 2026-09-10 (grpcio 1.83.1, protobuf 7.36.1). grpcio-tools is build-only and joined [dev]; the dev group gained just-dna-enricher[atlas] so the suite collects the moved tests instead of erroring on import grpc. The alphagenome extra is gone.

What kept it honest. test_imports_stay_within_the_declared_floor walks the client's AST and asserts its third-party roots are exactly {grpc, just_dna_enricher} — an AST walk rather than a sys.modules check, because another test's heavier import would already be resident by then and the assertion would pass for the wrong reason. That test is what makes the size claim a property of the code instead of a sentence in a comment.

The stale argument, deleted rather than left standing. enricher/pyproject.toml carried a comment block asserting the light client "is not declarable here" and calling vendoring "a decision with a maintenance cost attached". Commit 1f9a84a had already refuted it by doing the vendoring, and a comment arguing against what the file now declares is worse than no comment. Rewritten in the same commit as the extra it describes.

What it did not do, filed rather than improvised (filed as RM280 on 2026-09-27; nothing was filed at the time). No tenacity layer over the vendored grpc_service_config.json (@retry-attempt-floor), no shared pacing gate, and no interval RPC — ListDenseVariantScores needs an x-goog-fieldmask header and 32 bp chunking, which RM194 owes. And the bindings are a build product no wheel can build, which is RM196.

RM184 — CACHE_LANES published every attribute of a lane except the variable that steers it

Severity low · Status ✅ shipped 2026-09-03 in the uncut 0.7.0 (just-dna-enricher only: one required field on CacheLane, fifteen constants in locations, no behaviour change in any resolver) · Owner enricher · Motivating case S89 (just-module-creator, in CONSUMER_SUGGESTIONS_HISTORY.md), filed as not deadline-bound and taken before the cut because it was cheaper to land than to schedule

What it reproduced. The consumer's 1:1 count: fourteen lanes in CACHE_LANES, fourteen JUST_DNA_<LANE>_CACHE literals in locations.py (one per resolver, passed to _resolve_parquet_cache or _resolve_named_cache), plus JUST_DNA_PIPELINES_CACHE_DIR, the shared base every default directory hangs off. CacheLane carried fourteen attributes and not that one, so the registry RM176 built so that a consumer stops keeping its own copy of what the lanes are still left one attribute to copy — and the consumer's suite, a .env.template generator and a provisioning audit were each keeping the fourteen names by hand.

What shipped. CacheLane.env_var: str, populated from new locations.<LANE>_CACHE_VAR constants that the resolvers now read in place of their literals — so the field and the behaviour are one string, and the field cannot name a variable the resolver ignores. CACHE_BASE_VAR is declared beside them and is deliberately not a lane attribute: it moves every lane's default at once and no lane owns it. Two tests: each lane's variable, pointed at a probe directory shaped to satisfy every presence test while the base is moved somewhere empty, resolves there and nowhere else; and an equality over the walked module — every JUST_DNA_* string locations declares is exactly one lane's env_var or the base — with each lane's identity-checked against its <LANE>_CACHE_VAR.

str, not str | None, against the consumer's candidate. They proposed None for a lane steered only by the shared base. No such lane exists, and inventing the state would put an undetermined value into a column where every row is determinate — RM87's argument for locus_count = 1. A lane that ever lacks a variable has to be argued for in the walked test rather than slip past an optional. The peer session that had just added release_label suggested the equality-over-the-exception pattern for the None set; with no exception the equality is over the whole set instead, which is stricter.

Not changed. cache status does not print the variable. The consumer's audit case — which caches were provisioned by variable rather than by path — is answered by reading env_var off the registry and the environment; a resolver cannot say which rung of its ladder answered, and adding that would be a change to every resolver for a question the registry already lets a caller ask.

RM183 — needs_recompile crashed on the one input a registry is most likely to hand it, an unstamped compiler version

Severity medium · Status ✅ shipped 2026-09-03 in the uncut 0.7.0 (just-dna-format only: one early return in needs_recompile, one re-raise in release_version, two str | None widenings on RecompileAnswer; no schema, parquet or manifest change) · Owner format · Motivating case S88 (just-module-creator, in CONSUMER_SUGGESTIONS_HISTORY.md), found while reading INTEGRATION_0_7 § 2.8 to decide whether to adopt the call

What it reproduced. The consumer's table, row for row. Compilation.compiler_version is str | None with a None default, so a manifest carrying nothing there is well-formed and comes back through read_manifest as None; needs_recompile(None, "0.7.0") then died in release_version's .strip() with AttributeError, an error no caller can catch by type or act on by reading. "" raised ValueError instead — the same fact, nobody stamped, answering two different ways. And a stamp with a trailing note, just-dna-compiler 0.6.6 (marketplace-server), was refused as '(marketplace-server)', the last token, which names nothing the caller wrote.

Why this input is the one that matters. INTEGRATION_0_7 § 3 tells the marketplace to adopt this call for revalidate/needs_upgrade, and the obvious implementation is a loop over stored manifests it did not produce. One unstamped manifest took that loop down. The three-valued axis is the whole point of the surface — None is unknown, complete=False over a span with no record — and an unstamped version is the purest unknown provenance it can be asked about. It already answered all-None for a release it had no record of; None deserved the same answer for a stronger reason.

The line, and the consumer's doubt. They worried the unknown answer was too quiet — a None passed by accident gets a valid answer instead of a crash. Weighed, and the line is drawn one row down rather than at the whole table: None, "" and whitespace are absent and answer unknown (compiled_under=None, span=(None, current), every axis None, complete=False); a stamp that is present and unreadable — "0.7", "v0.7.0", "0.6.6+local", the trailing note — is asked-and- cannot-be-read, a caller's bug, and still raises ValueError, now quoting the whole stamp. That is @unreachable-not-absent read onto an input: nobody-stamped is a third state beside stamped-and- readable and stamped-and-malformed, and only the last is a refusal. The package prefix stays unchecked on purpose — one version across the workspace is the rule since 2026-08-11, so just-dna-format 0.6.6 names the same release and refusing it would invent a distinction the workspace does not make.

Two type widenings, additively. RecompileAnswer.compiled_under and span[0] are str | None; None appears only where the call used to raise, so no reader that worked before sees a new value. Pinned by three tests: the three blank spellings answer identically (is None per axis, never truthiness), the four malformed spellings raise with the whole stamp in the message, and absent and uncovered — both unknown — are asserted not to collapse into one object, because a consumer grouping unknowns by cause reads compiled_under.

RM180 — an overlay row's provenance was inside content_signature, and rewording a reason minted a new content identity

Severity medium · Status ✅ shipped 2026-09-03 in the uncut 0.7.0 (just-dna-format — one field marker and its reader in base, one exclude= in integrity.content_signature, three marked fields on OverrideRow; just-dna-compiler — a roster comment and two tests; no parquet column, no vocabulary member, no CLI change) · Owner format · Motivating case S87 (just-module-creator, in CONSUMER_SUGGESTIONS_HISTORY.md), a before-the-cut report against the 0.7 branch at f4a9b14

What it reproduced. On reference_examples/hboc_palb2, with no compile and no network, one frequencies.csv correction produced four content_signatures: none, the correction, the correction with its reason reworded, and the correction with decided_by/decided_at changed. The first three movements are right — the overlay is authored input and the value it writes changes what the module asserts. The fourth is byte-identical data under a different sentence, and the consumer's reading of spec_tables' comment was accurate: it justified including the overlay without distinguishing the value cells from the provenance cells, because nobody had.

The decision, and who took it. The maintainer, 2026-09-03: exclude the three. The six cells table/subject/member/field/operation/value say what the correction is; reason/ decided_by/decided_at say why, who and when. The precedents are S25 — a README caveat is outside both identity halves, so fixing a typo in it is a patch — and the fact-signature family, which keeps fetched_at/status out of every derived table's hash. The counter-precedent is stated rather than repaired: curator/method on variants.csv are inside the signature, folded from defaults: as content (RM37), and moving them re-keys every published module. Nothing in the compiler or enricher reads the three cells; they exist for a human reader, and they are exactly the cells an author improves on a second pass.

Why the window was the release. The three fields are since("0.7.0"), 0.7.0 is uncut, and no published module carries an overlay, so excluding them moved no signature. After the cut the same change moves every overlay-carrying module's signature — the one move stamped_identity_field's docstring says a content-dedup key may not make. Filing it to a roadmap would therefore have been a decision to keep them in, taken by default; it was put to the maintainer as that.

The candidate mechanism was refused, and the suite is what refused it. The consumer proposed exclude=True, the stamped_identity_field idiom. Probed in a detached worktree first: the signatures collapsed exactly as expected, 1,054 schema and overlay tests passed, and reason survived reverse — whose column list is authored_field_names, which filters on COMPILER_MANAGED and nothing else. The full suite then failed one enricher test, test_answered_call_shift, because its overlay writer serializes rows through model_dump() and an excluded reason came out blank, which OverrideRow refuses by design. draft._authored_dump makes the same model_dump() call, read from the code rather than run: every drafted overlay row would have failed its own compile on a blank the tool wrote. A stamped column can be excluded because nothing authors it and no writer reads it back; an authored column cannot, because model_dump() is the writers' contract. So the fact lives on the field as OUTSIDE_CONTENT_IDENTITY, content_identity_exclusions(model) walks it, and integrity.content_signature passes it as exclude= — the one reader. A test asserts the marked set over _ALL_MODELS equals exactly the overlay's three, so a fourth cannot leave the signature silently and a marker on any other model is a visible decision.

What still sees the prose. overrides.parquet (_build_table reads fields off the model), manifest.inputs (raw bytes of overrides.csv), the verification binding (a reworded reason still un-closes a module), reverse (re-emits all nine columns; the fixed-point test now asserts the reason cells on the reversed bytes, since the signature can no longer vouch for them) and artifact.digest, which moves. That is the README shape.

What it did not repair. A reader that dedups on content_signature and then opens overrides.parquet can find two modules with one signature whose overlay prose differs — the consumer's own argument against their fix, and the shape README already has; stated in SCHEMAS. And the maintainer's observation on the resulting picture — byte digest moved, every signature intact, what moved unstated — is RM181.

RM187 — eleven bulk downloads carried one body in eleven copies, four of them leaking the transport

Severity high · Status ✅ shipped 2026-09-03 in the uncut 0.7.0 (just-dna-enricher only — one shared helper, eleven call sites, two adapter handlers; no schema, no parquet column, no CLI flag) · Owner enricher · Motivating case a real failure during RM179's republish: NCBI closed the connection 180,927,542 bytes into a 193,427,450-byte ClinVar VCF on 2026-09-03 and the run died with a raw httpx.RemoteProtocolError traceback

The leak is the item; the missing retry is what made it likely. _rebuild_clinvar catches ClinVarBuildError, and download_clinvar_vcf raised httpx's own type — so the lane could not report built=False, and the exception escaped rebuild_lane as well. In a full cache rebuild that aborts every lane after the flaky one, which is precisely the rule that loop was written to hold ("one snapshot failing must not sink the rest"), defeated one level below where it is stated. Four of the eleven builder downloads were in that state — clinvar_build's two, constraint_build's and clinpgx_build's — and the other seven translated correctly.

All eleven had no retry, which is the part worth pausing on. Every live client in this tier has had attempt_floor since RM42, and the requests without it were the largest ones the tier makes: a ~190 MB VCF and a ~95 MB TSV over public mirrors, exactly the fetches most likely to be cut short. The asymmetry had a cause rather than being an oversight — net.py was documented as pacing for live API clients and download.py as HuggingFace provisioning, so each builder reached for neither and wrote its own fifteen lines. Eleven copies of a body nobody owned.

One helper, and the eleven public signatures unchanged. net.stream_to_file returns a StreamedFile (path, sha256, etag, last_modified) and each downloader builds its own return type from it, so no caller moved — the five different return shapes (Path, tuple[Path, str], and three per-lane dataclasses) are all still there. Four properties, each of which had been a defect somewhere: atomic through .part, retried on transport failure, translated at the boundary, and restarted from zero on each attempt — the hasher and the file handle are created inside the attempt, because a retry that appended would produce a file whose digest is real and whose contents are nonsense, which neither a footer check nor raise_for_status would catch.

Retried only where retrying is honest. httpx.TransportError is the predicate: RemoteProtocolError subclasses it, so the motivating incident is covered, and a second attempt genuinely fixes a cut connection. A status error is deliberately not retried — a 404 from a mistyped release tag is the same 404 four times over, and three backoffs only delay telling the caller what the first response already said. That matches the tier's dominant predicate rather than gnomAD's wider one, which retries HTTPStatusError because its own rate limiting arrives that way.

constraint_build had no error type at all, which is why its download leaked: there was nothing to translate into, and _rebuild_constraint therefore caught (FileNotFoundError, ImportError, OSError). A lane without its own type cannot be caught as that lane. It gains one, and ClinVarUnavailable / ClinPgxUnavailable / ConstraintUnavailable are subclasses of their lane's error so a caller catching the build error still catches them, while one that wants to tell the source was unreachable from the bytes were unreadable can ask by name — the distinction that decides whether retrying is even the right response.

Third appearance of @client-exception-contract, and the guard is shaped by the second one's failure. RM97 found the leak in the clients, RM101 one layer up in the passes, and the builder downloads were never swept. RM101's own coverage guard hand-kept eight module names and missed identifiers, leaving OntologyClient leaking raw httpx for a release — so this guard walks the package by AST, and twice: no download_* may open a stream, and httpx.stream appears nowhere outside net.py. The second walk exists because the first is keyed on a naming convention, and a new bulk fetch called fetch_dump would satisfy it by not matching.

Two defects found by the sweep rather than reported. pubmind_build was the one handler of eleven that did not unlink its .part on failure, so a failed fetch there left a partial behind (@a-failed-fetch-is-not-a-no-op). And four of the eleven computed a sha256 while streaming and only logged it, so a caller recording the provenance of bytes it had just fetched had to hash the file again — two lanes had already grown a tuple[Path, str] return for exactly that reason, one at a time (@dont-discard-computed). The shared body returns it to all eleven.

The old behaviour is demonstrated on the old arrangement, not asserted about the new one: a test restores download_clinvar_vcf to raising the transport type and watches the exception come back out of rebuild_lane. Without that, the claim that this repair fixes something is a claim about code nobody ran.

What it does not do. No downloader gains a resume — a retry re-fetches from byte zero, so a connection that dies at 180 MB costs the whole 190 MB again. Range requests would fix that and are not free: the mirrors' Accept-Ranges support is unmeasured, and a resumed body needs the digest computed across two responses, which is a different design from this one. Worth an item if the incident recurs; not worth guessing at now.

RM185 — a publish could replace a release.json describing bytes it was not carrying

Severity high · Status ✅ shipped 2026-09-03 in the uncut 0.7.0 (just-dna-enricher only — one guard in the publisher, wired into three publish paths; no schema change) · Owner enricher · Motivating case RM179's own entry, which fixed the ClinVar lane and left the general shape to the maintainer; decided with them the same day

The general form of RM179. A snapshot's release.json describes every half the artifact carries, because a builder merges its block in rather than writing a file of its own. A publish that carries one half replaces the whole description — and the publisher adds without deleting, so the other half survives as bytes nothing describes. ClinVar is the lane it happened to, and RM179 stopped that lane from producing the input; nothing stopped a publish from accepting it, and any lane that grows a sidecar could repeat it.

It reads the remote tree, not the remote release.json, and that is the load-bearing choice. The intuitive guard — compare the incoming description against the published one — would have passed the second bad publish exactly as it passed the first, because by then the block was already gone from the published file while citations/citations.parquet was still there. The bytes are what a puller gets, so the bytes are what the guard asks about. Scoped to publishes that carry release.json, since one that carries none overwrites no provenance; a repo that does not exist yet lists nothing and passes, because that is a first publish and not an orphan.

OrphanedSidecarError, its own type, for the reason PublishCollisionError is one: the CLI has to tell it from the refusals plan_* raises. Those say the local snapshot is unpublishable; this one says the local snapshot is fine and the remote holds bytes this publish would stop describing. The message names the file and the command that builds the missing half. The dry run runs it too — a rehearsal that skips what the real thing refuses on is the same defect as an allowlist that drops a file the dry run promised (@publisher-allowlist-derived), so --dry-run reads the repo and exits non-zero with WOULD BE REFUSED.

The state it was written against was repaired while it was being written, which is worth recording rather than smoothing over: just-dna-seq/clinvar was republished on 2026-09-03 with the citations block restored (clinvar_file_date 2026-08-29, 3,925,275 links, 30 files), so the mixed-vintage artifact this guard refuses no longer exists on that repo. The guard was verified against the live tree as it stands — carrying the sidecar and a matching description, it passes — and against the found state as a fixture. That the repair and the guard landed the same day is not a reason to trust the repair alone: RM179 stopped the lane producing the input, this stops any lane's publish accepting it.

· from RM179's deferred half · related RM179, RM186 · also in CHANGELOG, AGENT_NOTES @a-publish-may-not-orphan-the-bytes-it-stops-describing

RM186 — deletion on a published repo, by declaration or by asking, never as a side effect

Severity medium · Status ✅ shipped 2026-09-03 in the uncut 0.7.0 (just-dna-enricher only — LayoutShift + cache prune; no schema change) · Owner enricher · Motivating case the 159 MB single-file data/clinvar.parquet from the pre-2026 layout, still at HEAD in just-dna-seq/clinvar beside the 25 clinvar-chr*.parquet that replaced it

The policy is the maintainer's, and it corrects a premise of this repository's own. @snapshot-accumulates had been read as never delete, and the audit that produced this round inherited that reading and reported the remnant as a human's job. The maintainer's correction: a HuggingFace dataset repo is git-backed, so a delete is a commit and a superseded revision still resolves — three of them were read off the hub while auditing this. Deletion is therefore recoverable, and the reason to be careful is not lost bytes. It is that a retired file goes on answering 200 to whoever still asks for it, which is how a lane's default archive stayed frozen for a year (CLINPGX_ARCHIVES), and that a sweep deletes what nobody looked at.

So there are exactly two ways a published file goes away, and neither is a side effect of a publish.

  1. A declared retirement — LayoutShift. A change that retires one published file and introduces another carries the migration with it: if the new spelling is absent from the repo and the old one is present, upload the new and delete the old. The predicate is over the remote, so it fires once per repo and is a no-op forever after; it rides in the upload's own commit as delete_patterns, so the arrival and the removal are one commit rather than a window in which the repo has both or neither, and the retired name appears in the commit message. What makes it safe is not that it is small but that it is named, in the commit that changed the layout, where a reviewer sees both halves at once.
  2. cache prune, which asks. It names two kinds of file and nothing else: one under data/ that the lane's own glob excludes — not part of the snapshot by the same definition provisioning uses, which already refuses to download it — and one a LayoutShift declares retired. README.md, .gitattributes, release.json, LICENSE.txt and sidecar directories are never candidates. Without --yes it reads, prints each file with its size and the reason it is nameable, and stops.

The declared entry is already past its own condition, and it stays literal. just-dna-seq/clinvar carries the old file and the new, because the publish that introduced the per-chromosome layout predated this rule — so the shift will not fire there, and the remnant is cache prune's. Loosening the predicate to retire the old whenever the new is present would sweep it, and would also make every publish a prune until the file was gone, which is what deletion-by-declaration exists not to be. The entry stays for the repo cloned or re-created later, which is the state it is actually for.

Second reader of the per-lane globs, so they became a registry. cache prune asks what does this repo carry that this lane is not made of, which can only be asked by lane; SNAPSHOT_FILE_GLOBS is now the one place each lane's file pattern is spelled and the ensure_* closures read it, so the provisioner and the pruner cannot come to disagree about what a snapshot is. Walked by test against the publishable lanes, with STRchive the one enumerated exclusion — its snapshot is a single JSON at the repo root, so there is no data/ for a file to be outside of, and cache prune says n/a rather than clean, because "found nothing" and "cannot look" are different answers.

Measured, read-only, against the live repos: one candidate in clinvar (159.5 MB, declared), constraint/clinpgx/cpic/drug_labels/civic/mitomap clean, strchive n/a, and every unpublishable lane skipped with the registry's own reason. Re-measured after that repo was republished mid-session and unchanged, which is the predicate behaving as designed: the republish restored the citations half and did not touch the legacy file, so the shift still does not fire and prune still names it. Nothing was deleted — publishing and deleting on HuggingFace remain the maintainer's to run.

· from the 2026-09-03 published-artifact audit · related RM185, RM178 · also in CHANGELOG, AGENT_NOTES @a-publish-may-not-orphan-the-bytes-it-stops-describing

RM179 — the ClinVar rebuild built one half of a two-half artifact, and published its provenance over the other

Severity high · Status ✅ shipped 2026-09-03 in the uncut 0.7.0 (just-dna-enricher only — one rebuild adapter; no schema, no parquet column, no CLI flag) · Owner enricher · Motivating case the published just-dna-seq/clinvar on 2026-09-03: records from ClinVar 2026-08-29 beside a citations/citations.parquet built from 2026-06-27, and a release.json describing only the first

A published snapshot is two halves on two cadences, and only one of them was being rebuilt. ClinVar publishes var_citations.txt separately from the VCF, so a snapshot legitimately carries records from one release and citations from another — which is why build_citations merges a citations block into release.json rather than writing its own file. _rebuild_clinvar called build_snapshot and stopped, and release.json is written by that half. So cache rebuild clinvar --publish uploaded a fresh, citations-free provenance over a repo whose sidecar it had not replaced, and the publisher adds without deleting: the sidecar survived the description that had named it. The block was there until the 2026-09-02 publish (revision 8f5c5720 has it) and gone afterwards.

The defect is structural, and that is what makes it worth an entry. Nobody deleted the block and no operator did anything wrong; the adapter's shape guaranteed the outcome on every rebuild. The same shape is one @registry-completeness step away from the class this repo keeps meeting — a fact about a lane that lives in a comment ("the citations table is published with the snapshot") rather than in code that has to hold.

Both halves or neither. The adapter now downloads var_citations.txt and runs build_citations into the same directory, so the merged release.json describes the pair the publisher will carry. A failure in the second half returns built=False with no out_dir rather than a quieter success: cache rebuild --publish uploads only on built is True, so the artifact this item exists to stop anyone publishing cannot reach the plan. The detail line says the records did build, which is the difference between retry the pair and it broke.

What it costs, stated rather than hidden. --source clinvar=<vcf> remains the VCF's off-switch, and the citations file is a separate ClinVar download that is still fetched — so a fully offline rebuild of this lane now reports failed where it used to report a snapshot. That snapshot was the mixed-vintage one, so the trade is deliberate; a lane-local second --source was refused as a flag grammar for one lane's second input, which is the shape MANE and CIViC already refuse.

Not repaired here: the publish-side guard. A publish that overwrites a remote release.json describing sidecars the plan does not carry should refuse, and that is the general form of this bug — it would have caught this one at the boundary rather than at the lane. It is a policy about what a publisher may overwrite, so it is the maintainer's call and not this item's. Nor does this repair the repo as it stands: just-dna-seq/clinvar still needs a citations rebuild off 2026-08-29, which is an outbound operation.

· from the 2026-09-03 published-artifact audit · related RM176, RM178 · also in CHANGELOG, AGENT_NOTES @a-lane-with-two-halves-publishes-the-provenance-of-one

RM182 — cache status named the release of every snapshot except the one that moves weekly

Severity low · Status ✅ shipped 2026-09-03 in the uncut 0.7.0 (just-dna-enricher only — one field on CacheLane and the reporter that reads it; no schema change) · Owner enricher · Motivating case the same audit: cache status over a freshly pulled cache printed clinpgx_2026-08-05, civic_01-Sep-2026, strchive_v2.26.0 … and a blank for clinvar

One reader, twelve writers, and the odd one out was the one that matters most. cache status labelled a lane with release.json's dataset. Eleven builders write it; clinvar_build writes clinvar_file_date and record_count instead, and has since long before the field existed. So the lane that refreshes weekly was the only one an operator could not read a release off — precisely the lane where which release is this? is asked.

The label is a lane's own property, not the reporter's. release_label joins build_command as a field that exists because a convention holding for eleven of twelve is not a convention: the reporter composing one for every lane is what produced the blank, exactly as composing f"{name} build" once printed two commands nobody could run. ClinVar's is clinvar_dataset_label — the function clinvar_draft already writes onto its licence row and clinical.tautology_reason recomputes to compare — shared rather than mirrored, because two spellings of one label never match and never fail either. The exception is asserted as an equality over the registry, so a second lane that stops writing dataset has to say so here instead of quietly printing nothing.

Refused: adding dataset to clinvar_build's release.json. It repairs nothing already on disk or already published — every existing snapshot would still print blank until rebuilt — and it makes a second writer of a label clinvar_dataset_label already owns. It stays available as an additive follow-up; it is not the fix.

· from the 2026-09-03 published-artifact audit · related RM176, RM179 · also in CHANGELOG, AGENT_NOTES @the-reporter-cannot-compose-a-lanes-label

RM178 — a failed optional fetch left a 0-byte licence in every pulled cache, and an empty licence pins the empty string

Severity medium · Status ✅ shipped 2026-09-03 in the uncut 0.7.0 (just-dna-enricher only — one download loop, one normalization in SourceTerms.row, one archive reader; no schema, no parquet column, no vocabulary member) · Owner enricher · Motivating case an audit of the published HuggingFace artifacts on 2026-09-03, which pulled every publishable lane into a scratch cache and found LICENSE.txt at 0 bytes in four of them

The transport does not behave the way the try assumed. _provision_snapshot ends by fetching the two optional root files, release.json and LICENSE.txt, inside a try/except that logs "the cache carries data only" — written on the assumption that a failed fetch changes nothing. It does not: HfFileSystem.get opens the destination for writing before it resolves the remote path, so a repo publishing neither file leaves a 0-byte one behind. Four of the nine published snapshots publish no LICENSE.txt (clinvar, gnomad_constraint, cpic, mitomap), so every cache pull on a hosted deployment created four phantom licence files. The same call truncated an existing local copy from 36 bytes to 0 — verified against the live hub, both halves, before anything was changed.

An empty licence is not a smaller absence, it is a different answer. The readers guard on is_file(), which cannot separate the two, and the answers diverge: an absent LICENSE.txt leaves license_sha256 null and warns, while an empty one records sha256:e3b0c442…b855, the hash of the empty string, as a pin — a definite claim about terms nobody read, in a field whose only purpose is to tie recorded terms to the text that governed the bytes (S44's whole point). Nothing had noticed because the one lane that reads the file, ClinPGx, publishes a real one.

Repaired at both ends, and the read end at the sink. The write end stages through .part and renames on success — the idiom the parquet and sidecar loops of that same function already used — so a failure leaves nothing and cannot overwrite what is there. The read end normalizes in SourceTerms.row: blank or whitespace-only license_text is None. At the sink because there are four callers (clinpgx_build.read_license, drug_labels_build, clinpgx_draft, and a registry's status field), and a rule restated per caller is a rule three callers drift from; read_license answers None for a present-but-blank archive member for the same reason one level up. clinpgx_draft keeps a blank check of its own only because it owes a warning, which the sink cannot emit.

Refused: deleting the phantom files from operator caches. _provision_snapshot already reports a foreign parquet rather than removing it — someone else's cache directory is not ours to clean — and the same rule holds here. A 0-byte LICENSE.txt in an existing cache is now inert (nothing pins it, and the next pull replaces or leaves it), and an operator who wants it gone can delete it.

· from the 2026-09-03 published-artifact audit · related RM176, S44 · also in CHANGELOG, AGENT_NOTES @a-failed-fetch-is-not-a-no-op

RM177 — nine builders wrote their snapshot beside pyproject.toml, because the rule that forbade it was prose

Severity medium · Status ✅ shipped 2026-09-03 in the uncut 0.7.0 (just-dna-enricher only — fourteen --out defaults and one locations helper; no schema, no parquet column, no vocabulary member) · Owner enricher · Motivating case the enricher reference and the authoring skill both telling an operator to run clinpgx build --out ./clinpgx from a checkout

The rule was old and it had been enforced exactly once. Nothing a command generates goes in the repository root was filed when civic reproduce wrote civic-reproduce/ there and needed its own .gitignore line to say so; the repair moved that one default under data/repro/ and wrote the rule into CLAUDE.md. Every builder written after it repeated the defect, because a rule stated in prose is checked by whoever remembers to read it. civic, clinvar, pubmind, gnomad_constraint, mane, strchive, acmg_sf, mitomap and mitomap_miss each defaulted --out to a bare relative name, so running any of them from a checkout dropped a snapshot directory beside pyproject.toml. Four more — clinpgx build, clinpgx build-labels, cpic build, pharmvar build — required --out with no default at all, which is how the reference came to show --out ./clinpgx. Nothing was ever committed by accident, because blind staging is banned here for an unrelated reason; the defect was visible on every git status and survived nine builders anyway.

What shipped is one function, not fourteen corrections. locations.repro_out(name) returns data/repro/<name>/, and every builder's --out default is a call to it. cache rebuild keeps data/caches/ as locations.CACHES_DIRNAME, in the same file, because a cache base is a different concept from one snapshot and the point is that neither is spelled inline. civic reproduce moved from data/repro/civic to data/repro/civic_reproduce, since civic build now takes the plain name; the probe records that name the old path (CONTRADICTION_CORPORA) are dated and keep it. A caller passing --out sees no change.

The guard walks rather than lists (@registry-completeness). test_build_out_defaults.py parses cli.py, finds every typer.Option bound to --out, and asserts each default is repro_out(...) or a locations constant — never a literal. Sixteen found, and sixteen "--out" strings in the file, so nothing escaped the walk. The one required --out that remains, clinvar citations, names an input (an existing snapshot to add a sidecar to) and is enumerated as an equality, so the exemption cannot grow quietly. A floor — at least nine under data/ — would have passed forever while the tenth builder wrote wherever it liked.

Refused: a .gitignore line per lane. It is the repair civic reproduce originally got, and it is the shape that produced nine repeats: each new builder would need its own line, which is the same prose rule at a different address. /data/ is ignored whole, so a default under it needs no line.


RM160 — the citations ten CIViC records carry are published on one surface, and it is the one nothing read

Severity medium · Status ✅ SHIPPED 2026-09-03 in the uncut 0.7.0 — the provenance half, as shape 3 (just-dna-enricher client + command + check, two optional studies.csv columns, one new VALID_VERIFICATION_CHECKS member). Its coverage half shipped earlier as RM169, and the VCF that answered the first could not answer this one · Owner enricher · Motivating case the 2026-09-01 residue round, variant 1955 (CIVIC_LEGACY_INSERTIONS §7.4)

Read this first: the item's original premise was wrong. It said the API has no dated release to pin, and therefore that any wider basis costs the snapshot its reproducibility. CIViC publishes <date>-civic_accepted_and_submitted.vcf in the same dated directory as the TSVs, so the wider corpus was pinnable all along and RM169 took it: 507 rows on 270 variants → 1,149 on 397, with a byte-identical rebuild. The three shapes below were framed against the coverage half, which RM169 then dissolved without using any of them; they are re-scoped rather than retired, because for the half that is left the tension is real.

What that leaves here is narrower and still real. The VCF cannot carry a variant with no GRCh37 position, so it holds none of the 10 records whose hidden citations motivated this item, and 1 of the 53 unresolvable variants. The provenance half is API-only or nothing.

civic build reads the dated bulk TSV release, and every row in it is evidence_status = accepted. CIViC's own GraphQL API defaults to NON_REJECTED and serves 11,518 evidence items against the bulk file's 4,903 — a 2.35× difference between two published faces of one database, declared by neither. SUBMITTED (a curator entered it, no editor signed off) is the majority of CIViC: 6,614 of 11,518.

The snapshot records status_basis: "accepted" in release.json, so the basis is not hidden. What is missing is any sense that the choice costs something, and there is now a worked instance where it costs more than rows.

The instance, because a doubled row count was never the argument

Variant 1955 (VHL P71fs (c.211insT)) is one of two records in the whole corpus that nothing resolves: a legacy insertion notation with two readings, both registered as real and different alleles, and no discriminator anywhere. Its accepted evidence item cites Olschwang 1998, paywalled and not in PMC. Ong 2007, behind the sibling record 2131, likewise.

Queried directly, evidenceItems(variantId: 1955, status: ALL) returns two items. The second, EID 9969, cites PMID 12202531 — Dollfus 2002, free full text, whose Table 3 states the numbering convention the whole ambiguity turns on. It is SUBMITTED, so it exists in the API and in no file the builder reads.

So the basis does not merely shrink the corpus. Here it hides the only reachable evidence that could settle an identity the snapshot is currently unable to state — and it hid it from a probe that had already gone looking, because the probe read the file the builder reads.

Re-measured 2026-09-01, and it is worse than "a bigger corpus"

Two numbers sharpen the item, and the second changes what it is about.

On the direction axis the gap is 2.77×, not 2.35×. Queried per status rather than taken from the whole-database ratio:

basis all evidence items PREDISPOSITION/SUPPORTS
ACCEPTED 4,906 534
SUBMITTED 6,617 946
NON_REJECTED 11,523 1,480

So the axis this source was adopted for is more skewed toward unreviewed content than the database as a whole. (DOES_NOT_SUPPORT is 2 → 4 and PROTECTIVENESS 1 → 2, which is why the contested-variant count moves 0 → 3 and genuine risk-vs-protective opposition still does not.)

Ten of the twenty records nothing can place gain a citation the accepted basis does not carry. This is the finding, and it is not about volume. Asked status: ALL, per record:

record accepted citations citations only SUBMITTED brings
844 VHL Exon 1 Deletion 3 34
1939 VHL Exon 3 Deletion 4 33
843 VHL Exon 1-3 Deletion 2 17
845 VHL Exon 1-2 Deletion 1 18
2182 VHL Null (Large deletion) 3 7
2439 VHL Rearrangement 2 7
715 STK11 Mutation 3 4
2036 VHL Null (Partial del Ex2&3) 1 2
3298 VHL P81S and L188V 1 1
1955 VHL P71fs (c.211insT) 1 1 — the free-fulltext one

A verdict is only as wide as the papers read, and these were read on the accepted basis. The class-C three-way split in CIVIC_UNRESOLVED — never measured / measured then generalised away / measured at a resolution that is not allele resolution — was decided from each record's cited papers, and for 2036, 2182 and 2439 those were the accepted ones only. The verdicts about what the name denotes are untouched (a class label stays a class label however many papers cite it), but the claim that the source never measured breakpoints is scoped to papers that a wider basis would have added 2, 7 and 7 more of. That scope belongs on those verdicts whether or not this item is ever taken.

What is already measured, so nobody re-derives it

  • Reading SUBMITTED roughly doubles the corpus and moves every number in CIVIC_SURVEY.
  • It takes the contested-variant count from 0 to 3 (variants 2161, 2428, 2533, all VHL, all risk against not_risk). Under accepted the count is 0 because both sides of every contest are SUBMITTED.
  • Genuine risk-vs-protective opposition stays 0 at every basis, so this does not reopen the concordance route (that is closed on arithmetic, not on volume).
  • The direction slice is 533 rows on the accepted basis and 925 SUBMITTED against 533 ACCEPTED over the wider germline direction set.

The design question, re-scoped 2026-09-01 after RM169

Is the API richer than the files? Yes, on exactly one axis, and it is this one. The whole dated download surface is enumerated in CIVIC_SURVEY § the bulk releases: seven TSVs and two VCFs. Both TSVs the builder reads are accepted-only (ClinicalEvidenceSummaries, and VariantSummaries too — a fact nothing had stated before that enumeration), the only two files carrying submitted at all are the VCFs, and a VCF record needs a POS. So submitted evidence attached to a variant with no GRCh37 coordinate is published on one surface only, the API. For everything that has a coordinate, RM169's dated VCF already carries it, pinnable, no API. Nothing else about the API is richer than the files, and the three summaries the builder does not read (AssertionSummaries 145 rows, FeatureSummaries/GeneSummaries 973 and byte-identical to each other, VariantGroupSummaries 30) do not bear on this: none is an evidence table.

So the reproducibility tension survives, narrowed to this half. civic build is byte-reproducible because its input is a pinned dated file pair, and civic reproduce proves it by building twice. An API read still has nothing to pin. Of the original three shapes, two stay live and one stopped meaning what it meant — this is not an open three-way choice, and it was mistakenly re-put as one on 2026-09-01:

  1. Snapshot the API response with a retrieval timestamp and hash it as an input, the way the download files are hashed. Reproducible against that capture, not against CIViC.
  2. ~~A second parquet beside the accepted one, built from the API~~ — dissolved by RM169. The wider parquet exists and is built from files; one more from the API would be a third basis rather than a second, and the consumer decision this shape was priced against has already been spent.
  3. Leave the build alone and read SUBMITTED at enrich time, beside the CAID pass, where network reads already live and reproducibility is not claimed. Narrowest, and it does not enlarge the published snapshot — which may be the point or may be the missing half.

DECIDED 2026-09-02 with the maintainer: shape 3. civic build and civic reproduce keep their byte-reproducibility contract untouched and the published snapshot does not grow; the API read lives where network reads already do and where reproducibility is never claimed. The motivating case is an enrich-time question anyway — an author resolving one identity, holding one variant, needing the citations that variant's record carries. Shape 1 was available and not taken: hashing a capture keeps the word reproducible while changing what it is reproducible against, and a snapshot that reproduces only against itself is a weaker claim than one that reproduces against a dated release.

Not yet built. What it needs: a per-variant evidenceItems(variantId:, status: ALL) read behind the same offline/check_declared_use discipline as the other enricher fetches (CIViC is CC0, so no gate), the status on each returned item carried as confidence/confidence_unit unconverted, and a skip that is offline/unreachable rather than a silent empty — the pass has to distinguish the API said this variant has nothing more from nobody asked. It is one variant at a time by construction, which is why it fits enrich and would not fit a build.

The labelling requirement is settled and half-shipped. An accepted row and a submitted row must not be indistinguishable once both are in the file, and for the file-built half RM169 did it: every row carries evidence_status, CIViC's own word, unconverted. Whatever shape this half takes owes the same stamp — and where it lands as a magnitude rather than a column, that is confidence with confidence_unit, named rather than translated into a house grade, the way ClinSigAuthorityCallRow already requires a magnitude to name its instrument.

Related RM152 (the adoption), RM159 (the name-identity table, whose two unresolved records are the motivating case), RM153.

What shipped, 2026-09-03

civic_api.py — the client. evidenceItems(variantId:, status: ALL), paginated (variant 844 really is 37 items and a first-page reader would have reported four), checked against the payload's own totalCount, paced on a shared PacingGate, retried on attempt_floor(3), and translated at the boundary: CivicApiUnavailable for the question that was never put, CivicApiError for an answer this client cannot read — a GraphQL errors block is the second, because the service did answer. Statuses are lower-cased to the spelling civic_vcf already writes and not otherwise touched, and a member outside {accepted, submitted, rejected} raises rather than defaulting.

civic citations <spec> — the command. Three routes reach a CIViC variant id, and the third exists because the first two miss the class this item is about: the snapshot's coordinate join through clinical.comparison_plan (the same resolved-(chrom, start, ref, alt) route the refutation leg uses, never an rsID), the curated name-identity table, and --variant-id N for a record neither can place. 1955 is not in CIVIC_NAME_IDENTITY_BY_VARIANT — being unresolvable is why its citations were unreachable — so without the third route the motivating case would not have been reached by the thing built to reach it. Those rows ground the module rather than a variant, which StudyRow has permitted since RM47.

A recovered citation is a studies.csv row and nothing writes literature.csv. That table is derived from these PMIDs by the literature pass, and an article row nothing cites is dropped from the artifact (@uncited-literature-dropped) — so drafting the citing row and letting literature fill the article is the pairing that works in both directions. Five evidence items citing one paper are one row, because (variant_key, pmid) is the grain.

StudyRow.confidence / confidence_unit, optional and 0.7.0. The labelling requirement was settled before the round: an accepted row and a submitted row must not be indistinguishable once both are in a file, and where the state lands as a magnitude rather than a column it rides here, named rather than translated. This is one authored column pair more than PROPOSAL_0_7_PT3 priced the item at — that file says RM160 "adds no authored column at all" — and the correction is recorded as a dated addendum there rather than left as a silent contradiction. It is still minor-legal: a new optional column is additive under P3/P8, content_signature does not move for a module that fills neither, and the parquet it lands in is the one RM140 had already moved this release.

evidence_status_currency — the canary, and the half the maintainer asked for by name. Drafting from a live read is only honest if something re-asks: the pin says when and on what basis (fetched_at and dataset on the (civic, literature) SourceRow), and enrich re-asks and reports what has moved — a status accepted or rejected since, or a citation added since. Two codes because two remedies. Warns in both modes and escalates in neither (@a-source-recuring-is-not-a-strict-matter), and deliberately not dataset_currency: that one asks which release a table came from, this one asks whether a per-item judgement has moved.

The pin's layer is literature, and neither half of that is arbitrary. (civic, annotation) is civic_draft's row and a second surface of an already-declared source may not claim the lane's slot (@write-the-sourcerow); a civic_api source would publish a route as a licensed body, which is the overloading @source-vs-authority fixed in gene_metrics.csv; and literature is one of the two layers the compiler's orphan check exempts, so a module carrying studies.csv rows does not warn source_row_unused. merge_sources_csv is never-clobber, so the pin records the ask that first put a recovered citation into the module — a floor on "not asked since", which is precisely the gap the canary closes.

Three withholds, and each is counted rather than silent. Rejected evidence is not drafted at all (rejected_by_source) — status: ALL returns what CIViC's editors threw out, and a module must not carry it as though the source stood behind it; where a rejected item sits beside a live one for the same paper, the live ones decide the row, which is the real case on variant 1939 (PMID 28256701). A paper whose live items disagree about their status gets its confidence withheld rather than picked. A citationId on a non-PubMed source is a real id in another namespace and withholds rather than becoming a pmid (@pmid-vs-pmcid).

What it does not reach, said rather than smoothed over. A citation recovered through --variant-id names no variant, so nothing can map it back to a CIViC id on a later run: the canary reports those as not_re_askable under a no_reference skip rather than counting them as agreement. That is a real bound on the route built for the motivating record, and the honest form of it is a published number, not silence.

Tests. Three real recorded responses under assets/civic_api_slice/ (1955 for the motivating pair, 844 for volume and the five-items-one-paper case, 1939 for the only rejected item in the corpus), served through a mock transport so the suite never fetches; every expected value derived from them at runtime. The --offline probe's transport fails the run if it is reached, because an off-switch needs its own probe rather than a reading (@off-switch-needs-a-probe).

RM171 — MITOMAP's curated mtDNA tables, adopted as the increment they carry over ClinVar

Severity low-medium · Status ✅ SHIPPED 2026-09-03 in the uncut 0.7.0 — two cache lanes (one of them the registry's first derived lane), a parents field on CacheLane, a draft source, a SourceTerms row and five abbreviations in the shared clinical-significance normalizer. Nothing removed, promoted to required or retyped · Owner enricher · Motivating case RM164's probe, which found the table while answering a different question · Design rm171_diff_strategy, written by the maintainer, on the measurements in MITOMAP_STATUS; build order in PROPOSAL_0_7_PT3

What the entry was blocked on, and why that binary was the wrong question. It read does a source contributing sixteen new expert-panel calls earn an adoption, or does ClinVar already carry this? — and "16" is not a fact about MITOMAP. It is a fact about one join against one ClinVar vintage, and a hardcoded list of sixteen alleles is a snapshot of a diff, stale the next time either parent is rebuilt. What shipped answers the other question instead: what does MITOMAP publish that the ClinVar cache does not, derived every time both caches are current.

The shape: two parents and one derived child. mitomap is an ordinary lane — curl the published pg_dump, keep six of its hundred-odd tables, write parquet. mitomap_miss is not a download at all: its acquire stage is both parents on disk, its build is an exact (start, ref, alt) join on chrMT against the ClinVar parent, and its release.json pins both parents so a ClinVar rebuild without a child rebuild is detectable rather than silent. CacheLane gained parents for it — empty for the twelve that shipped with RM176, a two-lane tuple here — plus a guard whose outcome is built=None naming the missing parent. Both wrong answers were available and both are silent: a False files another lane's absence as this lane breaking, and an empty miss is the strongest possible claim about MITOMAP derived from a comparison that never ran.

Four buckets, and only one drafts. photocopy — the exact allele is in ClinVar, so the ClinGen mtDNA VCEP's call already reaches this repository with ClinVar's own provenance; drafting a second copy would attribute it to the wrong publisher and would hand a ClinVar concordance check a copy of ClinVar to agree with (@tautology-zero). rated miss — absent, and the bracket is one of the five documented VCEP classes. unrated miss — absent, and MITOMAP published no class this tier may map. unmintable is a fourth because the question cannot be asked of it: MITOMAP writes a deletion right-anchored (refna="TA" against regna=":"), and turning that into a VCF allele needs the rCRS base at position - 1, which Principle 2 forbids these tiers from fetching.

The bracket is a normalization; the confirmation token never is. status is a two-token grammar — a confirmation token (Reported/Cfrm/Conflicting reports, plus Unclear in the sibling table) followed by an optional bracketed rating. MITOMAP's own legend says in as many words that the first is not an assignment of pathogenicity; it is a literature-count criterion, so mapping Cfrm onto pathogenic would write a judgement the source declines to make. The second is somebody else's instrument entirely — the ClinGen mtDNA VCEP's five classes, which is exactly what VALID_CLIN_SIG already carries — so the five abbreviations became keys in the one shared normalizer (@one-normalizer-two-spellings) rather than a MITOMAP-local map that would then have to agree with it.

[VUS*] is withheld, and the withhold could not be left to the normalizer. It is not the legend's footnote marker (a diamond, printed inside the bracket), not a sixth class, and not APOGEE's [VUS+]/[VUS-], which leak into rtmutation on one row each from a seven-tier in-silico predictor sharing three letters. Nobody wrote down what it means. The subtlety is that normalize_clin_sig's own default is other — a definite member of the vocabulary, not an unknown — so an unmapped token falling through would have become a confident call. mitomap.vcep_clin_sig therefore decides membership before anything is normalized, and the withheld brackets are counted in the snapshot's release.json rather than folded into VUS.

Both tables, and that was settled before the build. reference_examples/mt_heteroplasmy carries two variants and both live in rtmutation; neither is in mmutation. An mmutation-only lane would have drafted nothing the repository's one mtDNA module needs — and shipping one table and discovering the sibling later is how RM164 happened.

What the first build measured, on the ClinVar of its own day

The entry owed a rejoin rather than a quotation, and the rejoin moves the number the entry was about. Against clinvar_file_date 2026-06-27 (3,104 distinct chrMT alleles) and the dump served on 2026-08-24 (mmutation curated through 2026-08-21, rtmutation through 2026-08-19):

photocopy rated miss unrated miss unmintable
mmutation (602) 352 3 218 29
rtmutation (494) 303 3 170 18

Six rated misses, not sixteen — and the difference is not a disagreement with the probe. The probe counted 16 bracketed mmutation rows absent from that same snapshot, and all 16 reproduce. Thirteen of them are : deletions, which the design's own §6 puts in the unmintable count until an enricher pass anchors them; the three that remain are insertions the schema can spell. The sibling table contributes three more of the same kind. So the motivating number was never sixteen new draftable calls — it was sixteen rows, thirteen of which the same document says this tier may not mint. That is the sharpest possible argument for the rule the entry shipped under: the number is derived, never stored.

Every one of the six keys on an indel, which the lane publishes rather than hides. The join is exact and neither side is left-aligned, so a miss on an indel key is either an allele ClinVar does not carry or one it carries at another anchor, and this lane says which it cannot tell you.

The nlmid walk, which the strategy left owed on a sample of four. All 6,770 reference rows were walked: 6,372 carry a bare-digit PMID, 397 state none, and exactly one states 01930224-202601000-00006 — an Ovid article id whose first eight characters are digits, which a substring search would have cited as somebody else's paper (@pmid-vs-pmcid, one registry over). So nlmid_pmid requires the whole cell to be a digit run, deliberately stricter than spec.extract_pmids. The increment carries 802 citation links for its non-photocopy rows.

One more finding the build turned up, reported and not repaired. One drafted row's allele name states a variable number of copies (T961delT+ / -C(n)ins) while its allele columns state one definite pair (T→CC) — the source disagreeing with itself about definiteness. The row keeps MITOMAP's own ref/alt, because dropping it would discard a published call and rewriting it would need a rule for what (n) means that MITOMAP has not given; the drafter names it, on a row the author has to curate by hand anyway (@multiplicity-is-a-finding).

genotype is stubbed, and the reason is not the contig's

This is the departure worth recording, because the house already has a rule that points the other way. clinvar_draft.sole_expressible_genotype fills the ALT on chrMT — a haploid contig leaves no zygosity open, so the placeholder is protecting a decision that does not exist (S6, @placeholder-protects-decision). That argument is right about ClinVar, whose record is a claim about an allele. MITOMAP's row is a claim about a literature corpus: homo and hetero are presence flags saying whether the variant has been reported in each state, and on the real increment three of the six drafted rows are reported only heteroplasmically. Writing genotype=<ALT> there states the homoplasmic reading — which is precisely the claim reference_examples/mt_heteroplasmy keeps in variants.csv and separates from its heteroplasmy.csv bins. So the cell is stubbed, the flags MITOMAP did publish go in front of the author per row as an uncapped worklist, and a MITOMAP-drafted module cannot compile until a human writes those cells. That is the cost of this adoption and it is stated rather than engineered around.

The five places the build departed from the plan

Recorded here and as a dated addendum on PROPOSAL_0_7_PT3, because a silent contradiction of a build plan is worse than a noisy one.

  1. The lane is mitomap_miss; mitomap-miss is accepted everywhere and folds to it. The registry is walked by identity — resolve_<name>_reference, <NAME>_SUBDIR, <name>_build.py — so a hyphen cannot be a lane name. drug_labels is the precedent, and caches.lane_name returns the declared member rather than the caller's spelling (@vocab-separator-slip).
  2. The command is draft-panel --source mitomap-miss, not a bare draft --source: draft is the CPIC command and draft-panel is the one that writes variants.csv + studies.csv from a --source vocabulary. --gene became optional for this source alone and is still refused as absent for the other three — the increment is asked for as a whole, where an unfiltered ClinVar draft would be the whole snapshot.
  3. dataset comes from the dump's own edit_date, not from HTTP Last-Modified. The ClinVar precedent the design names is ##fileDate — a statement the file makes about itself — so a build from a local dump produces a label a downloaded one can be compared against. Both tables' dates, because both are adopted and they are curated separately; the header and the sha256 stay in release.json, where provenance of the fetch belongs. The increment's own label is that plus the ClinVar release, since a derived artifact's identity is the pair it came from, and it is withheld entirely when either half is unknown.
  4. The child carries its own citations parquet, for the non-photocopy rows only, so the drafter reads one snapshot rather than two — the alternative lets a draft run against a MITOMAP snapshot that is not the one the join used.
  5. STATE_BY_CLIN_SIG moved to clin_sig.py. pubmind_draft was already importing it out of clinvar_draft; a third caller made the private home indefensible, on the normalizer's own argument.

What it deliberately does not do, and what is still open

Never maps a confirmation token; never maps [VUS*]; never drafts a photocopy; never left-anchors the : deletions in the format or compiler tiers; and never puts a count in a constant — the tests assert relationships (a miss key is absent from the parent, a photocopy key is present, a rated-miss clin_sig is the normalizer's image of its bracket, the four buckets partition the source rows, a child whose parent pin does not match the parent on disk is stale).

Still open, and none of it blocking (RM285 carries the first three, filed 2026-09-27; the third, the anchoring pass, shipped as RM293): VUS* is withheld rather than understood — a legend, or McCormick 2020 read in full, would revisit it, and until then a rated-miss count that silently included those rows would be a lie. The 388 unrated misses are a real identity increment with no mappable class, counted and not drafted; whether their identity earns a row at all is a second, smaller call. The : deletions want an enricher pass that anchors them against the rCRS — legal in that tier, which may fetch. Indel normalization would turn the left-alignment caveat into an answer. And publishing the MITOMAP snapshot to HuggingFace is outbound and stays the maintainer's: the lane has mitomap publish and CC BY 3.0 permits it, but nothing has been uploaded. (Stale by 2026-09-03: just-dna-seq/mitomap was published that day, commit dd99d54e; confirmed 2026-09-27.) The derived child is deliberately unpublishable for a fourth reason that is neither a refusal nor an unestablished permission — a pulled copy would carry a currency check its holder cannot run.

Related RM164 (where it was found), RM176 (the registry it extends), MITOMAP_STATUS, rm171_diff_strategy, @one-normalizer-two-spellings, @lookup-with-a-default-hides-a-new-member, @tautology-zero, @currency-asks-the-source-not-the-cache, @stub-cannot-compile, @probe-names-the-table.

Correction, 2026-09-27 (RM273). The six rated misses above were measured by an exact join on spelling, and five of them are ClinVar's own calls at another anchor (7471 C>CC and 7472 A>CA are ClinVar's 7465 A>AC; 8618 T>TT is 8617 A>AT). The lane now compares events against a vendored rCRS, and on the same parents it reports one rated miss (likely_benign) and 663 photocopies. RM293 then anchored MITOMAP's 39 : deletions, and the lane reads two rated misses and 686 photocopies.

RM176 — eleven builders, three stages each, and the roster that was supposed to name them was a list

Severity high · Status ✅ SHIPPED 2026-09-02 in the uncut 0.7.0 — the cache registry, three missing resolvers, three new publish/provision pairs, and cache rebuild (just-dna-enricher; no schema, no vocabulary, no parquet column) · Owner enricher · Motivating case the maintainer's 2026-09-02 question — do all the caches we build have a common rebuild endpoint, and does each have download, build and upload? — asked of every lane except Ensembl

The answer was no, and the three gaps were one defect wearing three faces. Every one was a fact about a lane that no code anywhere asserted, because the roster was a four-tuple list inside cli.py.

  • Three lanes were not in it at all. acmg_build, strchive_build and drug_labels_build existed and had no roster entry, so cache status reported nine caches on a machine that has twelve and cache pull refused the other three as unknown names.
  • Those same three had no resolver. Each check took an explicit path and looked nowhere else, so the only way to run one against a built snapshot was to name it on every invocation. The path a deployment actually takes is the flagless one, and for all three it did something worse than fail: ACMG's fell through to scraping NCBI's page, which serves v3.2 while the snapshot holds v3.3, so a correctly authored row came back reported as wrong; the other two skipped themselves with no_reference about a catalogue sitting in the cache directory.
  • Three lanes had the licence to publish and no way to. The roster's own comment called CIViC's absent ensure_* a gap rather than a refusal — CC0 grants redistribution outright — and STRchive's MIT and the drug labels' CC BY-SA say the same on their own terms. What was missing was plumbing.

What shipped. caches.CACHE_LANES is a registry: one entry per lane, carrying its three stages (acquire, build, publish) and, for each stage it lacks, the reason as a field rather than a comment. test_cache_lanes.py walks it against the *_build modules on disk in both directions, which is the check a list could never have (@registry-completeness). Resolvers and cache subdirectories for acmg, strchive and drug_labels, each wired into the flagless branch of its own check, and the tests assert the call rather than the resolver — a resolver nothing calls passes its own unit test while leaving the defect exactly where it was (@ensure-must-be-called). Publish and provision for CIViC, STRchive and the drug labels, with strchive publish and clinpgx publish-labels as new commands. And cache rebuild, the endpoint the question asked for: one command over eleven builders, calling the same download_*/build_* the per-lane commands call, so there is one conversion algorithm with two callers rather than two that have to agree.

And cache prepare beside it, which is the command a deployment actually wanted. cache pull fetches the published snapshots and stops, so a machine that only pulled is short exactly the four lanes nothing publishes — and those four are unpublished for recorded reasons, which means the gap was permanent rather than pending. prepare runs each lane by the route it has, pulling or building, and the route is a property of the lane rather than a flag: asking an operator to choose would be asking them to restate the licensing story. It leaves a present cache alone, like pull, and stages a built one beside its target rather than writing into a live cache directory — a build there is visible half-done, and unlike a truncated download no footer check catches it because the file is real. prepare_caches and rebuild_caches are the Python halves, returning one outcome per lane in registry order.

Two shapes had to be generalized to get there, and both were premises rather than bugs. The publisher assumed every snapshot is data/*.parquet; ACMG's is acmg_sf.csv and STRchive's is STRchive-loci.json, each at the snapshot root. plan_reference_snapshot now takes the payload filename from its caller — a lane knows what it builds, and a roster of lane filenames inside the publisher would make it the fourth place a new snapshot kind has to be taught about. The provisioner could not be generalized the same way and is not: _provision_snapshot is parquet all the way down and a JSON file has no footer to check, so _provision_root_file_snapshot gives the same guarantee by parsing before the rename.

publish_reference_snapshot now derives its allowlist from the plan instead of restating it as patterns. The two were separate statements of one thing that had to agree and twice did not — that is how citations/ and LICENSE.txt each went a release printed-in-the-dry-run and dropped-on-upload (@publisher-allowlist-derived). One list, so a dry run is a promise.

The rebuild outcome is three-valued, and the third state is the item's most load-bearing decision. ACMG needs a workbook that is Elsevier supplementary material, PharmVar a personal key, CIViC a release date to pin, Ensembl is built by just-dna-pipelines. Folding those into failed would have a nightly rebuild alarm on four lanes behaving exactly as their licences intend; folding them into built would be a lie. They print as not run with the registry's own reason, and the exit code counts only real failures. Each lane builds into <base>/<lane>/, never in place — a rebuild takes minutes and a short parquet still has a PAR1 footer, so an enrich reading a half-written snapshot sees a real but incomplete table and no resolver can catch it.

Two defects the suite caught rather than review, and both are the repository's own recorded shapes. clinpgx publish-labels had landed after the __main__ guard, where nothing registers it. And cache status composed its instruction as f"{name} build", which is right for ten lanes and names two commands that do not exist — there is no drug_labels build and no constraint build — so build_command is a field the guard invokes against the real Typer tree (@warning-text-is-api).

The dependency question the item also asked was already answered: every builder-only dependency (polars, openpyxl) is in the [dev] extra behind a guarded import, and no runtime check reads either. Nothing moved.

Four defects its own probe found, after the round looked finished, and three of them are the item's own shapes turned back on it. One: the default cache pull exited 1 on a fresh machine, because three lanes gained an ensure_* before anyone created their repos and the transport's error reached the blanket handler as a failure — nobody-published is the same third state as nobody-asked, so SnapshotNotPublished is its own type and is printed rather than counted. Two: Path("./x.xlsx").as_uri() raises, so --source acmg=./workbook.xlsx — the documented invocation — produced a traceback instead of an outcome. Three: the PharmVar adapter reported every exception as not run, folding a lane that broke into a lane that opted out; the split is decided before the request now, from whether a key is configured at all, because the service's 401 is identical for an absent, a malformed and an unrecognised key and a flat PharmVarError cannot carry the difference (@answered-is-not-absent). Four: the CIViC adapter fetched the release VCF unconditionally, which RM169 made opt-in because it widens the status basis — so one release would have built two different snapshots depending on which caller asked, the exact fork this endpoint exists to prevent.

And two more the maintainer's question found, both @credential-where-read. Asked whether the endpoint handles credentials kept in a .env, it did not — for $PHARMVAR_API_KEY and $HF_TOKEN, the two the operator actually holds. The PharmVar one is the worse of the pair and is this round's own tri-state repair turned against it: the guard deciding no key configured versus a key that failed read os.environ directly, while PharmVarClient.__init__ calls load_env() before reading the same variable — so the key was visible to the builder and invisible to the check standing in front of it, and the lane claimed the designed third state on exactly the machine most likely to have a key. A pre-check that answers differently from the code it guards is worse than no pre-check. $HF_TOKEN failed honestly by comparison: _hf_api called get_token(), which reads the real environment and ~/.cache/huggingface/token, so a publish refused. Both load where the credential is read now, and the probes run in subprocesses with the real variables stripped and HF_HOME redirected — otherwise they pass on any laptop that has ever run hf auth login.

Left undone on purpose. The three new repos — just-dna-seq/civic, just-dna-seq/strchive, just-dna-seq/clinpgx_drug_labels — do not exist on HuggingFace; the first publish creates each, and until then both ensure_* and cache pull say so rather than failing obscurely. No lane's snapshot was rebuilt or uploaded as part of this. And the PGS/PRS parquets under just-dna-seq are out of scope by decision, not by oversight: pgs-catalog, prs-percentiles, prs-sample-scores and polygenic_risk_scores are built by just-prs's Dagster pipeline, and pulling them into this tier would cross the dependency-tier rule the charter's Goal 2 states.

RM175 — the PGx lane's default archive was a retired filename, and every row it had ever built came out of a frozen 2025 object

Severity high · Status ✅ SHIPPED 2026-09-02 in the uncut 0.7.0 — the rebuild onto summaryAnnotations.zip plus the guard that refuses the retired one (just-dna-enricher; no schema, no vocabulary, no parquet column) · Owner enricher · Motivating case the maintainer's 2026-09-02 investigation (CLINPGX_ARCHIVES), which started from RM173's canary and found what it was a canary of · Supersedes RM173

PharmGKB renamed the table on 2025-07-29 (the ClinPGx launch post): "Clinical annotations … are now called summary annotations." The archive followed. clinicalAnnotations.zip was last written to S3 on 2025-07-05, twenty-four days before that post, and has not been rebuilt since; it is on no downloads page; and the API still answers it 200 through a 303 to the frozen object. clinpgx_build.DEFAULT_CLINPGX_URL named it.

So this was not a stale cache and not a slow source. Every annotations.parquet this lane had built, every PGx row drafted from it and every check that read one rested on a snapshot of the database as it stood fourteen months ago, and nothing in the response said so — a retired filename that still 200s is indistinguishable from a live one at the HTTP layer. RM173 measured the 13-month gap correctly and diagnosed it as two live surfaces refreshing out of lockstep. It was one live surface and one leftover.

What shipped

summaryAnnotations.zip, CREATED_2026-08-05, is the same 15-column table under new names:

2025 archive 2026 archive
clinical_annotations.tsv summary_annotations.tsv
clinical_ann_alleles.tsv summary_ann_alleles.tsv
clinical_ann_evidence.tsv summary_ann_evidence.tsv
clinical_ann_history.tsv summary_ann_history.tsv
Clinical Annotation ID Summary Annotation ID

The other fourteen column names are identical and in the same order, and Phenotype Category has the same values with the same ; separator, so no vocabulary moved and no model changed. The builder reads two of the four members; the evidence and history siblings are renamed upstream and named nowhere in this tier, so they cost nothing. What changed is the URL, two member names, the id column, the numbers derived from the old file — and the guard.

The guard is the item. An archive carrying the old member names parses perfectly and yields a plausible parquet, so require_current_archive reads the member names before anything else and answers in three arms (@answered-is-not-absent): the current spelling builds; the retired one is refused with the rename, its date, the retired filename and the URL to build from instead (@specific-rejection — a generic "member missing" is a dead end where naming the rename is a fix); an archive that is neither says so separately, listing what it holds. clinpgx build prints CLINPGX BUILD FAILED: … and exits 1, matching build-labels.

Both spellings live in one table the reader takes its member names and its id column from, so the guard cannot drift from what the builder reads (@suppression-from-merge-key has the same shape). RETIRED_ARCHIVE is returned by nothing: no path through the module can read a 2025 archive, which is stronger than refusing to. No compatibility layer was built, deliberately — a reader that parses both vintages is a reader that can still publish 2025 data.

It was not a rename-only patch, because the data moved. Re-derived against both archives on 2026-09-02: over the 5,179 ids in both, 7 annotations gone, 11 new, 8 rows change Level of Evidence, 2 Variant/Haplotypes, 40 Drug(s), 14 Score, 68 Level Modifiers, and every URL rehosts pharmgkb.org → clinpgx.org on a path that still reads /clinicalAnnotation/. At the snapshot's own grain the rebuild is 16,087 → 16,117 rows across 5,186 → 5,190 annotations, 1,086 → 1,087 genes: 22 (annotation, genotype) keys gone, 52 new, and among the 16,065 shared keys 30 rows change evidence_level, 120 drugs, 47 annotation_text, 38 phenotypes and 4 subject. The parquet digest moves, and a module drafted from this lane can see an evidence level change under it — which is correct, and is the first thing this lane has ever had to say about currency.

And one recorded number was wrong twice. clinpgx_build's docstring said "4,618 of 5,113 carry exactly three" genotype rows. 4,618 is the 2025 file's three-genotype count and 5,113 is neither file's annotation count (5,186 then, 5,190 now) — it is the distinct-key count of the clinicalVariants rollup. The pair appeared in five live files. It is gone from all of them, replaced by the relationship ("the large majority carry exactly three") rather than by a fresh count: a number measured off one download is exactly what this item is about. The fixture-bearing measurements that are dated but true — 396 of 16,087 rows with a multi-gene cell (RM74), 15,331 of 16,087 with a gene, 1,199 of 17,380 colliding triples (RM29b) — were left as the release-time evidence they are.

The fixture is real bytes now. assets/clinpgx_annotations_slice/ is cut verbatim from the 2026-08-05 archive: the real LICENSE.txt and CREATED_*.txt, the three rs4149056/simvastatin annotations that disagree with each other, and a real CYP2C19 haplotype annotation replacing an invented id the old in-memory fixture carried. Every expected value is computed from it at runtime, and the retired-vintage archive the guard is tested against is the same rows under the old member names and the old header — one copy of the data, two spellings, so the refusal is proved against an archive that would otherwise have built.

The general half, which is why this was severity high and RM173 was not

A filename can retire while its bytes keep serving, and nothing in this lane could have noticed: the download succeeded, the members parsed, the licence read, the row count was plausible, and release.json recorded a CREATED_*.txt nobody compared against anything. Three candidate guards were listed when the item was sized, and none was built — the item is a rebuild, and each of the three is a design in its own right:

  • Audit every default URL in the lane against what the source lists. ClinPGx serves 19 zips; drugLabels.zip, relationships.zip and clinicalVariants.zip are all on the page and clinicalAnnotations.zip is not. A one-off read, not machinery — and one that needs a browser, per the trap below.
  • Record the S3 Last-Modified beside the CREATED_*.txt in release.json, so an archive that stops being rebuilt is visible in the artifact rather than only in the source.
  • Fire when one archive of a multi-archive source is much older than its siblings — the shape RM173 stumbled into, generalised. @two-surfaces-two-denominators is the neighbour, and @currency-asks-the-source-not-the-cache says the question goes to the source.

The name check that shipped is narrower than any of them on purpose: it catches this failure — a retired name still serving — at the only moment the lane can see it, without claiming to detect staleness in general. Nothing built here would notice summaryAnnotations.zip itself going quiet, and that gap is the honest remainder (RM283, filed 2026-09-27).

A trap that cost the investigation real time, and belongs in the record. Every ClinPGx HTML route — /downloads, every help page — serves the same JS shell whose no-JS body is "Javascript Is Disabled!". curl and WebFetch therefore cannot answer "is this file listed?", and both return 200 while telling you nothing. The downloads listing in the probe is a rendered-DOM capture from a browser. Treat a no-JS fetch of this host as no evidence at all (@probe-the-real-file, one host further on).

Related RM173 (closed into this), RM166 and RM29b (both built on the lane this rebuilds), RM164, @two-surfaces-two-denominators, @currency-asks-the-source-not-the-cache, @probe-the-real-file, @pgx-research-only.

RM166 — the whole PGx lane is one licence class, and a second authority exists that is not in it

Severity low-medium · Status ✅ SHIPPED 2026-09-01 in the uncut 0.7.0 — the cross-check built, the licence half closed measured (just-dna-enricher, plus one VALID_VERIFICATION_CHECKS member; compiler/ untouched) · Owner enricher · Motivating case the 2026-09-01 source-adoption round

The item split, and only one half is code. What builds is a drugLabels.zip builder beside clinpgx_build — the same cache, the same payload-read LICENSE.txt handling, its own CREATED_*.txt and therefore its own release.json — and a regulator-label cross-check joining at two tiers, the star-allele tier where Variants/Haplotypes supplies one and the gene tier otherwise, with the tier distinguishable in the finding because a gene-level agreement and an allele-level agreement are not the same claim.

The half that closes is the one the item was filed for, and it closes on measurement rather than on deferral. The entry wanted a PGx lane member whose terms may not gate. Both routes refute it: the ClinPGx route is CC BY-SA + no-sale, the same gate, so it diversifies nothing; and the FDA's own Table of Pharmacogenetic Associations is 126 associations in an HTML page with no bulk download and no copyright or public-domain statement on the page at all. "US government work is public domain" is a rule with exceptions, the entry said so, and the page does not settle it. So the direct route supplies a quarter of the FDA content ClinPGx already carries, in a shape that must be scraped, on terms that are unestablished. Leaving that half open would have left an item riding on a source shown not to serve it. If licence diversification for the PGx lane still matters — and it plausibly does, being a single point of failure on the axis the format gates on — it wants its own entry (RM282, filed 2026-09-27), with candidates chosen for their terms first, which is the opposite of how this one chose.

It is five regulators, not one, and the surface is named for the labels. Source counts: FDA, Health Canada, EMA, Swissmedic, PMDA. The entry asked for the FDA and the file supplies four more at no extra cost, which turns the concordance shape from module ↔ authority ↔ authority into a lane where the number of authorities is a parameter — exactly what RM134's vocabulary split was built to survive. Naming any one agency in the surface would bake an authority into a published key, the mistake RM134 caught in ClinSigConflict before it shipped.

The join key exists, contra the entry's own closing worry. Genes is populated on ~87 % of rows and Variants/Haplotypes on ~15 %, and the star-allele tokens in the latter are haplotypes.csv's key verbatim. So "a check with no key to join on is not a check" is answered: a gene-level key for most rows, an allele-level key for a sixth, and the sixth is where this lane's rows actually live.

A blank Testing Level is unknown and withholds. Roughly a third of the file states none, which is an absence and not a no: reading it as No Clinical PGx would manufacture a negative regulatory claim on 472 rows. Kleene, not a default — and the levels the snapshot states that the vocabulary does not know are collected and reported rather than folded into an "other" bucket (@lookup-with-a-default-hides-a-new-member).

It warns in both modes, like every other cross-check in this round: five expert regulators genuinely disagree with each other and with a curator, and failing would make the format arbitrate between its own authorities (@clinsig-never-escalates).

The finding that outgrew the item, noticed and not built. ClinPGx publishes at least twelve archives and clinpgx_build reads one. clinicalVariants.zip is the one bearing on a shipped table kind — ~5,190 rows of pharm_variants.csv territory, whose type is a six-member base vocabulary that comma-combines, so any adoption normalizes the combination rather than the token. The honest restatement is that the PGx lane reads one of twelve files from a source it has already adopted and gated, and the FDA question was a narrow way into a broad finding. It wants its own number, filed as RM281 on 2026-09-27.

What the code review found after the item was written, and it is a shape rather than a slip. The lane shipped a VALID_AUTHORED_POSITION holding five members while just_dna_format.vocab already had that exact name holding five different ones — the clinical-significance concordance axis. Nothing broke, because one test file imported one and another the other, which is precisely what made it dangerous: the collision is invisible until a third caller imports both and the later from … import wins silently, and two members are shared so even a spot-check passes. A lane-local vocabulary carries the lane's prefix, and the rule is now @a-lane-local-vocabulary-may-not-shadow-a-schema-one. Its related half: a reason map only a test reads is a map nothing speaks — the equality guard over the sentence maps passed while every actual reader still met a bare token with no statement of what it claims.

The same pass corrected two measurements this entry would otherwise have preserved. An allele claim whose gene-tier sibling was never answered had been counted as no label names this allele, when the truth is that nothing was asked about its gene either; it is withheld, and the three buckets are now asserted as a partition rather than checked one at a time. And the gene-qualified join composes a token two ways, because the file spells it two ways — the star alleles run together (TPMT*3A) and the DPYD haplotypes are spaced (DPYD c.2846A>T) — so trying only the concatenation told a DPYD module its allele was named by no label while two regulators named it exactly. A false coverage claim, which is worse than a miss.

@two-surfaces-two-denominators is the live rule: ClinPGx's bulk file and the FDA's web table are different sources with different denominators, and any count either produces must say which. And clinpgx_build's own docstring records that relationships.zip was a year newer than clinicalAnnotations.zip, so this archive carries its own CREATED_*.txt rather than inheriting the lane's release.

Probed and decided in PROPOSAL_0_7_PT2, which proposed 0.8 and was overturned: largest in the batch and least urgent is an argument about order, not about the release. It was sequenced last so that an early cut would leave one item in flight rather than four.

Related RM134 § B, RM29b, @pgx-research-only, @two-surfaces-two-denominators, @clinsig-never-escalates, @acquisition-gate-is-not-a-read-gate.

RM167 — LitVar2/PubTator3 answers "which papers name this allele", which is the half PubMind structurally cannot

Severity medium · Status ✅ SHIPPED 2026-09-01 in the uncut 0.7.0 (just-dna-enricher, plus one VALID_VERIFICATION_CHECKS member; compiler/ untouched) · Owner enricher · Motivating case the measured limits of the PubMind adoption (RM134)

The entry set its own test and the test passes. PUBMIND_ASSESSMENT measured that PubMind has record identity, not variant identity — 68,744 coordinate keys carry more than one PVID, HFE C282Y alone holds eight with four different verdicts — and the entry proposed LitVar2 as an independent second vote on exactly that fan-out, "complements if LitVar's identity is genuinely allele-level". It is. BRAF rs113488022's three CAIDs resolve to three distinct ALTs at one position and carry 31,276 / 99 / 41 papers: allele resolution doing real work, three orders of magnitude apart.

The finding is that the tier a locus is answerable at is a property of the LOCUS, not of the source. APOE rs429358's position node carries 3,945 papers and its single allele node carries 328, so 92 % of the literature at that locus is not allele-resolved. A pass reporting the allele node's count as the answer would understate it twelvefold. So the shipped pass names which tier answered: allele-resolved, position-only, absent — plus unchecked as the fourth state the house algebra needs — each arm with its own reason sentence, the fall-back to the position node never silent (@refutation-withholds: a position-level answer to an allele-level question withholds rather than answering approximately), and the position-only residue counted over the union of every allele node rather than folded into the matched one (@dont-discard-computed).

It writes no row, which was pre-authorised and is a complete outcome rather than a half-done one. A PMID list per variant is not a table kind, literature.csv is keyed by article, and sources.csv means this module uses this source, which would be false here. What lands is one literature_coverage attestation.

The corpus measurement, which the entry made the build's first task. Over the 11 reference modules carrying a resolution.csv — 389 loci, of which 180 (46.3 %) have at least one CAID node: 165 answered at allele tier, 92 at position tier only, 122 absent, 10 could not be asked. 14,168 papers sit on a position node no allele node claims, 6,700 of them APOE's.

Three of the proposal's own numbers did not reproduce, and that is the round's shape again. Its "of 588 HFE nodes … 299 are gene-level" conflates two id shapes: measured off the recorded payload there is exactly one gene node (3,285 papers) and 298 text mentions, which is a fifth shape (litvar@#<gene_id>#<protein_name>, all three flag_* false) and not a variant at all. The 423-locus join does not reproduce — a roster derived from DRAFTABLE finds 389 loci and 388 distinct rsIDs. And the stated id grammar litvar@<clingen_id>#<rsid>#<gene_id> is contradicted by the proposal's own example: litvar@rs1800562## puts the rsID in the ClinGen slot, so the field count varies by tier rather than the slots being fixed.

The bound ships with the pass, in its own documentation. Measured against the two records this workspace could not resolve — CIViC 1955 and 2131, worked down in CIVIC_LEGACY_INSERTIONS to four candidate alleles with registered CAIDs — LitVar returns no node for any of the four, and the one nominal hit for VHL P71fs is an unrelated paper that happens to write the string. The reason is structural: PubTator3's export for all four source papers is title and abstract only, with zero variant annotations, and the alleles live in a table inside a paywalled paper. So on precisely the class this workspace built a protocol for, LitVar is the wrong instrument — it answers which papers discuss an already-identified allele and never which allele this name meant. Those read as the same question and are not.

data_clinical_significance is not adopted in any form. It is populated on position nodes and None on every allele node measured, so it is position-level, unattributed, undated, and cannot even be attributed to the allele it would be voting on.

Two API facts pinned before anyone writes a second client. variant/search/gene/GENE returns line-delimited Python repr(), not JSON — .json() raises on it, so the shipped client parses rather than deserializes (@probe-the-real-file). And NCBI publishes a policy, not a licence: it places no restrictions and in the same passage declines to grant permission, so under @no-named-licence every gating axis is None. Recording it as public domain by analogy with ClinVar is exactly the move that rule forbids — ClinVar has a page saying so and this surface does not. NCBI's side only; nothing is asserted about EMBL-EBI's terms for surfaces EBI co-hosts.

It also repaired a defect one file over. clingen_allele._parse computed a one-sided allele and then discarded it whenever an rs-number arrived, because the rsID alone makes the outcome resolved — so every PALB2 indel read as incomparable. unanchored now travels on a resolved result too.

Probed and decided in PROPOSAL_0_7_PT2, which reversed twice: an earlier draft proposed CLOSES on a misread id, the file then proposed BUILDS in 0.8, and the maintainer pass took it now — the three stated blockers were a small client, a tiering rule that is the item's own result, and an artifact question the entry had already pre-authorised.

Related RM134, RM153, @existence-not-identity, @probe-the-real-file, @no-named-licence, @refutation-withholds, @dont-discard-computed.

RM165 — repeat_alleles.csv has no source, and RM65/RM66 have been waiting on exactly the corpus one would bring

Severity medium · Status ✅ SHIPPED 2026-09-01 in the uncut 0.7.0 (just-dna-enricher, plus one VALID_VERIFICATION_CHECKS member; compiler/ untouched) · Owner enricher · Motivating case RM65's own stated prerequisite

What shipped, and the split is the finding rather than a caution. STRchive — dashnowlab/STRchive, MIT, 82 loci across 79 genes — is adopted by column: a check-repeat-bands cross-check over benign_*/intermediate_*/pathogenic_*, and a draft-repeats provider over the identity half. Two commits, so the check is revertible without the provider.

The reason the bands are checked and never drafted was measured on both corpus modules, and it is one agreement and one disagreement. STRchive reproduces htt_repeat_expansion's first two bands exactly — benign 6–26, intermediate 27–35, independently authored, about as strong a validation as a drafting provider can get before it is written. And it gives FMR1 a single intermediate 45–200 where the module has 45–54 and 55–200: the boundary it does not have is 55, the premutation threshold, and the module's own conclusions name what would be lost — the 45–54 grey zone where "the carrier is not at risk, but the allele may be unstable in transmission", and the 55–200 FXTAS/POF range. Drafting the three bands straight would have erased a clinically load-bearing line in one of the corpus's two modules. The finding names the missing boundary rather than reporting that the tables differ.

pathogenic_max is emitted nowhere, and this is the second refusal worth keeping. STRchive gives HTT 250 where the module leaves measure_max empty. A catalogue's pathogenic_max is the largest allele the literature reports — an observation, not a clinical bound — and written as measure_max a 300-repeat allele would match no bin at all, silently, --strict included, which is the exact silence RM55 shipped a loud warning about (@bin-grounding). It is reported as its own finding kind instead. @verbatim-except-order is about not re-encoding a source's values; it is not a licence to import a bound the source did not intend as one, and the band's meaning is the schema's, not the catalogue's.

It warns in both modes. Two curators disagreeing about a threshold is not a strict matter (@clinsig-never-escalates), and a strict run reports exactly what a best-effort run reports.

Four things the build contradicted, and the first is the most useful. The identity half is mostly uncarryable: RepeatAlleleRow has no column for coordinates, locus_structure, ref_copies or the OMIM/MONDO disease ids, so a drafted row is gene, motif, trait and a stubbed conclusion. That gap is RM65/RM87 rather than a shortfall in this provider — the entry proposed drafting columns the schema does not have. No DRAFT_PROJECTIONS entry is owed, because the split means the checked columns were never copies, and a test asserts the absence with the reason. HTT is finer than the catalogue too, dividing the pathogenic band at 40, which the entry named only for FMR1. And drafting into a real shipped module exposed a pre-existing crash in just_dna_compiler.draft.append_partial_rows on any table whose header is narrower than its model; it reaches all four existing partial-row providers, was reproduced independently of this work, and is left for its own item because compiler/ was barred this round.

Two things named and deliberately not built. RM66's evidence is real and partial — locus_structure is present on 23 of 82 loci, HTT's being the (CAG)n(CAA)(CAG) structure RM66 asks about, published as typed data with its own three-member vocabulary, while FMR1's is []. That is enough to decide RM66 and not enough to make the answer universal; naming the evidence and stopping was the whole of this round's obligation to it. And STRchive's evidence is a ClinGen-style validity classification on all 82 loci including Disputed 3 and Refuted 1 — a second instance of RM170's problem in a different domain, worth knowing before RM170 is designed against CIViC alone.

gnomAD's tandem-repeat release is out on category, not on terms. gnomAD_STR_genotypes__2022_01_20.tsv.gz is Genotype/Allele1/Allele2/Sex/Age — one row per sample per locus, per-sample genotype data, the one category this format does not carry — so the question of inheriting GNOMAD_TERMS never arises. A category exclusion is cheaper and more durable than a licence answer, because it cannot be renegotiated.

RM65's attached obligation carries forward: _write_resolution_csv's positional pass hard-codes locus_index = 0, honest only while these tables never expand, and repeat coordinates are exactly what could expand one (RM87).

Probed and decided in PROPOSAL_0_7_PT2 — which drafted the provider as held to 0.8 and was overturned: the deferral assumed a cut about to close, and the argument that the split made deferring the larger half cheap reads equally well as an argument that the half is cheap.

Related RM65, RM66, RM87, RM164, RM170, @bin-grounding, @enrichment-is-validation, @verbatim-except-order.

RM163 — pgs.csv is keyed on a Catalog accession and nothing ever asks the Catalog about it

Severity medium · Status ✅ SHIPPED 2026-09-01 in the uncut 0.7.0 (just-dna-enricher, plus two VALID_VERIFICATION_CHECKS members in just-dna-format; compiler/ untouched) · Owner enricher · Motivating case the 2026-09-01 source-adoption round

What shipped. A fourth registry in identifiers.py and a pgs.py client asking the PGS Catalog about every authored pgs_id, PGS_TERMS as a per-score licence floor, and pgs_catalog as the second member of currency.default_probes. It attests under two names — pgs_accession_currency and pgs_metadata_agreement — because currency asks whether the id still names a score and drift asks whether two cells beside it still match: different questions, different subjects, different denominators, and one record over two populations publishes a findings count that means nothing.

The verdict is read off the body, never the status. GET /rest/score/PGS999999 — a never-assigned id — returns HTTP 200 and {}, and so does GET /rest/score/PGSXXXX, which is not a well-formed accession at all. So the status code carries no existence information and a withdrawn score, a typo and a malformed id are indistinguishable by construction. @existence-not-identity, and RM153's warning about a 200 that is not an answer arriving in a second source.

And the absence message is weighted by a measured base rate, which is @rsid-absent-two-readings run backwards. About 35 % of the accession range is assigned, so an unrecognised pgs_id is overwhelmingly a never-assigned one. dbSNP earns its equal-weight treatment because its id space is densely assigned and merges are a frequent, real event; here the base rate runs the other way, and naming withdrawal as a co-equal reading would send an author looking for a retirement notice that almost certainly does not exist. The message states the absence, states the sparsity, and names withdrawal as the rarer reading — and where the Catalog offers no supersession field at all, that is stated as a limit of the source rather than resolved by guessing.

Drift is over two fields, not the four the entry named. Reading the model rather than recalling it: match_rate_floor is described in its own Field as "Author-set variant-match floor" and research_tier is a two-member curator judgement. The Catalog publishes neither, so there is nothing to drift them against, and a check with no source-side value is a check that cannot fail (@tautology-zero). The reason is written down where somebody would otherwise add them later. What is checked is training_ancestry against ancestry_distribution and training_cohort against samples_training, reporting and never repairing.

The licence half is the one that had to be right, and it is a correctness requirement rather than an optimisation. license is a field on each score record, not a property of the Catalog: over the first 250 of ~6,982 scores, most carry the generic "used in accordance with any licensing restrictions set by the authors" string, a handful are academic-research-use-only — the class licensing.py's own comments name as barring redistribution outright — and a couple are CC0. So PGS_TERMS is written as the floor, with EBI's terms-of-use URL and every gating axis None, and each score's own license string overrides it in that score's SourceRow. @licensing-as-data, the shape ClinPGx's bundled LICENSE.txt already uses, and @per-article-terms one source over: the Catalog is a host for scores licensed by their authors. The consequence is visible rather than theoretical — a module naming a single academic-use-only score is now refused by the compile gate by name, where one flat constant would only have warned, and would have been a false claim in the permissive direction.

Currency is read, not built. /rest/info publishes the release date, the score count and the trait and publication totals, so the infrastructure this item wanted did not have to be written — the same finding as MANE's README_versions.txt in RM168, and the second time in one round that a source turned out to publish its own release record.

Four things the build contradicted, all of them recorded. The section's e2e recipe wanted one spec directory carrying a malformed accession beside a live one; PgsRow refuses PGSXXXX at load, so it never reaches the Catalog and the malformed case has to be probed at the client. "A drifted cell is the author's to fix or to answer in overrides.csv" is impossible for these cells — the overlay is derived-tables-only and pgs.csv is authored, so the sentence names a remedy that does not exist and the finding has no silencing route. PgsRow disagrees with itself about which ancestry training_ancestry means: the name says training, the description says "validated in" (RM289, filed 2026-09-27). And /rest/release/current bought nothing over /rest/info, so it is not read.

Severity is deliberately split. An unrecognised accession escalates under --strict; a metadata disagreement never does, because the Catalog and a curator are two authorities and the format does not arbitrate between them (@clinsig-never-escalates).

Probed and decided in PROPOSAL_0_7_PT2. RM16 is not re-opened — that is authored per-variant weights and stays deferred on a missing consumer; PgsRow is a manifest of Catalog ids and this item touched only the manifest.

Related RM16, S86, RM153, @existence-not-identity, @licensing-as-data, @tautology-zero, @rsid-absent-two-readings.

RM168 — the identity procedure downloads MANE by hand, and nothing in the code knows the file exists

Severity medium · Status ✅ SHIPPED 2026-09-01 in the uncut 0.7.0 (just-dna-enricher only; no schema change, no authored column, compiler/ untouched) · Owner enricher · Motivating case CIVIC_IDENTITY_PROTOCOL § 3b

What shipped. MANE_TERMS in licensing.py, a mane/ cache with $JUST_DNA_MANE_CACHE and the default_mane_cache_dir / resolve_mane_reference pair, mane_build.py, a mane build sub-app, a _CACHES row, and an ENRICHER.md lane section. Three files in one pass, together under 1.2 MB: the summary, changed_select_accessions and protein_coding_genes_not_in_mane. Splitting them was refused for a reason worth keeping — the second file is the currency check, so shipping the cache without it would ship the thing this item complains about (a version pinned in prose that nothing will notice going stale) with a cache wrapped round it.

The source publishes its own staleness list, and its own provenance. README_versions.txt is 96 bytes and states the MANE version, the NCBI RefSeq annotation release and the Ensembl release; the builder copies it rather than parsing a filename, because two of those three are in no filename and reconstructing less information than the source hands over is @probe-the-real-file backwards. changed_select_accessions carries Update_Affects_CDS — the numbering-frame axis, stated by the source: a MANE Select change that moves the CDS moves every c. and p. derived in that frame, and one that does not, does not. So the currency check for a numbering frame turns out to be read one small file, not diff two releases.

MANE_status is a column and is never collapsed, which is the decision the item exists for. 74 of 19,437 rows are MANE Plus Clinical (0.38 %), and CDKN2A is the case: two rows for GeneID 1029 with different CDS numbering, NM_000077.5 MANE Select beside NM_058195.4 MANE Plus Clinical. A builder keeping one row per gene would drop them and reintroduce the exact blind spot the table can see and a remembered accession cannot.

And the negative roster is a third state served by the source. protein_coding_genes_not_in_mane lists 222 genes with a reason over a seven-member vocabulary — gene not on assembled chromosomes, gene located on mitochondrial genome, pending MANE review and four others — so "MANE has no answer for this gene" is distinguishable from "nobody asked" (@unreachable-not-absent), and pending MANE review is neither absent nor decided. The vocabulary is derived from the file and asserted as an equality against it, so a reason MANE adds is counted rather than joining an "other" bucket (@registry-completeness).

The bound ships with it: MANE is the default, not the answer. RUNX1 is a single row, and the 27-residue RUNX1c/RUNX1b offset § 3b derived by translating each isoform's CDS is not in MANE and cannot be. The table makes the CDKN2A class of problem visible and is silent on the RUNX1 class, so a pass treating it as an oracle would be wrong in a way the file itself cannot warn about. Said in the lane's documentation rather than left for a reader to rediscover.

Terms: NCBI publishes a policy, not a licence. license=None, license_url at the policy, the two operative sentences in notice, every gating axis None (@no-named-licence). No restriction imposed is not permission granted. MANE is a joint NCBI/EMBL-EBI product and only NCBI's side was read — the terms constant says so, and asserts nothing about EMBL-EBI's. Consequently there is no --use flag on the build and no ensure_mane_snapshot: a declared-use gate whose every answer is a skip is a flag that does nothing (@acquisition-gate-is-not-a-read-gate), and nothing publishes a MANE snapshot to ensure.

Pinned by the versioned directory, never current/. One 96-byte request reads current/ to discover the newest version, and the answer is resolved to a release_<v>/ URL before anything is downloaded — so a build is pinnable after the fact. That distinction became its own gotcha, @current-discovers-a-version-a-directory-pins.

Why it went first. Nothing else in the round depends on it and the identity protocol does: it is the only item that makes an already-shipped result re-derivable — RM159's 33 curated name→identity answers were derived in this frame, and the frame was recorded nowhere a re-derivation could read.

Probed and decided in PROPOSAL_0_7_PT2. Worth recording: of the round's six items this is the only one whose probe the build did not move. Every fact was re-measured live against NCBI while building — 19,437 rows, 74 MANE Plus Clinical, 120 changed accessions with Update_Affects_CDS Yes on 74, 222 excluded genes over exactly 7 reasons, CDKN2A two rows, RUNX1 one, VHL NM_000551.4 — and none of them contradicted the entry. In a round whose keeper is that five of six entries said something their own probe contradicted, the one that held is the one whose questions were cheapest to ask.

Related RM159, RM153, RM152, @snapshot-layout-locations, @release-json-provenance, @current-discovers-a-version-a-directory-pins, @accession-version-names-no-build.

RM169 — the wider basis was published as a dated file all along, and nobody had looked

Severity medium · Status ✅ shipped 2026-09-01 in the uncut 0.7.0 (just-dna-enricher; no schema change) · Owner enricher · Motivating case RM160, whose central premise this item falsified

RM160 was filed on the finding that civic build reads the accepted-only bulk TSV while the API serves 2.35× as much, and it stated the tension as a reproducibility bargain: the API has no dated release to pin, so any wider read costs the snapshot its byte-reproducibility. All three shapes it proposed were ways of paying that price.

The premise was false, and the check was one HTTP request. CIViC publishes <date>-civic_accepted_and_submitted.vcf inside the same dated release directory the builder already reads. It is pinnable, hashable and immutable exactly like the three TSVs. Nobody had probed the download surface past the files already in use — the survey named three TSVs and stopped.

What the file is, and why it is not the input

The whole release surface, enumerated: seven TSVs and two VCFs. (GeneSummaries.tsv is byte-identical to FeatureSummaries.tsv — one file under two names.) The VCF carries one CSQ entry per evidence item, with CIViC Entity Status on each.

But it is a strict subset of the TSV, and the subset is not arbitrary. A VCF record needs a POS, so a variant with no GRCh37 coordinate cannot appear at all. Over 01-Aug-2026 the accepted VCF holds 473 direction rows on 236 variants against the TSV's 533 on 290 — and 52 of the 54 it drops are exactly the unresolvable_identity class, the records whose identity RM159 had to read out of their names. Reading the VCF as the row source would silently discard the hardest-won half of the snapshot.

So the TSV pair stays primary and the VCF is joined onto it, behind --submitted.

What it added, measured

accepted accepted+submitted
Rows 507 1,149
…of which submitted 0 642
Variants 270 397 — 127 of them new
refget coordinates cross-checked 57 129, 0 mismatches
input_rows the drop registry closes over 4,878 8,328

release.json gains status_basis, status_counts, vcf_evidence and unjoinable_submitted, and every row gains evidence_status carrying CIViC's own word. A rebuild on the wider basis is byte-identical, so Principle 7 survives the join.

The second accepted-only file, which is why vcf_csq exists

VariantSummaries.tsv is accepted-only too — a fact nothing had stated. So 112 of the 127 variants the submitted evidence introduces have no row there at all: no gene, no aliases, no HGVS, no registry id. A first cut kept identity strictly TSV-sourced and recovered only 15 of them.

The same CSQ entry carries all four identity cells, so for a variant the TSV cannot describe they are read from there instead — through the same parsers, on the same published identifiers:

route variants
ClinGen CAID only 57
rs-number only 40
GRCh38 accession only 14
both an rs-number and a coordinate 1
total 112

Those rows are stamped identity_derivation="vcf_csq", a member of its own: the routes inside are the ordinary ones, and what the member names is the file, which is the part a consumer cannot otherwise recover. Measured over the emitted parquet, not over the input — 172 rows on those 112 variants, and the other 15 new variants join the TSV normally and take an ordinary derivation.

Nothing is placed from the VCF's own position. It is GRCh37 throughout (##reference=…GRCh37-lite.fa.gz) and lifting it stays refused (RM48); a CSQ-sourced row leaves the civic_grch37_* provenance columns empty rather than recording a coordinate whose build this file never states, and a test pins it.

Two guards the round earned

  • The drop registry caught a real accounting error. A first cut counted submitted items that could not join under a new drop reason — but those rows never entered the evidence list the registry's equality is over, so the input total disagreed with the list the loop walks. The guard raised (@registry-completeness working exactly as designed), and the count moved to its own field, unjoinable_submitted, outside the registry.
  • The vocabulary is enumerated, not computed. The VCF spells members SCREAMING_CASE where the TSV uses title case, and a .title()-shaped rule gets RARE_GERMLINE right and SENSITIVITYRESPONSE wrong — the TSV writes it Sensitivity/Response, with a separator the VCF drops. Three exceptions in twenty members is a map, and it raises on an unmapped member rather than emitting a mis-spelled token (@lookup-with-a-default-hides-a-new-member).

What this leaves for RM160

Its coverage half is answered and closed here. Its provenance half is not: the sweep behind it found that 10 of the 20 records nothing can place gain citations only a wider basis carries, and the VCF reaches none of them — it holds 0 of those 10 and 1 of the 53 unresolvable variants, for the structural reason above. That half still needs the API or nothing, and RM160 stays open carrying it.

RM159 — the identity a source states in a variant's name, adopted rather than left in a probe

Severity medium · Status ✅ shipped 2026-09-01 in the uncut 0.7.0 (just-dna-enricher; no schema change) · Owner enricher · Motivating case the 2026-09-01 residue round (CIVIC_UNRESOLVED)

civic build placed a row from what CIViC puts in its identifier columns — an rs-number, or a GRCh38 RefSeq accession it can parse — and dropped 53 variants as unresolvable_identity. For most of them the identity was published the whole time, one column over: in the variant's own name. N150fs (c.448delA), IVS2+1G>A, D1709N. A c. or protein fragment plus the gene's numbering frame is an allele, and an allele registry holds it.

Adopted: 33 of the 34 that resolved. Coverage over the dated 01-Aug-2026 release goes from 237/290 variants (81.7%) to 270/290 (93.1%), and from 474/533 evidence rows (88.9%) to 507/533 (95.1%). unresolvable_identity falls from 59 rows to 26.

The one excluded, and why it is not an oversight. CIViC 4968 TP53 R72P resolves — rs1042522, CA178298 — and its identity is the reference allele: codon 72 is CCC = Pro on GRCh38, so the name has reference and alternate inverted, and the registry answers NC_000017.11:g.7676154G=. A snapshot row is chrom/start/ref/alt and ref == alt is not a variant row. The identity exists and this representation cannot carry it, which is a fact about the representation.

Why the answers ship as data and the procedure does not run

Resolving a name needs the network, and civic build must stay byte-reproducible from a pinned dated release — which is why the CAID pass (RM153) runs at draft time and never in a build. The obvious repair is therefore "do this at draft time too", and it was refused: four of the 33 required a judgement no lookup makes. A legacy IVS2 name that converts structurally to the wrong exon (788 — the structural answer c.319+1 and the true one c.444+1 are both real registered alleles 9 kb apart, so nothing in a lookup flags the error); a name pairing a missense protein label with a synonymous cDNA change (2459); a protein consequence standing over an intronic allele (804); an rs-number that is position-level where two alleles spell the same substitution (2196). A draft-time resolver would either fail on those or silently pick a side.

So the answer is a shipped constant — civic_identities.CIVIC_NAME_IDENTITIES, 33 rows carrying coordinates, rsID, the CAID as provenance and a note where one was needed — the procedure is written down as CIVIC_IDENTITY_PROTOCOL, and the build stays offline. P9 — zero authored-layer cost, no CSV, no column.

The name is the key, and that is the safety property

Every identity was derived from the name string quoted beside it, so a build applies a row only on an exact name match. Each curated row lands in exactly one of four counted states, published in release.json and asserted as an equality over the walked table (@registry-completeness):

  • applied — the name still matches, CIViC still publishes no identifier, the row was placed.
  • superseded — CIViC now publishes an identity of its own. The source always wins, and a supersession is the cheapest currency signal available: it means the upstream has curated.
  • renamed — the variant is there and its name changed. The answer was an answer to a name.
  • absent — the variant is not in the file. Kept apart from renamed on @unreachable-not-absent: over a full release it means withdrawn, over a slice it means nothing at all.

A curated answer therefore cannot outlive the record it answered, which is what makes a hand-built table safe against the next release rather than merely correct for this one.

What the external check says

civic reproduce cross-examines every placed coordinate against the GRCh38 reference through refget/seqrepo — an unrelated service asked whether the reference base at each position is what the snapshot wrote. It read 24 coordinates before this item and reads 57 of 57 with 0 mismatches after. Every one of the 33 hand-read alleles is confirmed at its stated position by something that has never heard of CIViC.

Two smaller things the adoption fixed on the way

  • allele_registry_id is untouched. It is CIViC's verbatim cell and is empty for all 33 by definition; the CAIDs the probe recovered live on the curated table as provenance. Writing them into the source's column would publish a finding as if the source had made it, and a test pins it.
  • curated_name is its own identity_derivation member, not folded into rsid/grch38_hgvs. Those mean "the source stated this in the column for it", and a consumer must be able to exclude the difference without re-deriving it. The drafter needed no change — it special-cases caid and lets every other member through the placed path — but that is now an equality over the vocabulary rather than a property nobody checked (@lookup-with-a-default-hides-a-new-member).

RM162 — RM_TOC.md is an index, and an index is not an allocator

Severity medium · Status ✅ shipped 2026-09-01 in the uncut 0.7.0 (tooling only — no package, no schema change) · Owner the triage loop · Motivating case the 2026-09-01 collision, git 741ec59

The consumer-suggestion loop has had an allocator for Sn since it was built (triage-state.py --next), because the id is written into a document and a stale one collides. RMn never got one. docs/RM_TOC.md is the complete index of every item — that is what it was written for — but reading a number out of it claims nothing, so the procedure was grep the highest, add one, and write the entry. The window between the read and the write is exactly where a second session reads.

Reproduced rather than hypothesised, and by this loop on itself. On 2026-09-01 two sessions sharing this working tree filed different work as RM159 a minute apart, and the tree carried two RM159 entries pointing at different items. 741ec59 renumbered one to RM161, picking the cheaper move: the other pair was contiguous and already referenced from three probe documents and the enricher reference.

Grepping cannot fix this. Any read-then-write with a gap has the same race, so the claim has to be a single atomic write: .claude/rm-next.py scans every docs/**/*.md and appends the reservation inside one critical section. Scanning outside the lock and appending inside it would be the same defect with a smaller window, so the scan is in there too.

The lock is on docs/, the directory, and the second reason was measured. A lockfile left behind by exactly the kill this guards against would block every later run, and the staleness rule that repairs that is a clock — @flock-not-a-lockfile, the idiom transaction.spec_lock already uses for enrich. The sharper reason is that flock binds an inode: an editor or an atomic writer that renames a new file over RM_TOC.md leaves the holder locking an unlinked inode while a second process opens the new file and acquires immediately. Verified in a sandbox before the tool was written — locking the file would have looked correct and excluded nothing.

A reservation is a visible index row, not a side-car. 🔷 reserved, under the open-items heading, replaced by the item's real row when the entry is written. A number claimed and abandoned is then visible rather than silently burned, and a state file the index cannot see is precisely how a number goes missing — the failure RM_TOC.md exists to prevent. Placement is checked: the file ends in a prose section, and a row appended at EOF would read as part of it, which is the furniture hazard the triage loop's own §6 records one document over.

--release leaves a tombstone, and the first cut of this shipped the bug it fixes. Deleting the reservation row made the number invisible to the scan, so a released RM10 was immediately re-reserved as RM10 — contradicting the rule the tool's own docstring states. Ids are never reused: whatever argued the withdrawal refers to the number, and reusing it makes two items answer to one name in the record. The tombstone has to contain the number literally, since a scan is all that reads it. Found by running the release path rather than by reading it.

Pinned by a guard watched failing. test_rm_allocator.py runs eight allocators at once and asserts eight distinct contiguous numbers — and runs the same eight with flock neutered, asserting they collide. Without that second test the first passes for reasons that have nothing to do with the lock. The unlocked run produced 5 distinct of 8, with one number taken three times.

Also corrected: the loop's own Step 5 hygiene bullet said to read the number off RM_TOC.md, which is the instruction the incident came from, and named RM47 as the highest — a counter in prose, stale for 114 items (@counted-prose-needs-a-fixed-field).

RM161 — a release record's two halves are written at different times, and the second left the first behind

Severity high (a red release gate) · Status ✅ shipped 2026-09-01 in the uncut 0.7.0 (just-dna-format) · Owner format · Motivating case the pre-build gate run for the 0.7.0 cut

sweep --release 0.7.0 exited 1 with two findings: gene_validity.superseded_count and identity.version_coerced_from "moved and the release record does not list it". Both are real manifest additions from the 2026-08-31 batch, both carry a DeclaredChange written the day they landed, and neither was in the record's manifest_fields. The readiness table had recorded the gate green on 2026-08-31; the two declarations were added at 06:52 and 07:04 that morning, after the measurement the list came from.

The shape is the record's own construction. SweepMeasurement.as_record produces the measured half — axes and manifest_fields — with declared deliberately empty, so the gate keeps refusing until a person classifies each movement. That split is what makes the gate work, and it is also what lets an item landing after the measurement add its declaration and leave the measured list behind. Nothing in a checkout could see it: the gate needs the previous release installed and is a release-sequence command by design, so between two cuts the record can be wrong for a fortnight and every test stays green.

The guard is an asymmetry, not a symmetry. A declared addition must appear in manifest_fields: a field that did not exist before moves wherever its block appears, so a release claiming to add one while measuring no movement is claiming something its own corpus contradicts. A declared correction may legitimately be unmeasurable — 0.7.0 declares gene_validity.classifications and gene_metrics.signature, and no reference module carries a re-curated gene-validity claim or a row from the snapshot the second is about. Those stay declared and unlisted, and the gate already has a note for the reverse case. Asserting the full set equal would have forced two false claims into the record to silence a true one.

The test walks RELEASE_RECORDS, so a future release joins by existing. It fails on the pre-fix tree naming exactly the two fields, which is the whole point: this was findable offline and was not being looked for.

Evidence unchanged. The record's evidence sentence already carried today's numbers (content_signature 0/15, manifest_fields 15/15, parquet_bytes 14/15, parquet_schema 14/15, warnings 3/15) — only the field list was stale, which is why nothing else in the record needed touching. After the fix: "release record for 0.7.0 covers the measurement", exit 0.

RM158 — the GWAS pass asked about one table's rsIDs, and the answer already existed in this package

Severity medium · Status ✅ shipped 2026-09-01 in the uncut 0.7.0 (just-dna-enricher) · Owner enricher · Motivating case the RM155 sweep, third instance

gwas._module_subjects built its (rsid, variant_key) list from variants.csv while five authored models carry rsid, so a module whose rsIDs live in haplotypes.csv or pharm_variants.csv got no associations and no line saying none had been asked for. Reproduced against the pre-fix code: a spec carrying one haplotypes.csv row for rs4244285 — CYP2C19*2, which the Catalog has associations for — returned [].

What makes this the useful one of the three: the fix was already written. enrich.Subject and its collector exist for precisely this question, and the docstring says so — resolution read variants.csv alone until RM43, so a PGx module "which by design carries no variants.csv" enriched to an empty resolution.csv and shipped with no coordinates at all. That repair normalized the question to a subject and let three tables through the unchanged resolver. The GWAS pass, written afterwards, restated the narrow loop instead of calling it. So the shape recurs even where the package has already paid to end it, and a sweep is worth more than a fix: grep for the question, not for the bug.

_collect_subjects and _Subject are now collect_subjects and Subject — a private name is what kept the second caller from finding the first. studies.csv carries rsid and is deliberately not a subject: a study row references the variant it grounds, which the module already carries as a row of its own, so admitting it would add no rsID and only change which table an identity came from.

Nothing moves for a module that already had subjects. Measured across the corpus before and after: pathogenic_clinvar (301), hboc_palb2 (16), mt_heteroplasmy (2) and grch37_build (0) return identical lists, because variants.csv goes first in the collector and first occurrence wins — the precedence that exists so a PGx row cannot take an identity a SNP row minted. This pass inherits it rather than re-implementing it.

No schema change: no column, no vocabulary member, no signature moves.

RM157 — the gene set three passes take their scope from read one table while nine carry the column

Severity medium · Status ✅ shipped 2026-09-01 in the uncut 0.7.0 (just-dna-enricher) · Owner enricher · Motivating case the RM155 sweep, run against this repo's own corpus

gene_metrics.module_genes built its list from variants.csv alone while nine authored models declare gene. It is not a report: it is the scope of the constraint-metrics pass, the gene-validity pass and the ClinGen dosage pass — all three call it, the second through a wrapper that exists only to re-raise its error as its own type — so a module whose genes live in its PGx tables had all three quietly do nothing. No rows, no findings, and no line saying a question had not been put.

Measured on the corpus, not on a fixture. cyp2c19_star_alleles, apoe_epsilon, cyp2c9_warfarin_grch37 and hfe_compound_het returned [] here while naming CYP2C19, APOE, CYP2C9, VKORC1, CYP4F2 and HFE on rows an enrichment could have asked gnomAD and ClinGen about. A fixture written to the widened roster cannot produce that evidence, which is the general rule this pair of items leaves behind.

The workspace was already carrying two answers to one question. pgx._module_genes reads two PGx tables, and this one read a table those modules do not have; nobody had put them side by side. And the pass had already been patched for the symptom without anyone asking why the list was empty — RM104 bound reference before the branch because "any module with no variants.csv" raised UnboundLocalError out of a run where wanted came back empty. That sentence was in the code, in a comment, describing the defect as a shape rather than a question.

Derived, and refusing rather than narrowing. The set now comes from the same registry walk the identifier roster uses (@registry-completeness), so a table kind that gains the column joins by existing and a second implementation cannot drift from the first. A table that exists and will not parse raises here, in this pass's own phrasing — a reporting surface may route an unreadable table to not_read, but a scope may not: half a gene set is a silently narrowed one, which is the same defect one table wider. IdentifierRoster gained read_errors so the loader's own message survives into that refusal instead of being reconstructed by string surgery, which is what keeps gene_validity's variants.csv is invalid diagnosis exactly as it was.

pgx._GENE_TABLES stays two tables and is not this roster: it decides whether the star-allele cross-check applies, which is a fact about that check's inputs rather than about what the module is about. Widening it would run the cross-check over modules carrying no star alleles at all.

No schema change, and no ordering change: gene_metrics sorts its rows by (gene, dataset) before writing, so the roster's order reaches no artifact. What moves is that three passes now have a scope on modules where they had none.

RM156 — the widened roster was gated behind the one table it had stopped depending on

Severity medium · Status ✅ shipped 2026-09-01 in the uncut 0.7.0 (just-dna-enricher) · Owner enricher · Motivating case the RM155 sweep, run against this repo's own corpus

RM155 widened check_identifiers' rosters from variants.csv to the nine authored tables that carry each column. Two gates in front of it were still keyed on variants.csv alone, so on the module shape the widening was most for, the wide roster was never reached: check_identifiers(spec_dir=) loaded that table unconditionally and raised variants.csv is invalid: ... not found, and the command returned "no variants.csv — nothing to check" one call earlier and hid it.

The table has never been mandatory (RM2), and four of the nine carrying gene are the PGx kinds a module is built entirely out of. Reproduced on this repo's own reference examples rather than a fixture: cyp2c19_star_alleles, apoe_epsilon, cyp2c9_warfarin_grch37 and hfe_compound_het carry no variants.csv at all, and between them name CYP2C19, APOE, CYP2C9, VKORC1, CYP4F2 and HFE on rows the roster now reads. check-identifiers printed "no variants.csv — nothing to check" and exited 0 on every one. That is S86's unreadable 0 surviving one level above the function that repaired it, which is the more useful half of the lesson: a widening is not done while a caller still gates on the narrow thing.

The old guard's comment is what dated. It justified writing no attestation on the grounds that such a module "has no gene, trait_efo_id or row for these checks to have an opinion about, so the check does not APPLY". The first clause became false the moment the roster walked DRAFTABLE; the second — no attestation without a question — was right and is kept, now derived: nothing to check means no id-bearing table was read, which is a fact about the roster rather than about a filename. Both checks switched off is a different state and keeps its own path, recorded as not_requested.

A third site, found by following the rows. With variants empty and symbols in hand, _gene_locus_conflicts returned compared=0 with None beside it — the ran(0, 0) its own attestation docstring forbids, and the same vacuous pass a third time. It now returns the reason: no variants.csv rows, so no symbol could be placed against a variant's chromosome. The guard sits before the "no row names a gene" arm because it is the more specific fact — since the widening, a module can reach that code with genes and no rows.

Present-and-unparseable still raises, deliberately: that is a module whose rows exist and cannot be read, which is the author's to fix rather than a shape the check should tolerate.

No schema change: no column, no vocabulary member, no signature moves. What moves is which modules the check runs on at all.

RM153 — the identity CIViC does not publish, recovered through the registry rather than by lifting a coordinate

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-enricher; additive — one new client, one snapshot derivation, two withhold reasons, one licence row. No schema change.) Severity low-medium · Owner enricher · Motivating case measured while building RM152

The residue RM152 left: CIViC publishes GRCh37 coordinates or none, and after every published identifier is read, some variants still have no route to a GRCh38 identity. The item carried two questions — should a ClinGen CAID be resolved, and should the remainder be lifted over. Both are now answered, and they answer in opposite directions.

What was measured

Over the dated 01-Aug-2026 release, 533 germline direction rows on 290 variants:

Variants
Recovered by the builder before this item 138 48%
Recoverable through a ClinGen CAID +64 52 via an rs-number, 12 via a GRCh38 coordinate
…plus one-sided indels the registry states, once anchored +35 22 deletions, 13 insertions — all 35, no exceptions
After RM153 237 82%
No identifier of any kind 53 of which 9 carry a GRCh37 coordinate

The registry answered all 102 probe requests with zero failures, serves both an rs-number and a GRCh38 coordinate, and needs no key.

A correction to this item's own figures, and then a correction to the correction. It said 131 unreachable where the dated release gives 157. That gap was first written up as nightly-versus-dated — reach numbers from one file, row counts from the other. Re-measured on 2026-09-01 it is not two files at all: the nightly and 01-Aug-2026 are identical on this slice, and 131 versus 157 is one file read two ways, counting variants that carry a GRCh38 accession (40) against variants carrying one parse_grch38_substitution can read (12). 157 is the number the builder acts on. CIVIC_SURVEY carries the measurement and now labels the definition behind every identity figure, not just the file.

What shipped

  • clingen_allele.ClingenAlleleClient — CAID → rs-number and/or GRCh38 coordinate, paced, cached per run, with three outcomes and never two: resolved, no_identity (the registry answered and holds none — a 404 is an answer), unchecked (a 5xx or a transport failure), plus skipped_offline. It raises nothing; the outcome is the contract, which is why it joins Grch37Client in the exception-contract suite's named exemptions rather than being given an error type to leak.
  • identity_derivation="caid" — the snapshot now keeps a CAID-only row with null coordinate and null rsID, instead of dropping it. It has a route to an identity rather than an identity, and dropping it made the recovery invisible to every later pass. unresolvable_identity now means no identifier of any kind, and falls from 204 rows to 59.
  • The pass runs at draft time, not build time. A build that fetched would forfeit the offline byte-reproducibility that is the whole reason civic build reads a dated file. --offline is the switch, as it is everywhere in this tier, and a run without the registry withholds those rows as caid_unresolved — unplaced, never unplaceable.
  • The rs-number is preferred over the coordinate, and the reason is the item's central argument: ClinGen supplies it and the ordinary resolution chain verifies it against Ensembl. Two authorities, so the check is real — which is precisely the property a lifted coordinate lacks.

  • One-sided indels are anchored VCF/Picard-style, and that closed the last recoverable class. The registry states an insertion as referenceAllele="" and a deletion as allele="", in interbase terms — neither is a row a ref/alts pair can hold. Prefixing both sides with the single reference base before the event is the left-aligned representation VCF requires, and the registry's interbase start is that anchor position for both shapes, so one rule covers them with no per-shape arithmetic. anchor_indel is a pure function with the base reader injected; the reader is SequenceProxy, already in this tier for the reference-allele check. All 35 rows that previously read no_identity are one-sided indels, and every one anchors.

Verified two ways rather than asserted: the reference base at chr3:10142013 is G, and ClinGen's own HGVS for that allele is NC_000003.12:g.10142013dup — a duplication of G, which is exactly the G>GG row produced. An anchor that cannot be read is withheld under its own reason (anchor_base_unreadable), never guessed: a guessed anchor is a wrong ref on a right position, which is the mismatch class sequences.RefMismatch exists to report.

Measured end to end, the drafter goes from 115 variant rows offline to 201 online, withholding nothing.

Repairs rejected

  • Liftover. Reopened at the maintainer's instruction with new balance weights and refused on the measurement — the full probe is CIVIC_UNRESOLVED. Its ceiling is 13 evidence rows on 9 variants, 2.4% of the corpus, and after analysing what those events are the honest recovery is at most one variant. Three are gene-level assertions (Loss, Mutation) that no genotype satisfies on any build. Five are imprecise by the source's own HGVS (c.1-?_340+?del) — the ClinGen registry refuses those expressions outright, which is a stronger statement than a count: they have no allele identity on either build. And variant 2099 is the worked instance of RM48's hazard: its own coordinate pair says 15 bp while its name and alias say 24, and lifting CIViC's coordinate exactly yields a different allele from the one the source is describing. The format cannot defend itself either — a fabricated <DEL:340> and a bare gene-span locus both compile clean in both modes.
  • pyliftover as a dev dependency. Tried. It agrees with Ensembl on all 18 endpoints, so it buys no accuracy; it downloads an unpinned chain file from UCSC at construction; and the assembly-map endpoint already returns interval segment structure, which two point-lifts cannot.
  • Picard LiftoverVcf as the tool of record. Not run, and the reason is worth keeping. Two independent implementations already agree to the base on all 18 endpoints, so a third would confirm arithmetic nobody disputes — while eight of the nine carry no REF/ALT at all, so feeding LiftoverVcf would mean fabricating symbolic records with invented spans, which is manufacturing the input whose correctness is the question. The blocker was never the mapping.
  • Resolving CAIDs inside civic build. It would make the snapshot depend on a live service and cost the reproducibility the dated input exists to provide.
  • Inheriting ClinGen's CC0 for the registry. The gene-curation surface is CC0; this is a different surface, and reg.clinicalgenome.org/site/terms answers HTTP 200 with a generic Genboree "broken link" page — a soft-404, the same shape as HPO's licence URL. Every axis is recorded None: unknown is not permissive. Nothing is redistributed, and reading a public endpoint to place a row is a read rather than an acquisition anyone has gated.

Charter check

P2 — the fetch is in the enricher, the only tier permitted one. P3/P8 — no column, no table, no vocabulary member; a new identity_derivation value on a derived snapshot, which is not the authored surface. P5 — caid_unresolved and caid_no_identity are two withhold reasons because they are two facts, and collapsing them is the S20 defect. P7 — the snapshot stays byte-reproducible precisely because this pass is not in it. P9 — zero authored-layer cost.

What it left open

53 variants carry no identifier at all, and five of the nine coordinate-bearing ones can never be reached by any identity pass, because an unambiguous identity does not exist for them. That is a permanent floor on CIViC's germline reach rather than a gap to close.

Two smaller residues are sized in the probes and not taken: 26 unresolved variants publish a GRCh38 deletion accession the substitution-only parser cannot read directly — most are reached through the registry instead, which is why this was not worth a second parser — and 31 carry a c. HGVS inside their name rather than in hgvs_descriptions. Whether a name plus a transcript resolves through the registry was not measured and is the obvious next question.

Measured on 2026-09-01, and the answer moves this item's residue a long way. It does resolve: all 53 were put through a four-tier identity procedure and 34 of them have an identity, from the fragments CIViC publishes in the variant's own name. The paragraph above understated it by testing a per-gene fact (which transcript a c. fragment is numbered against) as a per-record one, so 29 variants were written off for lacking a representative_transcript cell. Thirty-three of the 34 were adopted the same day as RM159, taking coverage from 237/290 to 270/290 variants and 474/533 to 507/533 rows; the one held back is TP53 R72P, whose identity is the reference allele and so is not a ref/alt row. The "53 carry no identifier" sentence above therefore stands only as the state at this item's cut. What survives unchanged is the five that can never be reached, plus six more that name a class of event rather than an allele. Class by class, with the four wrong CIViC names and three self-duplicates the round also turned up, in CIVIC_UNRESOLVED.

RM152 — CIViC's germline quarter says almost nothing on the axis we asked it, and a great deal on the one next to it

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-enricher; additive — a new snapshot builder, a new drafting source, one licence row, and no schema change of any kind). Severity low-medium · Owner enricher · Motivating case S84 (just-module-creator), 2026-08-31

The item was filed carrying no release class, because both adoptions S84 proposed had been refuted by measurement and an item with no repair has none to state. It acquired one when the probe it named was finally run: the refutations stood, and a third route nobody had proposed turned out to be buildable. The full measurement record is CIVIC_SURVEY.md, which is evidence and not contract.

What was measured, and by whom

S84 reported the germline split and declined to claim the follow-up probe. The reply named it — SUPPORTS/DOES_NOT_SUPPORT × PREDISPOSITION/PROTECTIVENESS against VALID_DIRECTIONS, over a corpus that can say how much it reaches — and it was run on 2026-08-31. Every figure in the item reproduced, including the 412 obtained by subtraction. Four things it did not know:

  1. The contested count was wrong in both directions. The item read PREDISPOSITION × DOES_NOT_SUPPORT as "4 items, precisely the reading contested was added for". Grouped by molecular profile it is 1; grouped by variant, which is the granularity identity uses, it is 3, because a two-variant profile's refuting row propagates to both members while each carries supporting evidence on its own profile. Two of the original four are lone refutations, which contested does not describe. Genuine opposition — a risk call against a protective one — is 0, at every scope probed and under every status basis.
  2. Widening the scope changes nothing. All 620 variants re-swept with no origin, significance or status filter: 2,811 items, 11 newly camp-bearing, every one SUPPORTS on a variant already carrying risk, 0 new contested variants.
  3. The assertions table cannot carry the axis at all. Not thinly — structurally. AssertionSignificance is a different 16-member enum that does not contain PREDISPOSITION or PROTECTIVENESS, so filtering by them is a GraphQL type error rather than an empty result. No CIViC assertion can ever hold a direction call, however the database grows.
  4. The number everything quotes has an undeclared denominator. Both connections default to status: NON_REJECTED, so the 11,518 in the item and the report is that basis; ACCEPTED is 4,904. The bulk TSV release is accepted-only at 4,903 rows. Two published surfaces of one source, 2.35× apart, neither declaring it.

What shipped

  • civic build — a dated release reduced to one parquet plus release.json, byte-reproducible. It reads the bulk TSVs, not the API, because only the download side has dated releases and a snapshot that cannot name its input cannot be reproduced; release.json records the accepted basis so a count from it is never compared with one from the API. Three input files, because MolecularProfileSummaries.tsv is what tells a combination genotype from a dangling reference.
  • draft-panel --source civic — writes direction, never clin_sig, reading the snapshot.
  • CIVIC_TERMS — CC0 1.0, permissive on all three axes.
  • A defect in shared drafting code, found by dogfooding rather than by review: append_partial_rows built its covered-set from partials[0].match_on while comparing each row against its own, so a batch of mixed arity re-added rows on every lap. Fixed at the provider and guarded at the helper.

Repairs rejected

  • CIViC as a concordance authority. S84's preferred candidate, refuted before this round and confirmed by it: five germline ACMG-tier calls, zero benign-class, so discordant is unsayable.
  • A direction-axis concordance apparatus. The open question the item carried, and the answer is no. Genuine opposition is 0; the 3 contested variants are claim-against-refutation, all three dissolve under ACCEPTED, and nothing else in the enricher fills direction — clinvar_draft's fold targets state, the legacy axis, and @axes-passthrough bars crossing them. A concordance record needs two authorities and this axis has one.
  • draft_from_civic on the clin_sig axis. Still refused, and the surviving half of the item's own objection is the silent somatic drop — now a counted drop rather than a filter. The half that did not survive is "it would write rows with an empty significance column": true of clin_sig at 812 NA, and false of direction, where NA is 0 of 1,458. The rejection had been measured on the axis the report aimed at rather than the one the item itself identified as surviving.
  • Liftover, to reach the GRCh37 coordinates. Reopened on the maintainer's instruction and closed again on the number — see RM153.
  • Reading "does not support predisposition" as protective. A refutation removes a claim without establishing its opposite. The row is kept, the axis value withheld, and the count reported.

Charter check

P1 — a snapshot is data and a drafted row is an ordinary authored row; no predicate language. P2 — all of it in the enricher, the only tier permitted to fetch; the compile path imports none of it. P3/P8 — no schema change at all: no new column, no new table, no vocabulary member, nothing demoted or retyped, no published module invalidated. The whole adoption rides on direction and state, which have existed since 0.3. P5 — direction and clin_sig stay separate axes, which is the entire finding. P7 — a rebuild is byte-identical and a re-draft is a no-op, both pinned. P9 — the snapshot is the free layer and the drafter writes only authored columns that already exist, so the authored surface is priced at zero.

What it measured

Over the 01-Aug-2026 release: 4,878 evidence rows in, 329 kept on 133 variants; dropped non_germline_origin 4,067, not_direction_axis 278, unresolvable_identity 204, and the two structural reasons 0 each. Identity: rsid 305, both 17, grch38_hgvs 7. Drafted into an empty spec: 110 variant rows and 311 study rows, every study row carrying a real PMID.

RM146 — every authored column now says which release it appeared in

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format; additive — a marker on each field declaration, no column, no parquet, no signature). Severity medium · Owner format (schema) · Motivating case S81 (just-dna-registry, relaying just-module-creator)

The finding

A module authored on 0.6.6 was sent to a registry deployment running format 0.6.1, which runs our validate_spec server-side and reports its findings verbatim:

studies.csv line 2 [curator]: Extra inputs are not permitted

StudyRow.curator is ours, added in 0.6.5. A genuine typo produces the byte-identical shape ([curatr]), and the two want opposite actions from an author — upgrade the reader, or fix the cell. The finding is pydantic's under extra="forbid", so it could not be reworded into carrying the distinction: the information was not in the model at all.

What shipped

base.since("0.6.5") on every authored field, read back by base.field_first_seen(model). It composes with vocabulary() rather than replacing it — both are entries in one json_schema_extra dict — and stamped_identity_field takes first_seen as a required argument, because a compiler-stamped column is still one an older reader refuses and defaulting it would let the next such column inherit a version nobody measured.

On the field, not in a roster. A list keyed like release_records was the alternative and loses on the rule this repo keeps relearning: a hand-kept list beside a model is a second statement of one fact, and it is the copy that goes stale. Declared on the field, it travels through every rename and move.

The backfill was measured, and the numbers are worth recording

Parsed out of each release tag's own sources — git ls-tree per tag, the model classes read from the AST rather than imported, since old code need not import under a current Python. 414 fields across 31 models, and the distribution is a fair summary of this format's history: 115 fields date to 0.2.0, 81 to 0.4.0, 150 to 0.5.0, 160 to 0.6.0, 3 to 0.6.5, and 78 land in the uncut 0.7.0.

curator is the worked example and it is the reason the answer is per (model, field): it is on VariantRow from 0.2.0 and gains its StudyRow twin only in 0.6.5. A roster keyed by column name would have given one answer for two facts — and the wrong one for the module in the report.

The guard, and why it is an equality

test_first_seen.py asserts set equality over the walked registry: every field of every model in _ALL_MODELS declares one. A floor (>= 400) or a truthiness check is satisfied by exactly the state that produced this report (@registry-completeness). Two guards ride with it — the registry itself is checked for completeness, since a guard over an incomplete registry reports a clean bill about the models it happens to know (RM96's shape), and every declared version is checked against the set of releases that actually exist, because a typo'd number is the one error the model cannot catch itself.

Two things the build turned up

A mechanical edit needs an AST, and the AST needs to know what a field is. The first pass wrapped nine ClassVar declarations — ALLELE_COLUMNS, REQUIRED_ANY_OF — in Field(...), which is not a field at all; the suite caught it as TypeError: 'FieldInfo' object is not iterable from the tests that iterate those constants. Unwrapped by AST rather than by regex, because the multi-line forms are invisible to a line-oriented pattern.

The entry said 402 fields and the tree holds 414. It was written before 0.7's own additions landed, which is the ordinary fate of a counted number in prose (@counted-prose-needs-a-fixed-field) — and the reason the test asserts a floor on the total while asserting equality on the coverage.

Repairs rejected, kept from the entry

Reading release_records' parquet_schema axis names 4 of 402 authored columns, because it records what a release changed about compiled output; curator happens to be there, which is what makes it dangerous — right for the case in hand, silently wrong for 398 others. Rewording the pydantic message has nothing to word. Loosening extra="forbid" removes the guard that catches the typo half. And a compatibility handshake was explicitly not asked for; the reporter corrected their own side.

What it does not settle

A reader still cannot be told which release it is missing without also knowing its own — that pairing is the consumer's, already shipped in their 0.22.0, and stays theirs. This supplies the half nobody outside this repo can compute.

RM117 — the vindication signal shipped, and it replaced a message that read as an accusation

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format + just-dna-compiler). Severity medium · Owner enricher when filed, compiler as built · Motivating case S52 (just-module-creator)

What the item was by the time it was built

Two halves settled before this one. ProvenanceItem.outranks — {column: why}, per column, additive — landed 2026-08-20 so an author overriding a checked value has somewhere to record why. The severity half was closed on 2026-08-21, not deferred: putting a checked verdict under authored control is something nothing else in this format does. What remained was the observability half: two signals a check can compute because it runs on every compile and needs nobody's permission.

Recast onto the overlay rather than outranks. The entry proposed both signals over provenance.json, and by 2026-08-28 that was the wrong file: RM135 settled the overlap as a dated succession, outranks is filed for removal at the major, and concordance.py already names the overlay as where an answer goes. Growing observability on a field queued for deletion is what RM135 warns against, so the signals compute from overrides.csv, where the surviving mechanism is.

The signal was already firing, with the wrong words on it

This is the part worth keeping. clin_sig_concordance.csv holds contested subjects only and is rewritten whole, and concordance.py states outright that a subject leaving the record is how an author learns the archive caught up with them. So the state RM117 wanted to observe — the archive resolved a conflict the author had answered — already produced an observable: the overlay row reaches nothing.

What it produced was the generic finding, offering the subject may be mistyped, or the correction may be aimed at a row the compiler drops — put to an author in the one case where their judgement had just been confirmed. So the work was not adding a signal; it was stopping a wrong one, which is why this earns a code (overlay_answer_vindicated) rather than a rewording, and why the test asserts the misleading line is gone as well as that the good one appears.

It is an observation, not a verdict, and the wording is pinned

The authorities agreed and the overlay row is now unnecessary. Whether the author was right about the biology is not something a compiler can say. The test greps the message for adjudicating words on a word boundary, and it caught a real one: the first wording said the conflict ended rather than that the correction is wrong, which grades the author's row while claiming not to. The published sentence says the disagreement ended and the row can be retired.

The second signal was filed rather than built, and shipped the same day

A record whose row's value has changed again needs the archive's value now against its value at record time, so it needs a fetch — enricher work, with the offline/no-snapshot/nobody-asked ladder every network check here carries. It is RM151, and it turned out more tractable than this entry assumed: clin_sig_authority_calls.csv records each authority's call, its verbatim wording and its release, so the baseline exists — for the concordance pair alone, which is the scope RM151 states. It is below, shipped inside the same uncut 0.7.0.

Scope

One table, because one table's absence has a single reading. Every other overridable table's unmatched update is ambiguous and takes RM137's split; VINDICATING_OVERLAY_TABLE names the exception, and the routing is a continue rather than a reachability predicate, since the generic classifier's two readings are exactly what must not be printed here.

RM151 — the second vindication signal, and the baseline is the file the same run overwrites

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-enricher). Severity low-medium · Owner enricher · Motivating case S52 (just-module-creator), RM117's second signal

RM117 shipped the signal that a subject has left the concordance record. This is the other one: an overrides.csv row answering a contested subject is a judgement written about a particular disagreement — the archive said X, the author says Y, and reason explains why — and if the archive later says Z, that reason was written about a value that is no longer there. Nothing distinguished a justification that still describes the disagreement on file from one that describes a disagreement since replaced by a different one.

The baseline exists, and it is exactly one file

RM117 said a record "is not bound to the value it justifies", and for the concordance pair that is no longer quite true. clin_sig_authority_calls.csv records what each authority actually said — clin_sig, the verbatim clin_sig_raw, and the dataset release it came from, keyed (variant_key, genotype, authority) — so recorded-call against fresh-call is available here and nowhere else in this format.

Scoped to that table, and the finding says so in its own text (@probe-names-the-table). An overlay row against frequencies.csv or resolution.csv has no recorded prior value at all, so a general the value moved check would be answerable for one table and silently absent for every other — an unscoped negative becoming a permanent false constraint.

The ordering is the feature, and it is guarded where a refactor would break it

write_concordance_tables replaces the record whole, so the previous run's rows exist only until this run commits. The comparison is therefore computed in the staging phase, above the commit — which enrich() already does for every product of a run, for the unrelated reason that a refused strict run must change nothing. No assertion over a return value can see statement order, so the test walks the AST and asserts the read's line precedes the write's, in the same enclosing function. The guard was demonstrated to fail on a source copy with the two swapped before it was kept.

A move is observable exactly once, and that is the honest shape

The run that notices also rewrites the baseline; the next run compares against the new one and is silent. Persisting it needs the overlay row bound to the value it justifies — a column on overrides.csv recording what the answer was written against — and that is a schema change to the authored surface, a minor rather than a patch, and precisely the binding RM117's three objections all turned on missing. None of those objections is an objection to noticing that the value moved, which is why this ships as an observation and the binding stays unbuilt. Decided per item with the maintainer.

Three states, and the third is the whole point

Unchanged is recorded on both sides with the same classification, dataset moved or not: a re-released archive saying the same thing has not moved the disagreement. A shift is a changed classification, or recorded → no_record and back — asked both times, and the answer differs. Everything else is withheld, no_prior_record or unchecked_now, and reported as an info note. Neither withheld state ever reads as nothing moved: telling an author their reasoning still stands on evidence nobody looked at is the one way this check does real harm, and it is what the tests spend their weight on.

A move this tier's own normalizer made is reported apart from the archive's. Same verbatim clin_sig_raw, different normalized member, means clin_sig.py changed rather than ClinVar — a fact about our code with nothing for an author to do. Folding it in would accuse a source of a change we made.

What counts as an answer, and why it is the opposite rule from RM136's

Any overlay row naming the subject — every operation, every field. What goes stale is the reason, which the model makes mandatory on every row whatever the row does, so a per-field rule would have to name a column the reason does not live in. RM136's overlay_answers is per field for the opposite direction: it decides whether a finding may be silenced, and anything looser silences findings the author never looked at. A finding raised too widely costs a reader one line; one silenced too widely costs them the finding. licensing.overlay_answered_subjects is the second reader, beside rather than inside the first.

The boundary with RM117, and the wording

A subject that has left the record entirely never enters this comparison: that is overlay_answer_vindicated, reported by the compiler as good news, and hanging a second and gloomier finding on the same overlay row is exactly the already firing with the wrong words failure RM117 was. The messages are pinned by a word-boundary grep refusing correct, wrong, mistaken, vindicated, confirmed and their siblings — the disagreement you answered is not the one on record now is a statement about the record, and your answer may be wrong is a verdict this check cannot see the reasoning for.

Warning-tier in both modes, escalating in neither (@clinsig-never-escalates), with more force than the record itself: gating on it would make an artifact refuse over an archive's release schedule.

RM138 — closed: the duplication costs 1.84× raw and 1.06× compressed, and the encoding stands

Closed on 2026-08-31 with no code change, inside the uncut 0.7.0. Severity low · Owner format (schema) + compiler · Found by reviewing RM131 against its own motivation

Not a defect, and the entry said so first. The shape was decided per item with the maintainer — a carried list beside warnings, holding the subset the author cannot clear — over a field on each finding, because it invents no permanent names and a consumer subtracts to get the actionable set. Both properties hold. What the decision did not have in front of it was the size, and the size is the thing RM131 exists about.

The number that was missing, measured rather than argued

The entry measured the raw cost at 1.84× across the corpus. The question it left open was whether a published manifest should pay that. Re-measured on 2026-08-31 with the compression a real transport uses, over every reference example that emits a warning:

module warnings carried raw gzip
pathogenic_clinvar 113 109 1.96× 1.13×
hboc_palb2 12 12 2.00× 1.07×
shox_par1 / apoe_epsilon 2 2 2.00× 1.05× / 1.07×
htt_repeat_expansion 3 1 1.33× 1.02×
corpus 1.84× 1.06×

The raw column reproduces the entry's figure exactly, which is what makes the second column trustworthy. carried is a verbatim subset of warnings, which is precisely the input DEFLATE's back-references are for, so the duplication that doubles the bytes on the wire uncompressed adds 6% compressed — and the whole with-carried payload gzips to 0.21× the uncompressed warnings-only one. The worst case in the corpus, the 113-warning module the item was filed about, pays 13%.

The decision

Keep the encoding, and recommend compression where the size matters — a catalog serving many manifests, an API response, anything shipping manifest.json over a wire. That is a deployment concern rather than a schema one, and it is where the cost actually lands.

The three cheaper encodings the entry weighed stay rejected, unchanged, and their reasons are now cheaper to accept because the thing they were buying is worth ~6%:

  • carried: list[int], indices into warnings. Breaks the one property the field was chosen for — the subtraction becomes a zip, and an index means nothing to a consumer that filtered or re-ordered the channel. It also positionally couples two published fields, which manifest.compilation.warnings has always avoided.
  • carried: list[str] of codes. Answers a different question, and one already answered: carried-ness is a property of the code alone, so warnings_summary plus CARRIED_WARNING_CODES gives the count without this field at all.
  • Drop carried, publish a per-message codes: list[str]. The genuinely minimal encoding, and still a third shape rather than the decided one — it re-introduces the positional coupling and hands every consumer a derivation where they currently read an answer.

Closing it now rather than leaving it open is the point. A fourth encoding after 1.0 is a removal, and removals are major-only under Principle 3, so this had to be settled inside 0.7 either way. It is settled with a number rather than by drift.

RM136 — the enricher reads the author's overlay, so a correction stops coming back forever

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-compiler — one loader made public — plus just-dna-enricher). Severity medium · Owner enricher · Found by the wave-1 audit of RM124, 2026-08-28

The asymmetry

The compiler applies overrides.csv before any check reads a row, which is the whole point: a check must report on what the module asserts. The enricher did not — its passes re-read the raw derived file — so an author who corrected a resolution.csv cell through the overlay went on being told the same finding on every subsequent run, forever, with no way to clear it and no indication that the correction had been recorded and honoured one tier over. INTEGRATION_0_6 states the asymmetry for consumers; it was never stated for the author, who meets it first and has no parquet to read at the point they are curating.

The decision, and the line it draws

Read-only, at INPUT reads, per field. Three separable choices, and each has a refused alternative:

  • Read-only. The enricher never writes through the overlay: an overlay row is the author's answer to a difference, never the tier's (RM83's standing refusal).
  • Input reads only, never merge baselines. A pass that reads its own output file to merge against it writes that file back, so feeding it post-overlay rows would bake the correction into the derived table. The three input sites — frequencies, assertions, and identifiers' gene-locus check — read resolution.csv as an input to something else and take the overlay; every merge baseline stays raw. Same rule the sidecar gotchas already state from the other side: read the file you write.
  • Per field, not per row. A finding is answered when the overlay updates the very cell the finding is about, so correcting a coordinate silences the coordinate check and leaves an unrelated clin_sig finding standing. Per row was cheaper and was refused: an author correcting one cell would silence findings they never looked at, which is the silent-suppress hole the overlay's design calls its worst case.

No second implementation of apply_overrides — the entry's central refusal, on the grounds that two copies would drift on exactly the normalization seam that produced a silent P7 break in this feature's first week. compiler.load_overlay became public (the S74 shape: a private symbol the enricher would otherwise reach into) and licensing.overlaid_input_rows calls the apply_overrides. A test compares the helper's output against apply_overrides directly, so a future copy would be seen.

Answered is not agreed, and that is what keeps it honest

An answered pair leaves disagreements and stays in subjects, with PairCheck.answered counting it and one INFO line saying so. The comparison ran and found a difference; dropping it from the denominator would report a cleaner module than there is, which is the silent-success shape this codebase keeps closing. What changes is only that the difference reads as settled by the author rather than as work owed — and the author finally gets the acknowledgement that was missing.

What it does not reach, stated rather than left to be discovered

One check consults the answered set today: the rsid↔coordinate comparison, which is the finding an overrides.csv row on resolution.csv can actually answer. The mechanism is general — overlay_answers takes a table name — but a check is wired to it deliberately rather than in bulk, because "which cells does this comparison read" is a per-check fact and guessing it wrong silences a finding nobody answered. _COORDINATE_FIELDS is that fact written down for the first one.

RM137 — the unmatched-overlay warning is now a property of the module, not of the lap

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format + just-dna-compiler). Severity low-medium · Owner compiler · Found by the wave-1 audit of RM124, 2026-08-28, reproduced end to end

The defect

reverse_module rebuilds a derived table from the artifact, and two of the eight overridable tables are rebuilt from something narrower than the file the compiler read: literature.csv loses its uncited rows before the parquet and is rebuilt from that parquet, and resolution.csv has no parquet at all and is rebuilt from the SNP core, which re-emits only positioned rows. An update naming such a row matched on lap 1 and warned on lap 2, so a module and its own compile → reverse → compile disagreed on manifest.compilation.warnings — a published field, and one RM126 had made load-bearing.

What "count it over the overlay's own rows" means in code

The decision was to report the finding the way suppress reports its own — over the overlay rather than over what it reached. Turning that into code needed one step the entry did not have:

  • counting the overlay's update rows outright is a tautology that fires on every healthy module (@tautology-zero);
  • counting the ones that reached nothing is the lap-dependent original.

The stable quantity is neither. It is a property of the target: could an artifact of this module carry that row at all? For literature.csv that is "is the PMID cited", and for resolution.csv it is "can the module place that variant_key" — both computable from data that survives the round trip, so both answer the same on lap 1 and lap 2 whether or not the row is there to be matched.

The unreachable finding therefore fires matched-or-not, and that asymmetry is the whole fix. An earlier cut of this classified only the unmatched set and was silently lap-dependent all over again: on lap 1 the uncited row is present and the update matches, so nothing was reported. Caught by asserting equality between the two laps rather than "lap 2 warns", which would have passed on the broken code.

Two readings, and neither of them is "a typo"

That framing was the original entry's and it is wrong. A mistyped PMID is also an uncited one and a mistyped variant_key is also an unpositioned one, so a mistake lands in the unreachable bucket. What the reachable bucket really means is narrower and more useful:

  • overlay_update_unmatched (reworded) — the subject is cited or positioned, so the artifact could carry the row and the sidecar simply does not have it. Re-run the enrichment pass.
  • overlay_update_target_unreachable (new, actionable) — no artifact of this module can carry the row. Two readings, named rather than collapsed: the subject may be mistyped, or the correction may be aimed at a row the compiler drops and be perfectly fine.

Scope, and why it is not a dodge

Only literature.csv and resolution.csv — LOSSY_OVERLAY_TABLES, asserted as an equality over the walked registry. The other six rebuild whole on a reverse, so an update reaching nothing there is unmatched on both laps already and needs none of this. The predicate is defined only where the loss is, and a table added to OVERRIDABLE_TABLES has to face the question deliberately.

Two traps the build hit

The predicate must share the drop's own function, not restate it. cited_pmids was extracted out of split_cited_literature so both ask one question; two statements would drift, and in the worst direction — the predicate would call a row unreachable that the drop had kept, and a healthy overlay would report a finding forever.

And it must mirror the drop's empty-cited guard. split_cited_literature discards nothing when the module cites nothing at all, on the stated grounds that such a module cannot distinguish a stale sidecar from citations not yet authored. Without the mirror, every literature update on such a module reads as unreachable — a stable false positive, which is worse than the unstable true one.

Where the classification happens, and why it moved

Not at apply time. apply_overrides runs before any check reads a row, and the question needs studies.csv and the citing tables, which validate_spec and compile_module both load later. So apply_overrides gained defer_unmatched=True (additive, default off), the unmatched set is stashed from the pre-overlay rows — apply rebinds its input, and an insert earlier in the same overlay would otherwise make a later update look matched — and one shared helper splits it late in both functions, so the two cannot classify differently (@parity-by-check). Hoisting the studies.csv load instead was refused: pre-flight warnings seed the compile's list, so reordering the load reorders a published field for no gain.

RM150 — unknown was carrying an absence and a finding, and contested takes the second

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format). Severity low-medium · Owner format (schema) · Motivating case S83 (just-module-creator), the residue RM148 did not take · Taken into 0.7 by the maintainer on the grounds that there was no sense postponing it — it was filed to ROADMAP_0_8.md earlier the same day and moved here without its shape changing.

The shade RM148 left

The reporter said direction's unknown covers three things: no evidence, conflicting evidence, and evidence that does not exclude either direction. RM148 removed the third by reassignment — an unestablished sign is still a sign, so that state is the pair direction=<sign> + stat_significance=not_significant, and a member for it would have been a second spelling. That reasoning holds and is not reopened.

It does not reach the first two, and RM148's own field description said so out loud — "not assessed, or the sources conflict" — while adding nothing that told a consumer which. They are not one thing: one is an absence and the other is a finding. The reply to S83 asserted the two were "one thing (nothing to record)", and that was our assertion rather than the reporter's concession.

The decision, and why the member is earned here where it was refused there

contested is added and unknown keeps its original meaning. Both halves are load-bearing. Re-pointing a shipped member at the narrower sense would silently change what every published module already says by it — a retype in everything but name, and Principle 3 territory; adding beside it is minor-legal. The name is the workspace's own word for the same idea one table over (clin_sig_concordance.csv is one row per contested subject, and clin_sig_concordance_contested is an existing warning code), so coining a synonym would be the drift @one-normalizer-two-spellings records.

The cost that made RM148 refuse a member — a wire vocabulary gains one — is paid here because this shade is genuinely not expressible as a pair: no combination of direction and stat_significance says two sources disagree about the sign.

The trap, and it is why the map was the first edit rather than a follow-up

trimmed_state() projects a direction back into the legacy state set through _DIRECTION_TO_STATE.get(direction, "neutral") — a .get with a default, not a lookup that raises. Measured before anything was changed: trimmed_state("contested") already returned "neutral", and so does trimmed_state("a string that is not a direction"). So adding contested to VALID_DIRECTIONS and stopping there ships a module whose upgraded() silently emits the wrong legacy state, with nothing failing anywhere.

The map entry therefore went in first, and the guard is a registry-iterating equality — set(_DIRECTION_TO_STATE) == VALID_DIRECTIONS, walked. A test asserting trimmed_state("contested") == "neutral" would have passed against the unfixed code and measured nothing; the assertion has to be about the map's coverage, not its output, and the test says so with the demonstration beside it. contested → neutral is the right projection once it is explicit: the legacy set has no member for it, and neutral is where unknown already lands.

What it deliberately did not touch

  • _STATE_TO_DIRECTION gains nothing. The two maps look like they should mirror and do not: no legacy state value means the sources disagree about the sign, so there is nothing to map from. A module upgraded off the legacy column can never produce contested; only an author writing direction directly can. Commented at the site, because it invites a "fix".
  • stat_significance gains nothing. Two sources disagreeing about the sign is not two sources disagreeing about the strength, so the two vocabularies' intersection is still exactly unknown — asserted, so a later member has to face the question deliberately.
  • Nothing re-points, so nothing drifts. upgraded() stays idempotent and needs_upgrade does not start reporting existing unknown rows, which is the half that makes this an addition rather than a retype.

RM155 — the identifier roster read one table while eleven carry the column

Severity medium · Status ✅ shipped 2026-09-01 in the uncut 0.7.0 (just-dna-enricher) · Owner enricher · Motivating case S86 (just-module-creator, in CONSUMER_SUGGESTIONS_HISTORY.md)

check_identifiers built its trait and gene rosters from variants.csv alone. Walking _ALL_MODELS, eleven authored models declare trait_efo_id or gene — StudyRow has carried the trait column since 0.3 — so a 67-variant module carrying the id on all 68 studies.csv rows reported nothing checked and nothing flagged, and could ship a retired or simply wrong CURIE with every gate green. Reproduced offline in both directions before anything moved.

The unreadable 0 is the item; the missing table is only how it got there. traits checked: 0 asserted this module declares no trait and its traits are in a table nobody read in one breath — @unreachable-not-absent at a finer grain, a question never put rendered as an answer. Widening the roster alone would have left that hole, because a wide roster still returns [] for a module that genuinely declares none. So the fix is both halves, which is what the reporter proposed as an either/or and is really an and: IdentifierReport gained trait_tables_read / trait_tables_not_read and the gene pair beside them, and the CLI count names its own denominator.

The roster is derived from DRAFTABLE, never listed. A hand-kept set would be the same defect with a longer literal in it, so the test asserts an equality over the walked _ALL_MODELS (@registry-completeness) and a table kind added later joins by existing. Nine tables carry trait_efo_id, nine carry gene. Two edges the walk settled: MeasureBinRow is correctly absent as the abstract base whose four concrete subclasses are each their own entry — pinned rather than assumed — and the three derived models carrying these columns (GeneMetricsRow, GeneValidityRow, GwasEffectRow) are outside the roster on purpose, since a stale id in a machine-written row is the source's currency and no author can act on it. Widening to them would report findings against rows nobody wrote, and dataset_currency is the surface that asks that question.

A third instance, one level up, found by the same framing. report.clean is all() over a set that can be empty, so check-identifiers printed a green "all identifiers current" having asked nothing at all. It now says what it read. Worth the general form: a predicate that is all() over a possibly-empty set reports a pass it did not earn.

An absent optional table and one that exists and will not parse are kept apart — the first is every module's normal shape, the second means ids the module carries went unchecked, and only the second warns. The narrow roster survives for a caller passing variants=, which is all rows-in-hand can serve, and that caller is told so in *_tables_not_read rather than left indistinguishable from the wide case.

No schema change: no column, no vocabulary member, no signature moves. IdentifierReport is a report object rather than a published row, and the added fields default to empty, so an existing caller reads unchanged.

RM154 — an answered lookup whose alleles were rejected was published as an absence

Severity medium · Status ✅ shipped 2026-08-31 in the uncut 0.7.0 (just-dna-format + just-dna-compiler + just-dna-enricher) · Owner enricher · Motivating case S85 (just-module-creator, in CONSUMER_SUGGESTIONS_HISTORY.md)

A 64-variant longevity module authored from a paper whose supplementary is GRCh37/hg19 left five subjects unresolved, each written into resolution.csv as status: not_found, source: ensembl. Ensembl has all five and returns them immediately. What failed was allele matching: the paper spells the submitted strand, so its G/A meets GRCh38's C/T and the allele-aware filter rejects every locus, emptying loci and dropping the row through to the not_found arm.

Two states of the world, byte-identical rows. Reproduced offline against the real enrich path: a snapshot that has the rsID with complemented alleles and one that genuinely lacks it produce the same (rsid, status, chrom, start). That is the collapse RM98 repaired one branch over — the reporter cited its comments back at us — arriving from a third direction: unreachable_rsids means the request failed, unconsulted_rsids that nobody looked, and this one that the asking succeeded and the answer did not match. The consumer's own framing is the item: not_found sends an author to does this rsID exist, a question with an obvious answer that is not the problem.

Both obvious repairs are worse, and the second is worse in a way that had to be measured. A new VALID_RESOLUTION_STATUS member changes a wire vocabulary every reader of a published resolution.csv shares — the reporter argued this themselves. Deleting the row looks more honest and is not: variant_key and rsid are RESOLUTION_FACT_FIELDS while status is provenance and is not, so removing the row moves resolution_signature and changing its status is free. Checked with the real function rather than reasoned from the field list. The row was never the untruth — it is honestly unresolved either way — so what moved is the reason, not the row.

Shipped: EnrichmentResult.allele_mismatches, carrying AlleleMismatch(rsid, genotype, loci, offered, strand_flip) — the shape ref_mismatches and stale_rsids already have, which is the option the reporter proposed. One aggregated run warning in both modes, naming the rsIDs and saying the source has them, because an author who greps the artifact for not_found is exactly who this exists to contradict.

A second defect the report did not file, found in the sentence it quoted. hosting_verdict returns a confident False from two arms — a substitution/MNV locus (no flank, so no spelling freedom) and an event length the locus does not offer — and the warning gave the second arm's reason for both. So a strand-flipped SNV was reported as "The event sizes differ, which re-anchoring cannot change" about two 1 bp substitutions: a false claim, and the one that cost the run its largest diagnosis detour. contradiction_reason is now undecided_reason's twin on the False side (five causes there, two here), walked by a test asserting the arms' reasons are pairwise distinct — the failure mode is a third arm silently inheriting a second's sentence, which raises nothing and reads as a diagnosis.

strand_flip_explains and reverse_complement landed in format, not the enricher: they are pure string work over the four bases with no reference access, the compiler's twin reporting site needs them, and digest parity between the two resolution paths is a documented guarantee. reverse_complement withholds on anything that is not four bases — a degenerate code states an uncertainty, and complementing it would assert a base the source declined to name. strand_flip_explains tests called <= locus first, because a palindromic SNV (A/T at T>A) satisfies both readings and would otherwise be reported as a flip when it needed no explaining at all.

No artifact changes: no column, no vocabulary member, no signature moves, and every existing module recompiles byte-identically. The not_found rows stay exactly where they were, which is what the reporter concluded too — nothing in their data needed editing beyond the five genotypes' strand.

RM108 — a re-curation is recognised, and currency is DERIVED rather than marked

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format + just-dna-compiler + just-dna-enricher). Severity medium · Owner enricher, and the derivation landed in format · Motivating case the 2026-08-19 doc audit (just-module-creator's gene_validity.md)

The finding

_merge_key returns ("id", row.assertion_id) when the source published one — the right rule in general, and wrong here, because ClinGen's assertion id embeds the curation timestamp (CGGV:assertion_…-2019-08-18T160312.829Z). A re-curated assertion arrives under a different id, misses the merge key, and is appended beside the old one. manifest.gene_validity.classifications then published a pair as far apart as ["definitive", "refuted"], with classification_date and dataset the only discriminators and no consumer reading either.

The decision that survived contact with the code, and the one that did not

Survived: the newest classification_date is current, and nothing is deleted. That is S45's answer carried over to a weaker signal, and taking it means accepting one thing this format had not accepted before — that a date is authoritative for currency. The concession is narrower than it looks. The date decides ordering and nothing else: it never says a classification is right, both rows stay in the file so the drift stays visible, and a consumer wanting the answer no longer has to reconstruct one.

Did not survive: the marker column. The entry said the superseded marking "needs a column, which is additive and minor-legal". Legal it is; workable it is not, and the reason only shows up when you try to write it. The row that must be marked is the one already in the file, and merge-not-clobber forbids this pass editing it (@sidecar-authoritative). So the marker would be correct on every run except the one that created the ambiguity — the run that appends the new curation is exactly the run that cannot go back and mark the old one. A boolean fails that way and a superseded_by pointer fails that way too, plus three of its own: GenCC rows may carry no assertion_id to point at, a row superseded twice needs a rule about immediate-versus-current successor, and a pointer locates rather than asserts, which is the line GENE_VALIDITY_FACT_FIELDS already draws to keep report_url outside.

So nothing is stored. Currency is a total function of the rows present, so it is derived at every read (@derived-not-stored): classify_currency in the format tier, called by the enricher to report and by the compiler to warn and to build the manifest block. One consequence worth stating plainly — no column changed, so gene_validity.signature does not move and no existing module recompiles to different bytes. The reported harm was in the manifest, and the manifest is where it is fixed.

The grouping, and its one difference from the merge key

(gene, disease_id, moi, submitter) — the source's grain without dataset. A re-curation is by definition a later release of the same claim, so including dataset would put the two rows in different groups and answer "nothing was superseded" every time. Computed beside _merge_key and never inside it: the merge must keep both rows, because the drift staying visible is the property the item exists to preserve.

Two edges, and both withhold

Neither was in the original entry, and both are decisions rather than defaults:

  • a tie on classification_date — two curations stamped the same instant, and nothing says which came second;
  • any row in the group carrying no date — including the dated siblings, because being the newest of the rows that stated a date is not the same as being the newest.

In both cases no row is current and none superseded, and the manifest publishes every classification in the group. Breaking a tie on assertion_id was rejected: an identifier carries no chronology, and sorting on one manufactures a winner out of a spelling. A group of one is current, dated or not — there is nothing to order it against, and that is what keeps the finding quiet on an ordinary module.

Severity: a warning in both modes, in both tiers

The enricher never raises, in best_effort or strict — a curating body re-curating is the source working, not the module being wrong. That is the pass's own argument for missing ("strict is a report, not a refusal to have looked") and the stronger form of it: the only edit available to an author is deleting a row, which falsifies the record rather than repairing it. It is a deliberate departure from @enrichment-is-validation's mode ladder, and the second such check.

The compiler warns in both modes and never escalates, on the rule _vrs_coverage_warnings and frequencies' not_covered already follow — a finding no authored edit could clear is not a strict matter — and both codes are in CARRIED_WARNING_CODES for the same reason. validate_spec reports the same two findings, since this is pure computation over injected bytes (@parity-by-check).

What the build turned up on the way

The first fact-table check to run on both sides, so it was the first to double. compile_module runs validate_spec as its pre-flight, both reached the identical sentence, and manifest.compilation.warnings carried it twice — which doubled warnings_summary's count with it, the case @no-rerun-with-counts is about. The fact-handler loop now dedupes on the message like every other both-sides check (RM94's idiom); both passes read the same post-overlay rows, so the counts agree and the rule is satisfied rather than dodged.

manifest.gene_validity.superseded_count is new, and it is gated on the round trip. gene_validity.csv is rebuilt whole from its parquet — no row drops, unlike literature.csv — so the row set is identical on lap 2 and the derivation over it is too. Asserted rather than assumed, because a published field that differs between a module and its own round trip is precisely RM137.

The merge test could not see this defect and is part of the fix, not the thing that confirms it. test_a_rerun_merges_rather_than_duplicating feeds the same bytes twice, and the same bytes carry the same ids, so the key matches and nothing is appended however wrong the key is. The new fixture is two different exports of one claim, which is what the real source produces.

RM103 — the manifest now records the version that was READ, not only the one that was invented

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format + just-dna-compiler; the manifest half of the split item — the refusal half stays on the 1.0 tracker). Severity low-medium · Owner format · Motivating case S42 (just-dna-lite, in CONSUMER_SUGGESTIONS_HISTORY.md)

What shipped, and what deliberately did not

Identity.version_coerced_from — the authored module.version when the model rewrote it, None when it was already canonical SemVer. 'v2' beside '2.0.0', 'abc' beside '0.0.0'. Additive, out of artifact.digest, declared in RELEASE_RECORDS on the manifest_fields axis.

The coercion is untouched and must stay untouched. RM17 decided coerce-rather-than-reject because the pre-0.4 corpus is full of v2 and 3, and 0.6 widened it at mode="before" after 26 of 61 foreign modules refused on an unquoted integer. Every digit-bearing case still behaves exactly as it did, and the test parametrizes all of them precisely so a later change cannot quietly undo RM17 while appearing to be about this item.

A sentinel stays rejected. Coercing to something unmistakable has no target: every three-number string is a legal SemVer and therefore somebody's real release. Publishing what was read is the only repair available, which is exactly why the additive half was worth separating from the refusal.

The second-order effect that was nearly shipped, in the release that files RM137 about it

reverse_module takes version from its caller, and the caller has manifest.identity.version — the coerced string. Re-emitting that leaves lap 2 with nothing to coerce, so version_coerced_from comes back absent and a module disagrees with its own round trip on a published field. That is RM137's exact shape, and it would have arrived in the same release.

So reverse re-emits the pre-coercion string: _authored_version_from_artifact reads the artifact's own manifest, prefers version_coerced_from, falls back to version. Both cells then hold across two laps, which the test asserts rather than assumes — and the failure was demonstrated on the naive implementation before the test was called a regression net (abc → lap 1 abc, lap 2 None).

It also repairs a quieter loss nobody had filed. Reverse emitted no version: at all unless a caller supplied one, so even an ordinary canonical version did not survive a round trip. Nothing hashed on it — module.version is advisory and out of artifact.digest — which is why it went unnoticed. An explicit argument still wins, and a bare parquet directory with no manifest still leaves the key out: recover it or say nothing, never invent one, the same rule genome_build follows.

What the reporter should do meanwhile, restated because it was already true

Both compile and validate have always warned, naming the authored string and the coerced result, so a build that greps its warnings caught this before 0.7. The gap was between the model (silent) and the pipeline (loud), and the reporter was testing the model directly. The manifest closes it for a consumer holding only the artifact, which is the population that could not act at all.

One correction to their report, in their favour, kept from the original entry: they noted their own CLAUDE.md claimed "an unquoted 1 in YAML loads as an int and is rejected" and is wrong on 0.6.1 — 1 coerces to 1.0.0. Confirmed, and our documents do not carry that claim. The hazard is the unquoted decimal, still refused and deliberately so.

RM110 — constraint_flags had two producers, two encodings, and one of them inside the fact set

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format + just-dna-enricher). Severity medium · Owner enricher, and it moved to format — see below · Motivating case the 2026-08-19 doc audit (just-module-creator's gene_metrics.md)

What was wrong, measured on the published snapshot rather than estimated

The live GraphQL route wrote "|".join(sorted(flags)) if flags else None. The snapshot route copied gnomAD's bulk-TSV cell verbatim, and gnomAD writes a JSON array literal there. Re-probed against /data/.../gnomad_constraint/data/*.parquet before any code was touched:

cell rows what a consumer got
[] 17,403 if row.constraint_flags: → true, for an unflagged gene
a real array literal (["outlier_mis","outlier_syn"], 14 distinct shapes) 708 splitting on \| → one bogus token, never two flags
null or empty 0 —

So if row.constraint_flags: was true for 18,111 of 18,111 rows — 100%, where the true flagged fraction is 3.9%. The field description ("kept verbatim and pipe-joined") was false on the snapshot leg in both directions, and constraint_flags is inside GENE_METRICS_FACT_FIELDS, so the same gene fetched two ways minted two gene_metrics.signature values.

The decision, and the one thing it changed on contact with the code

Pipe-joined when non-empty, None when empty, on both legs — never in doubt: enricher/tests/test_gnomad.py had pinned constraint_flags is None on the live producer since 0.5, so the contract existed, was tested, and the snapshot producer had simply never implemented it. The item was filed as needing a decision when what it needed was a release.

What the entry did not anticipate is where the normalizer belongs. It said the normalization "goes in the cell" rather than in a public accessor, and that argument, followed properly, puts it on the model — just_dna_format.gene_metrics.normalize_constraint_flags, bound as a mode="before" validator on the field. mode="before" because neither producer hands over the str | None the field declares (a Python list from the API, an array literal from the TSV), and a mode="after" validator cannot rescue a value the field's type rejects first (@yaml-version-int).

Putting it in the fetching tier would have fixed the wrong half. The published v4.1 snapshot is immutable, and every gene_metrics.csv already written from it — including this repo's own reference_examples/hboc_palb2/ — carries [] on disk. A producer-side fix makes new tables agree with each other and leaves those still contradicting the column's description and still hashing apart from a live fetch. On the model, one function reaches every producer there will ever be, a hand-written table, and a re-read of a file some earlier release wrote.

Three call sites nonetheless, and each earns its place: the live route (so the payload is normal before it becomes a row), gene_metrics.lookup_snapshot (so the published snapshot reads correctly — the leg that matters most), and constraint_build._gene_record (so a snapshot built from here on is clean at source). All three are the same function, so they cannot drift; it is idempotent, so a rebuilt snapshot passes through unchanged.

What "empty → null" would have missed

Half the finding. It clears the 17,403 [] rows and leaves the 708 flagged ones still unparsed, so a consumer splitting on | still gets one token. The non-empty cells needed parsing, which is why the normalizer takes the cell apart instead of testing it against a null set. A bracketed string that does not parse is kept verbatim — this normalizes an encoding it recognises and invents no reading for one it does not, and a cell surviving unchanged stays visible to whoever reads the table.

Cost, measured

Exactly one row in the corpus: reference_examples/hboc_palb2/gene_metrics.csv carried constraint_flags=[], so its gene_metrics.signature and artifact.digest move and nothing else in the sixteen examples does. The checked-in file was corrected in the same commit, so it now holds what the model stores. Beyond that it is whatever consumers have compiled from the snapshot, which nobody has counted — which is the entire reason this is a minor with a CHANGELOG line rather than a patch.

The test that would have caught it

enricher/tests/test_constraint_flags_normalization.py, and its shape is the durable part (@one-normalizer-two-spellings): it runs both producers' raw tokens through the one function and names the answer both must reach. A suite over the live leg alone was green throughout — that is exactly what let this survive a release. The pre-fix behaviour was demonstrated before the tests were called a regression net: an unflagged gene read as flagged, and a two-flag cell split to one token.

RM147 — a source read by hand that yields no row had nowhere to go, and the home already existed

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format, documentation only — no behaviour changed). Severity low-medium · Owner format · Motivating case S82 (just-module-creator)

The question

An agent read five literature services by hand — Crossref, Europe PMC, OpenAlex, PubMed, Unpaywall — to find and confirm the papers behind two rows, and recorded that as five licensing.csv rows at layer=literature. The reporter removed them, correctly, on our own two rules: a literature source's terms are per article and live on LiteratureRow (RM46), and a pass that put no row in a table records no source (S77/RM142). They measured that the rows bought no enforcement — identical verdicts and warnings with and without them, since literature-layer rows are exempt from the orphan check.

Then they asked the real question: after removal there is no trace anywhere that a human went and looked, and found the second paper the module's whole claim rests on. They offered three readings and were attached to none.

The answer: reading (2), and the home is already built

Their reading (2) was "it belongs in logs/, and nothing writes it". Close, and the file is literature.csv rather than a log. A row no study, bin or pharm row cites is kept in the CSV and dropped from the artifact with literature_row_uncited — shipped since RM79 for the case of a citation the author deleted, and the same shape answers the opposite case exactly: a paper that was read and did not become a row.

That gives the consultation the three properties the report wanted and a log would not have. It is structured — a pmid, a doi, an exists verdict, checked by the same pass that checks a cited one. It cannot make a licence claim, which is what made the original rows wrong. And it is about the paper, which is the thing that was actually consulted; a service is only how the author reached it, and it is the paper that carries terms.

The compiler dropping the row from the artifact is right rather than a loss: nothing in the module joins to it, and the CSV is where the author's own record lives.

Documented rather than built, and that is the whole change

Nothing in the code moved. LiteratureRow's docstring now says the uncited row is this case's home and why the licensing table is not, and a test authors the reported shape end to end: two articles, one cited and one not, a green --strict compile, literature_row_uncited naming the unused one, and no licensing.csv at all — because nothing is owed for reading an abstract.

The readings not taken

  • (1), "it should not be recorded." Their straight application of S77, and the near miss. S77 is about obligations: a source that contributed nothing creates none. It is not a rule that the looking is uninteresting — and the looking is a fact about a paper, which this format already has a table for. Answering (1) would have made human search effort invisible by a rule that was never about visibility.
  • (3), a new layer member or a boolean meaning "consulted, contributed nothing". The reporter was least confident in this and named the reason themselves: a row meaning no obligation, sitting in the obligations table, re-opens the check-that-cannot-fail shape S77 had just closed. Agreed, and it is worse than they said — VALID_SOURCE_LAYERS is a wire vocabulary, so the member would be permanent under P3 for a fact that has a home already.
  • Keeping the rows as they were. Their own rejected candidate, and their argument is the one to keep: a pubmed,literature row with blank permission booleans sits one column from a false all-clear for text quoted out of a cc by-nc-nd paper.
  • A logs/ writer. Their (2) read literally. The transport exists, but a log line is unstructured, unchecked and unqueryable, and would have made us specify a line format that publishes. The typed row is strictly better and needed no new surface.

Charter check

P3/P8/P9 — a docstring and a test; no field, no vocabulary member, no behaviour, and zero cost on the authored layer. Measured: nothing in the corpus changes, so the 0.7.0 release record is unaffected.

RM148 — direction and stat_significance are one pair, and the description did not say so

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format). Severity low-medium · Owner format · Motivating case S83 (just-module-creator)

The measurement

Two runs of a byte-identical prompt, same model, same paper, authoring rs117385980 for a longevity module. Both green through every gate, and they wrote different values in direction for the same variant on the same evidence: risk/suggestive against unknown/not_significant.

The evidence: two cohorts trending the same way, p ≈ 0.074 and 0.073, combined OR 3.58 with a 95% CI of 0.96–13.4 — the interval contains 1 — at 28.4% power. Filed in the same spirit as S80, an hour after that one was accepted.

The answer: not a vocabulary gap, and the reason is the orthogonality itself

The reporter's reading (1), which they identified as the cheap one and which is also the correct one. direction records the sign of the reported estimate; stat_significance records how far to lean on it. They are orthogonal by design — the split RM145 just finished unwinding out of state — and orthogonality is precisely the answer to is a sign you cannot lean on still a sign: yes, because the other column is what says you cannot lean on it.

The state they wanted a member for already exists as the pair. direction=risk + stat_significance=not_significant is exactly a real trend the evidence does not establish, and it authors and validates today — asserted by a test that constructs their row rather than arguing about it.

Writing unknown there is the lossy choice, which is the half the old description left an author to work out. It discards the sign the paper reports and leaves stat_significance making a statement about nothing. So the description now bounds unknown: no sign to record — not assessed, or the sources conflict — never a sign you may not act on.

Why no new member

Their reading (2) — a member meaning looked, and the evidence does not establish a sign — is the one they could most easily imagine and did not push for. It would be a second spelling of the pair, which is Principle 5's overloading arriving as a synonym rather than as a conflation: two ways to say one thing, with consumers splitting on which they read. It is also a wire vocabulary change touching every consumer, permanent under P3, for a state that is already expressible.

A test asserts the two vocabularies stay disjoint but for unknown, over the walked sets rather than by naming members, so a future addition to either has to face this deliberately.

What the fix is

One description string, the RM145 mechanism the reporter explicitly cites — it reaches describe, requirements, reference and any consumer rendering model_fields, and it would have settled their two runs. Their own interim repair (say which value you chose and why in conclusion) stays good practice for a genuinely contested row; it is no longer the only thing standing between two agents and a coin flip.

Charter check

P3/P8 — a description string; no member added or removed, nothing invalidated. P5 — the fix is that principle, stated where an author reads it. Measured: no reference example moves anything.

RM144 — the licence-disagreement warning printed the remainder as though it were the whole set

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-compiler). Severity medium · Owner compiler · Motivating case S79 (just-module-creator)

The defect

_check_declared_license_agrees filtered the annotation-layer rows to those whose licence differs from the module's declaration, then rendered that remainder as if it were the whole set. So a two-source module declaring CC-BY-NC-ND-4.0 — an exact match for one row, and the binding constraint on the artifact — printed declares 'CC-BY-NC-ND-4.0' but annotation-layer sources report ['CC-BY-4.0']. The row that agrees is invisible in the sentence complaining about agreement.

Reproduced at the function, both ways: the matching-one case and the matching-none case produced messages of the same shape, differing only in the length of a list. Nothing in the output told the two apart.

Two problems with different repairs read identically. Your declaration is unsupported means the author picked a licence no source grants. Your declaration is not universal is the ordinary shape of a mixed-licence module, where the most restrictive term binds and the declaration is already right. An author reading the first when the second was true re-adjudicated a module's whole licence position and found nothing wrong — measured twice, in two separate reported rounds, and it survived RM142's fix because removing the phantom CC0-1.0 row leaves a real disagreement still rendered as total.

What shipped

The reporter's option (1): the count leads and the agreeing rows are named beside the disagreeing ones. declares 'CC-BY-NC-ND-4.0' and 1 of 2 annotation-layer source(s) report a different licence: ['CC-BY-4.0'], with a distinct sentence — no annotation-layer source reports it — for the case the old message was actually written for. The tail names the mixed-licence reading explicitly, so an author who sees a partial match knows it is a recognised shape rather than an unexplained complaint.

The denominator counts rows, not distinct licences. Two sources sharing a licence are two obligations, and the number the author is checking against is how many sources they have; counting distinct licences would report "1 of 2" for a three-row file, a number matching nothing in it. Rows with no licence stay outside the denominator — unknown terms are neither agreement nor disagreement — and so do non-annotation layers, or the count would disagree with the set the warning is about.

declares license still leads the sentence: it is the fragment an existing test keys on, and the non-escalation is unchanged and re-pinned — two claims about a legal position disagreeing is not the compiler's to arbitrate.

Repairs rejected

  • Suppressing the warning when any row matches. The reporter argued this against their own case and is right: a module declaring the least restrictive of several licences is exactly the one worth warning about.
  • Their (2), a bare count, and (3), changing only the verb. Both remove the false reading and neither separates unsupported from not-universal, which is the distinction that cost the work. They offered these as cheaper floors; the full form is three lines of code, so the cheaper ones buy nothing.
  • An SPDX compatibility matrix. Unchanged and not reopened: world-knowledge that goes stale, in the wrong tier.

Charter check

P2/P3/P8 — pure text over already-loaded rows; no schema change, no field, no vocabulary member, and no severity change. @warning-text-is-api is the live constraint and the grepped fragment is preserved. Measured: no reference example moves a digest, signature or warning, so the 0.7.0 release record is unaffected — the corpus has no mixed-licence module, which is why this survived it.

RM145 — state's six members were printed as peers, and two of them are retired in our own code

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format). Severity low-medium · Owner format · Motivating case S80 (just-module-creator)

The defect, and how it was found

VariantRow.state was described as One of: risk, protective, neutral, significant, alt, ref. Six values, no ordering, no standing. derive.py calls alt/ref the retired descriptors and maps both to direction=unknown; nothing in the printed string carried that.

A consumer's authoring surface passes our descriptions through verbatim — deliberately, so a vocabulary change reaches an author without them restating it and drifting — so an agent was offered six equal choices and picked alt for a heterozygote, honestly. The reporter had to read derive.py inside their own .venv to author one cell, which is the part they said they would fix first, and they are right: that contract works only while the description carries what an author needs in order to choose.

Their usage measurement recomputed here: across the sixteen reference examples state is 377 risk and 4 neutral, with significant, alt and ref used zero times.

What shipped, and why it is three groups rather than the two asked for

The description now reads: Direction of effect for this genotype. Current: risk, protective, neutral. Superseded, still valid and still read: significant — a significance claim rather than a direction, write stat_significance instead; alt/ref — genotype descriptors carrying no direction, which derive to direction=unknown.

The report proposed current | retired, with significant among the retired. That would tell an author significant means nothing, when it means something this column is the wrong place for. state is the Principle 5 anti-pattern the charter names by hand — one field conflating statistical significance, effect direction and a genotype descriptor — so the split has to be by which axis a value was really on, and derive.py is the evidence: alt/ref map to unknown on both axes, while significant maps to significant on the significance one and is refined from the weight sign before falling back.

Each group names its successor, because a standing with no destination is a warning nobody can clear — P3's own test for whether a deprecation belongs in a minor — and all three successors ship.

Repairs rejected

  • Removing the three. The reporter did not ask for it and it is major-only regardless: published modules carry these values and the read-time effective_* aliases derive from them. They cited S69's lesson about a deprecation claiming nothing else is lost, from the other side.
  • A RECOMMENDED_STATES frozenset beside the closed one. Two lists to keep in step for a fact that fits in the string every surface already prints.
  • A compile warning on a superseded value. Every such module would warn on every build for a value that still works and still derives correctly, and the author of a published module cannot clear it.
  • Fixing it in the consumer's describe_table. Their own rulebook forbids it and they are right to — a restated vocabulary is one that drifts.

Charter check

P3/P8 — a description string; no schema change, no vocabulary member added or removed, nothing invalidated. P5 — the fix is that principle applied to the field the charter cites as its own example. P9 — zero cost on the authored layer; the burden it removes is on the author. Measured: no reference example moves anything, and none uses a superseded member — pinned by a test that recomputes it.

RM143 — the enricher diagnosed a wrong-assembly coordinate and compile --strict built over it anyway

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-compiler). Severity medium · Owner compiler · Motivating case S78 (just-module-creator)

The measurement

A one-variant spec with a GRCh37 coordinate pasted into a GRCh38 module — the ordinary shape of a paper stating its assembly once in the methods and nowhere near the table an author reads. rs61849494 is 10:51613269 G/A on GRCh37 and 10:45982565 C/T on GRCh38: 5.6 Mb apart and strand-flipped.

The reporter walked all four gates. validate passes, correctly — it is offline and cannot know. enrich(strict) refuses, with a diagnosis they call better than anything they could have asked for. enrich(best_effort) reports all three readings and writes the table, which is what best-effort means. And compile_module(strict=True) succeeds, silently, over a module that is internally consistent and about the wrong locus.

Two of the three asks were already shipped, and saying so is half the answer

They offered three repairs in order of preference and asked for our view rather than guessing.

Their (2) — have the compiler re-run the rsid↔coordinate agreement — is refutable on the data. resolution.csv does not hold both coordinates. For a coordinate-authored row the enricher records what the author wrote, so there is one coordinate in the table and nothing to compare it against. The change is not small, it is impossible without a fetch, and P2 forbids the fetch.

Their (3) — make the compile warn — shipped in this same release and they could not have seen it. verification_findings_recorded (S70/RM130) reports every recorded finding at the author. It is absent from 0.6.6, the version they measured. Reproduced: with the diagnosis in verification.json, a 0.7 compile prints records 2 finding(s) across 2 check(s): genome_build_agreement (1 of 1), reference_allele (1 of 1).

Their (1) — record the diagnosis where the compiler can see it — is also mostly shipped, and the verification.json record is that place. What was missing is the last step: no severity attached to it, so the fact was carried and never acted on.

What shipped

build_disagreement_error refuses a strict compile when verification.json records a finding on genome_build_agreement, in both validate_spec and compile_module, with the error equal on both sides and placed ahead of output_dir.mkdir() so a refusal writes nothing.

This does not move the strict line, and that distinction is the item. strict means reproducible, never right — the FAQ says so and it stands. genome_build_agreement is the exception on internal-consistency grounds: a finding there says the module's rows are on a different assembly than the genome_build it declares, which is one authored file contradicting another, not the module disagreeing with an outside archive. Every other recorded finding keeps warning, pinned by a parametrized test over four checks — including reference_allele, which produces this diagnosis's input and still does not refuse on its own, because a ref mismatch has three causes and only one is an assembly.

The compiler adds no judgement. It acts on a record the enricher wrote against a GRCh37 service the compiler may never call. What changed is that the answer stops being discarded at the tier boundary.

Three things it must not do, each with its own test: no attestation is silent (an unverified module is the ordinary case, and refusing on absent evidence reads unknown as wrong); findings=0 is a clean bill, so the gate keys on findings and not on the record's presence; and a skipped record is unknown, which is what an --offline run writes — refusing there would make offline enrichment poison a module.

Repairs rejected

  • A column on resolution.csv marking the row as diagnosed — their (1) read literally. It is a fact about a check in a table of facts about variants, the same axis that keeps fetched_at out of every fact set, and verification.json is the file that already exists for it. Also full cost under P9 for a fact with one reader.
  • Re-running the check in the compiler — their (2), refuted above on the data.
  • Escalating every recorded finding under strict. The obvious generalisation and the wrong one: it would fail a build over a ClinVar disagreement, which the cross-check deliberately refuses to do because the archive is the stale side often enough that the format would be arbitrating someone else's dispute.
  • Telling authors to always run strict enrichment. Their own rejected candidate and correct: best_effort exists for good reasons, and a module authored under it stays wrong forever with every later gate green. The defect was the discarded diagnosis, not the chosen mode.

Charter check

P2 — no fetch; the gate reads an injected sidecar. P3/P8 — no schema change, no field, no vocabulary member; BUILD_AGREEMENT_CHECK names an existing one. P5 — severity and reporting stay separate axes: the warning still fires in both modes and the refusal is the ladder's upper rung. Measured: no reference example carries a genome_build_agreement finding, so nothing in the corpus changes and the 0.7.0 release record is unaffected.

RM142 — the dosage pass declared a ClinGen obligation for a module ClinGen curates nothing of

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-enricher). Severity medium · Owner enricher · Motivating case S77 (just-module-creator)

What was measured

A single-variant SIRT6 module. The dosage pass reported, correctly, that it covered nothing — dosage: missing: [SIRT6] — wrote no gene_metrics.csv row, and wrote a ClinGen licence row into licensing.csv anyway. Reproduced exactly: covered=[], missing=['SIRT6'], zero data rows, licensing.csv present with one clingen row.

Two costs, and the reporter is right that the second is the expensive one:

  • A false statement in a published artifact. licensing.csv travels to the registry and is read as this module uses this source. It is not true of a module ClinGen curates no gene of.
  • It fires declared_license_disagrees for nothing. Reproduced: a module declaring license: MIT and using ClinGen for nothing warns declares MIT but annotation-layer sources report CC0-1.0, and an author then adjudicates a conflict that does not exist. Two agents were measured spending real effort on exactly that in an earlier round.

The compiler cannot catch it, which is what makes this the pass's job rather than a check. The orphan warning _source_checks emits exempts the annotation layer deliberately (RM46), because sources.csv is where an author is told to record a hand-read source and warning about that would make compliance noisy while omission stayed silent. So an annotation-layer row nothing uses is silent by design, and only the pass knows whether it contributed.

The fix, which is what the siblings already do

merge_sources_file is now behind if covered:. That is not a new rule — it is the rule the rest of the family already follows and this one member missed. gene_metrics, frequencies, assertions and gene_validity all pass {row.source for row in out} to record_source_terms, so a pass that wrote no row records no source. clingen.py alone built a fixed row and wrote it unconditionally.

Checked rather than assumed, because the reporter asked us to check the others: enrich_gene_metrics and enrich_frequencies were run offline over a module they cover nothing of, and neither writes a licensing.csv at all. The defect is clingen.py's alone.

covered, not out, and not not missing. out carries rows a previous run merged in, whose terms are already recorded, so keying on it would be keying on history. not missing is the dangerous inversion — it would drop the declaration from every module carrying one uncurated gene beside a curated one, which is a real obligation going unrecorded. Both directions have a test, and so does the second lap, where covered is empty because the work is done and the row must stand.

ClinGenResult.source_row is still populated whatever happened: the terms of what was consulted are a fact a caller may want to render, and they are a different fact from what the module uses.

Repairs rejected

  • Having the author delete the row. The reporter's own rejected candidate and correct: it is machine-written and returns on the next pass, and authors deleting licence rows by hand is a worse habit than the defect.
  • A covered: false marker on the row. Their alternative suggestion. It makes sources.csv carry rows that are not declarations, so every consumer reading the table — the compile gate included — gains a case to handle for a fact that has no reader. Absence already says it.
  • Removing the annotation exemption from the compiler's orphan check. It would catch this and reintroduce what RM46 removed: a warning at the author who followed the documented advice to declare a hand-read source. Compliance warning while omission stays quiet is the wrong direction, and the exemption's reasoning is unchanged.
  • Recording "we queried this source" somewhere. The reporter floated a logs/ entry. Nothing reads it, and a run's history is not what licensing.csv is for — the same axis that keeps fetched_at out of every fact set.

Charter check

P2 — no new fetching; the pass consults exactly what it consulted. P3/P8 — no schema change, no field, no vocabulary member; a licensing.csv that was being written is not written, which cannot invalidate a module that never depended on it. Measured: no reference example changes — none carries a ClinGen dosage row from an empty pass — so the published 0.7.0 release record is unaffected.

The direction is worth naming: this removes a declaration, and a licence table losing a row is the dangerous direction in general. It is safe here only because the row's own predicate is now the thing that decides — a module ClinGen fed keeps its row, checked by test in three arrangements.

RM141 — validate --strict blessed a module compile --strict refused, whenever the resolution table was partial

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-compiler). Severity medium · Owner compiler · Motivating case S76 (just-module-creator)

What was reported, and what reproduced

A consumer's enrich was killed by an external quota limit partway through a 263-subject module, leaving a well-formed resolution.csv covering 201 of them. They reported two things: that nothing on disk marks such a file partial, and — the part that made it urgent — that merge-not-clobber turns it into a silent wrong answer, because the natural recovery of re-running merges onto the stale rows and never retries the missing 62.

The second half does not reproduce, and it does not reproduce on the version they ran either. Probed directly: a run over a table covering one of three subjects asks the source about exactly the other two and commits all three. Measured on this tree and again on v0.6.6 built from its own tag, so this is not something 0.7 fixed underneath them. enrich gap-fills; the merge is over subjects the table records, and a subject it does not record has nothing to merge onto. Their proposed repair (1), writing the sidecar atomically, is also already shipped — layout.atomic_writer, from RM128 in this same release, which is why the interrupted run left the previous table rather than a truncated one.

And the reporter corrected their own account the same day, which sharpens what this closes. From the preserved artifact: the 203 rows are sorted throughout, the last line ends cleanly, and the 62 absent rsIDs scatter across the whole alphabetical range rather than forming a tail. So it is a complete write of an incomplete resolution set, not a half-written file — which matches the code rather than contradicting it, because a subject whose live request could not be made joins unreachable_rsids and is written as no row at all, deliberately, so the table never states a negative nobody established (@unreachable-not-absent). Nothing was interrupted mid-write, so RM128's transaction and atomic writer would not have prevented it, and the same file comes out of a best_effort run that completes normally over an unreachable source.

That re-attributes the closure to this item rather than to RM128, and by the right route: a check reading the table against the spec beside it is the only thing that can see a set complete as a file and incomplete as an answer, and it is indifferent to why a row is absent — which matters, because the cause was misdescribed and the check does not depend on the cause.

What is real is that nothing said so until the compile, and that is a defect of ours.

The defect

compile --strict refuses a module whose variants have no position after resolution — the check that keeps a partial artifact from being published as a reproducible one. validate --strict did not report it at all. So a spec whose table covers some of its variants passed the pre-flight clean and was refused by the compile immediately after: the green-pre-flight-then-refusal shape the parity rule exists to prevent, and the third time that rule has been broken in the same way.

It hid behind the rule's own exemption. What stays compile-only is a check reading resolved rows, and coverage looks like one — but whether the injected table can place an authored row is arithmetic over bytes the pre-flight has already loaded, and needs no resolution to have run. The exemption is about resolved rows, not about the word "resolution".

What shipped

resolution.unresolved_subjects is the predicate resolve_from_table applies, factored out and called from both sides, so the two cannot drift into disagreeing about which rows are unplaceable — the alternative was a second implementation of _usable_loci's three exclusions (a not_found sentinel, a row under another build, a row with no chrom). The pre-flight emits rsid_unresolved with the sentence resolution already emits, and under strict appends the compile's error verbatim, which the test asserts by equality rather than by both being non-empty: a pre-flight refusing in its own words still sends the author hunting.

Two distinctions the fix had to keep, both the compile's own rather than new:

  • Nobody-asked is not asked-and-absent. With a table present, an uncovered row is absent from something that was consulted and is named. With no table, nothing was consulted, and the pre-flight says so once instead of blaming a missing file once per variant. Both still refuse under strict.
  • --no-resolve means the same thing on both sides. The master switch turns resolution off by request, and resolution_disabled already says that once with its row count; the coverage check stays silent there rather than restating it per row.

A double-report was found and fixed while doing it. compile_module runs the pre-flight in best_effort whatever its own mode, so both passes reach this finding for the same subject; appending blind published every one twice, measured at 24 warnings for 12 subjects on a real example, with warnings_summary counting 24. De-duplicated on the message, the _check_contig_ploidy idiom — safe here because no message resolution re-derives embeds a count, which is the condition @no-rerun-with-counts sets.

Repairs rejected

  • A partial-file marker, sentinel, or row-count header on resolution.csv — the reporter's framing. The file is a pure build product since RM124, and a marker in it would be a fact about a run living in a table of facts about variants, on the same axis fetched_at is kept off the fact set. It would also be unwritable by the case that needs it: a killed process writes no marker.
  • A --rederive-style completeness command (their option 3). They offered to build it themselves and asked whether it is theirs; it is neither theirs nor a new surface — compile already answers it, and now so does validate, which is the command their authoring loop runs first.
  • Having enrich refuse to start on a short-looking sidecar. Argued against by the reporter themselves and correct: a deliberately-resolved subset and an injected curated table are both supported practice, and nothing distinguishes either from a crash.
  • Recording the intended subject count in the run's output (their option 2). SubjectProgress already carries (done, total) live, and a durable count of what a killed run meant to do is the marker above wearing a different hat.

Charter check

P2 — pure computation over already-loaded bytes; nothing fetches, and the pre-flight gains no new input. P3/P8 — no schema change, no new field, no vocabulary member: rsid_unresolved and resolution_not_injected are existing codes and the strict error is the existing sentence. Measured: no reference example moves its artifact.digest, content_signature or warnings, so the published 0.7.0 release record is unaffected — none of the sixteen has a partial table, which is why the defect survived a corpus this size.

One test was asserting the defect and was corrected, not deleted: test_quoting_a_noncommercial_article_warns_and_never_gates built a fixture with no resolution.csv and asserted validate --strict reported valid. Its subject is that a licence finding never gates, and the module was independently strict-refusable for an unrelated missing coordinate — so the fixture now injects the table, and the assertion means what it says.

RM140 — a study row's p-value and effect size are asserted to belong together, and nothing recorded what either came from

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format + just-dna-compiler). Severity medium · Owner format + compiler · Motivating case S75 (just-module-creator)

What was measured, and by whom

A reproducibility benchmark the reporter ran: two agents, byte-identical prompts, the same three DOIs, one module each. They overlapped on exactly one row — rs117385980 from PMID 41249831 — and disagreed on its p_value, 0.36 against 0.75, with an identical effect_size of 1.42.

Neither was a misreading. The paper reports two analyses of the same association: an allelic Fisher's exact test giving OR 1.4, p 0.36 on the 2×2 allele table, and a univariate logistic regression giving OR 1.42, 95% CI 0.18–11.67, p 0.75, with five adjusted models after it. One run's row was internally consistent. The other carried the logistic regression's effect_size beside the Fisher test's p_value — one analysis's estimate and another's p-value on one row.

Everything was green, and this is the part that made it an item rather than an authoring mistake: validate_module(strict), compile_module(strict) and audit_module all passed, and quotes_found was satisfied — the provenance quote is verbatim and correct, because it grounds the significance verdict and contains no statistic at all. A quote cannot witness a number it does not contain, so quote verification is structurally blind to this class of error.

StudyRow had study_design — "e.g. meta-analysis, GWAS" — which describes the study. Nothing described the analysis. So a correct row and a mispaired one were byte-indistinguishable to every consumer and every check, and no check could be written, because the facts it would compare were not recorded anywhere.

What shipped

One optional free-form column, StudyRow.statistical_test, shaped like study_design beside it: which test or model produced this row's p_value/effect_size, and what it was adjusted for. Plain str | None, no vocabulary marker, no RECOMMENDED_* set — the space is open and a recommended set is additive later if a corpus ever shows a shape. Wired through all four touch points, with the round trip watched failing on each of the last two in turn before the test was called done.

And one behaviour change, which is what makes the column do something. duplicate_study_citation fires on a repeated (variant_key, pmid) because the check's own docstring reads that pair as the same claim written twice — which two rows naming two analyses are not. Since this item, both stated and different suppresses it. Nothing else does: an absent statistical_test is unknown, and unknown against a stated value cannot establish that two rows describe separate work. Kleene, not a != b — the naive form would suppress on every absent cell and silently retire the check for every module written before the column existed.

StudyRow._KEY_FIELDS is not widened, which the reporter explicitly scoped out and which is also the legal answer: that tuple drives hints.key_fields and the key.columns an authoring surface publishes, and re-keying a shipped authored table changes what an identity key means — major-only under P3. The check restates (variant_key, pmid) rather than reading _KEY_FIELDS, so the split is contained in the one place that needed it.

Repairs rejected

  • A validator requiring the pair to come from one analysis. The reporter argued this against their own ask and is right: it cannot be written, because nothing on either side of the boundary knows what test a number came from until the column exists, and adding column and gate together would make every published row retroactively incomplete. Column first, and possibly never a gate — what a gate would need is a second recorded fact per number, not a stricter reading of one.
  • Widening (variant_key, pmid) to carry an analysis. Above. Also unnecessary: both rows already reach studies.parquet today — the duplicate is a warning, never a drop — so the capability was present and only the legibility was missing.
  • A RECOMMENDED_STATISTICAL_TESTS vocabulary. A recommended set is a claim about what the corpus contains, and one module is not a corpus. Open now, additive later.
  • A second warning code for the half-stated pair — one row naming an analysis, the other blank. Considered and not taken: it is one more permanent key for a case that is a transient state of an author mid-adoption, and the existing message plus the rule stated in COMPILER § the analysis grain covers it. File it if anyone actually reports being stuck there.
  • Editing a reference example to exercise the column. It moves digests for no gain and manufactures the RM139 one side only case at the next cut. Test fixtures only.

Charter check

P3 — a new optional column on an authored model: additive, minor-legal, and it lands inside the already decided 0.7.0. P8 — optional with respect to every published module, so nothing previously valid becomes invalid; pinned by a test asserting two specs differing only in the presence of the column hash to the same content_signature. P5 — study_design and statistical_test are separate axes, and a future analysis_covariates sits beside this one rather than inside it. P7 — the round trip carries the value and the digest is a fixed point. P9 — full cost, an authored column, and the answer is that the rare author here is the one asking: an unset cell burdens nobody and the alternative is prose in a README that no consumer can read.

What it measured

artifact.digest moved on 10 of the 16 reference examples — exactly the ten carrying a studies.parquet — and content_signature on none of the sixteen. The same shape RM91 measured when it added effect_allele, for the same reason: a new column in a materialized table moves bytes and no authored identity.

The published 0.7.0 release record was re-measured rather than left standing. RM126's record carries measured counts, and this item landed after they were taken: the 0.6.6 → 0.7.0 sweep was re-run end to end with 0.6.6 built from its own tag, and the two parquet axes went from 4/15 to 14/15 while content_signature stayed 0/15. studies.parquet:statistical_test is declared on both axes, and the concordance-parquet declaration calling itself the release's most visible consequence was corrected in place — it was a measured claim, and ten digests to four is no longer that. The gate exits 0 against the amended record. A stale measured number reads as an all-clear, which is the failure this repo keeps meeting from the other direction.

The suppression is a loosening of a warning, not of validity: no module that compiled stops compiling, and no module that was silent starts warning. The message and code are byte-identical for every case that still reports (@warning-text-is-api), pinned by its own test.

RM139 — the release gate could not tell a broken compile from a spec that outgrew the old compiler

Shipped on 2026-08-31, inside the uncut 0.7.0 (just-dna-format + just-dna-compiler). Filed by running RM126's gate for real at that cut, decided and built the day after.

Severity medium · Status ✅ shipped · Owner compiler · Found by the 0.7.0 cut

gate_findings failed a release when a module compiled on one side only, and its reasoning was sound as far as it went: the likeliest operator error is running the sweep before uv sync propagated the bump, and a module vanishing into an all-False result over its surviving neighbours is a false green in the one mechanism the item rests on. But one side only was read as a compile failed, and the very first real use of the gate hit the other cause. RM70 added the optional requires_callable column to pharm_variants.csv, reference_examples/cyp2c9_warfarin_grch37/ uses it, and 0.6.6 refuses that spec under extra="forbid". Nothing failed: the previous release cannot produce a before state for that module at all, so no like-for-like comparison exists and the sweep is right to say nothing about it. The 0.7.0 record stated the exclusion in evidence prose the gate cannot read, and the tag was waved through by a human — which is the state this entry ends.

The decision, in two halves.

Which side, not whether. The two directions are facts about different releases, and collapsing them lost that. A module in the BEFORE tree and not the AFTER one is a regression in the release being gated — it fails unconditionally, and now carries the compiler's own errors, which build_outputs had been logging and discarding. A module in the AFTER tree and not the BEFORE one is a fact about the previous release: whatever the cause, nothing in this release failed, and there is no measurement to declare. A stale reused BEFORE directory holding a module the spec root no longer has reads as the first, which is the fail-safe direction; the runbook already says fresh trees every time.

The exclusion moves into a field the gate reads. ReleaseRecord.unmeasured names the modules the previous release produced no output for, and the second direction fails until the published record lists them. Old records read [], which is the correct claim for them.

Why that is not the per-module escape hatch this entry originally refused. The refusal was right about the shape it named — a field an operator can use to silence the gate is weaker exactly where the docstring warns — and unmeasured is not that field, because the check is an equality over the measured set rather than a membership test (@registry-completeness). It cannot cover a module the sweep measured on both sides: listing one is reported as a note. It cannot cover a module this release broke: that direction is fatal however it is listed, and as_record refuses to mint a record over one. And a movement on a measured module still gates however the list reads. What is lost, precisely and only, is that the previous release could not compile module X no longer blocks a tag — which is right, because it is not a fact about the release being cut. What is gained is the forcing function: as_record fills the field from the measurement, so the exclusion is committed to the published record rather than remembered in a sentence nothing checks. That is the same mechanism declared already uses, extended to the unmeasured set, not a second kind of gate input beside it.

The other three refusals in the original entry stand and were not revisited: the sweep still cannot see the authored spec at the previous version, compiling the old spec from git would vary input and compiler, and demoting the check to a note would re-open the false green RM126 exists to close.

Measured, not asserted. The 0.6.6 → 0.7.0 sweep was re-run end to end over all sixteen reference examples with 0.6.6 installed in an isolated environment: fifteen measured, cyp2c9_warfarin_grch37 refused by 0.6.6 on requires_callable]: Extra inputs are not permitted, and the gate now exits 0 against the shipped record instead of needing a human to read past it. Removing a module from the spec root exits 1 on the other direction, naming it.

The prose-versus-field shape is the recurring one. A count or an exclusion stated only in a sentence goes blind — the triage threshold counter did it twice — so the field is pinned to the sentence by a test rather than maintained beside it.

RM126 — nothing tells a consumer what a release changed about compiled output

SHIPPED in 0.7 on 2026-08-28 — just_dna_format.release_records (record, needs_recompile, roster), just_dna_compiler.sweep + just-dna-compiler sweep (instrument and gate), and 0.6.1/0.6.6 backfilled by measurement. See SCHEMAS § The release record and COMPILER § The release-record sweep.

Decided in PROPOSAL_0_7 on 2026-08-28 — BUILDS in 0.7, in full plus the S65 roster. Record + needs_recompile in format, the sweep in the compiler, the gate in the bump→tag sequence; intervals compose as a union over (a, b], which is what gives S65's convergence requirement for free.

Severity medium-high · Status ✅ SHIPPED in 0.7 (2026-08-28) — the record, needs_recompile, the roster, the sweep and the release gate. The charter required this channel: Principle 3 says a corrected derivation may ship in any release but never silently, and this is the declaration it mandates. Until it exists the charter describes a surface that is not there · Owner format (record + needs_recompile) + compiler (the sweep) · Motivating case S62 (just-dna-registry)

A registry sweeping its catalog for artifacts that should be recompiled has two questions it can answer and one it cannot. Is the stored input still legal? — re-run validate_spec, which answers ok. Was this compiled under a contract-incompatible compiler? — compare versions, and a patch is compatible. Neither is the question a changed derivation raises: would recompiling this artifact produce different output than the stored one? Today the only way to answer it is to enrich into a scratch directory, recompile and diff — which is the operation, not a triage for it.

Reproduced here, and it is wider than the report. All sixteen reference_examples/ compiled under v0.6.1 (detached worktree) and under 0.6.6, spec inputs byte-identical across the interval — the whole of which is patch releases:

measured
changed at least one published manifest field 16 / 16
moved artifact.digest (and artifact.files with it) 10 / 16
moved content_signature 0 / 16

compilation.compiled_at is a timestamp and is excluded as noise. The digest movement is not noise: studies.parquet grew by exactly 257 bytes on each of the ten because RM120 added the authored column curator, first present in v0.6.5. So the parquet schema moved across a patch interval, which is the sharpest form of the finding and the one the reporter had not seen — they reported changed manifest fields. stats.genes/stats.gene_count moved on seven (RM121) and literature.quotes_unchecked appeared on three (RM119). Six of the sixteen changed a published, indexed manifest field with both hashes byte-identical — apoe_epsilon went genes: [] → ["APOE"] at the same artifact.digest and the same content_signature. That is the sharpest number here and the one the surface has to answer to.

Authored identity held throughout, which is the charter working as designed: an unset optional column is omitted from content_signature, so nothing a consumer keys on moved. That is exactly why no existing surface can see this — a digest comparison, a signature comparison and a revalidate all correctly report no change while an indexed field goes stale.

The shape asked for is a declaration keyed on the interval rather than on a version, because the question is always compiled under X, installed Y, with the axes separated — parquet schema, parquet bytes, content_signature, and the set of manifest fields. Deliberately not a should_rebuild verdict: the same fact carries different costs per consumer (a stale cache is a free rebuild for just-dna-lite; for a registry it mints an immutable PATCH and moves what a client tracking latest receives), so the decision is the consumer's and only the fact is ours.

Three things the design has to get right, and the third is why this is filed rather than shipped.

  • Unknown must be a state, not an empty result. Asked about an interval the installed package has no record of — an artifact compiled under something newer, or older than the table reaches — the answer is cannot say, never nothing changed. That is the house tri-state (None is never False), and without it the surface is worse than nothing, because a consumer would stop recompiling on the strength of a silence.
  • content_signature needs its own axis, separate from bytes. For a registry a signature is a permanent global duplicate-content claim that only a purge frees, so the identity moved in a patch is an answer to fail loudly on rather than merely to act on. Our sweep says it has never happened; the axis exists so that stays checkable rather than remembered.
  • A hand-kept per-release map is the defect wearing a public name. The reporter said so themselves, and it is @registry-completeness — five of the six RM104–RM111 fixes were a derived value restated by hand. So the map has to be a measurement: the sweep above is the guard's prototype, and it is cheap — check out the previous tag into a detached worktree, compile reference_examples/, diff the manifests, and fail when the declared hints disagree with what actually moved.

The shape, decided 2026-08-21 in the S62 thread — two axes, and only one of them is measurable.

  • output_differs — measured. One record per release, produced by the sweep: parquet schema, parquet bytes, content_signature, and the set of changed manifest fields. Intervals compose as a union over the releases in (a, b], so storage is linear rather than O(releases²) and moved-and-moved-back still counts as moved, which is the right reading for staleness. Backfillable for 0.6.1→0.6.6 by measurement with the harness that produced the numbers above; older intervals stay honestly unknown.
  • Correction versus addition — declared. Only the person fixing the bug knows whether the stored value was wrong (stats.genes) or merely absent (curator), and no diff can tell them apart: both look like "a field changed". This is the canary — not a minor, but rebuild time — and it is the half the consumer cannot compute for themselves at any price.
  • The gate is what keeps the declaration honest. A release whose sweep shows a changed field with no declaration covering it fails. That is what stops this becoming the hand-kept map everyone agrees it must not be: the measurement forces the declaration rather than the author remembering to write one. A release where nothing moved records a measured zero with its evidence, never silence (@tautology-zero).

This does not contradict the reporter's "no should_rebuild verdict", and the item must say so. Their objection is to a cost verdict, because the cost differs per consumer. The correction flag is not a cost judgement — it is a fact about whether a value we published was wrong, which is upstream knowledge only this repo holds. The per-axis breakdown stays exposed underneath it, so a consumer who wants the facts rather than the flag still has them. A bare boolean with nothing under it would deserve their objection exactly.

Tiers. The record, its model and a pure needs_recompile(compiled_under, current) belong in just-dna-format — a static table plus a function, which pydantic-only holds comfortably, and format is the tier every consumer has. The sweep instrument belongs in the compiler, since producing a record means compiling. The gate runs in the bump → uv sync → tag sequence rather than as an ordinary test, because it needs the previous release actually installed. Keyed on compiler_version, which is what manifest.compilation already stamps and what a consumer holds. Scope v1 to compiler-derived outputs and say so — enricher-side outputs stay unmeasured rather than unchanged.

Open, because the representation is not obvious. An interval table is O(releases²) unless it is composed from per-release records, and composing them means deciding whether the axes are unions (a field that moved and moved back still moved) — probably yes, but that is a decision. The tier is open too: the natural caller is a consumer of just-dna-compiler, and the hints describe compiler behaviour, but a verify-only consumer holding just-dna-format alone has the same question about a manifest it can read. RM127 is why this is needed rather than a nicety, and it is now closed: a corrected derivation is a bug fix, deferring it to a minor means serving a wrong value meanwhile, so the release number cannot carry staleness and a second channel is the only resolution left. The charter amendment of 2026-08-21 made that a rule, which is what turns this item from a nicety into a debt.

Four constraints handed back by the consumer who built the other half (S65, 2026-08-21)

just-dna-registry shipped the recomputation side as services/rebuild.py in their 0.21.0 and reported what building it taught them. Each of these narrows the design and none was visible from here.

  • Convergence is a hard requirement, and the obvious shape fails it. If a hint fires for a version compiled by the exact compiler now installed, recompiling derives the same value again — so an automated sweep mints a fresh PATCH every run, forever. That is the a patch is not a gap rule re-entering by a different door. The interval-keyed shape gets this for free, because the interval from a version to itself is empty — so state that as load-bearing rather than incidental, since a field-keyed or "latest known defect" shape would not have the property. It is also what bounds a false positive to one wasted version number per module ever, which is what made them willing to act unattended at all.
  • Recomputability splits the problem in half, and the better half already shipped. For a manifest field that is a pure function of the authored rows, a consumer can recompute the current answer from stored inputs — no enrichment, no parquet, no network — using spec_tables (RM116) for the defaults-folded rows and module_stats (RM121) for the derivation. Neither landed for this reason. So what would help most is not a bigger table but a small published roster: which manifest fields are pure functions of the authored rows. That is a fact we hold and they guess at, and it shrinks this item rather than growing it. The interval-keyed table then only has to cover what a consumer cannot recompute — literature.quotes_unchecked (RM119) is their worked example, since it derives from a sidecar rather than from authored rows.
  • The roster's boundary is conditional, and the condition is invisible from outside. validate_spec computes stats over the full row set; compile_module re-derives over the survivors only when the symbolic-allele drop removed something. So a recomputation from authored rows is the pre-drop side, and manifest.stats legitimately disagrees with it — permanently, under any compiler — for a module that lost the sole row naming a gene. A roster stating "pure function of the authored rows" without that condition would send consumers to spend version numbers on modules that are current.
  • compilation.dropped_rows closes the residue, and shipped 2026-08-24. Their guard discriminates on variant_count, which catches a drop from variants.csv; a drop inside a kind table moved no published counter at all. With the counter, the stats half of the roster is unconditionally checkable. They rejected reading the warning text for the reason our own catalogue rule gives.

Scope it for coexistence rather than replacement, at the reporter's request. Their probes sit behind one named seam so a probe this covers retires by deletion, and they may keep one or two anyway — a recomputation checks the artifact actually in front of them, a hint states what a release did in general, and the two fail differently. The useful division: we state what a release did, they check what a specific stored artifact says. And they are not re-asking for should_rebuild; building the decision themselves is what surfaced all four constraints above.


RM134 — PubMind as a literature-derived annotation authority, and a ClinVar concordance check

Decided in PROPOSAL_0_7 on 2026-08-28 — BUILDS in 0.7, pulled in after the other eleven were decided and reviewed against them. Eight corrections, two of which were defects that would have shipped: the concordance record is shared with RM130 and RM130's shape changes because of it (ClinSigConflict names its authority in a field, so a second authority would have cost a key change or a retype — major-only); and one normalizer, not two, after two fixes — _normalize_clin_sig's map keys are underscored while PubMind's tokens are spaced, so Uncertain significance and Conflicting both fall to other today and the check would manufacture a disagreement on PubMind's largest disagreeing class. A maintainer stress test at five authorities failed the drafted vocabulary: pubmind_only/clinvar_only name the authority inside the member, because one field carried two axes. Split into authority_concordance and authored_position, five members each at any N. Nothing resolves a split — E+A agreeing against B/C/D needs a weighting model this repo has refused to invent three times — so the precedence list is recorded as methodology and computed with by nothing. Licensing governs what a module may do with the values, not whether the machinery exists: unknown terms warn and never gate, and publishing such a module is RM27's axis.

Severity low-medium · Status ✅ SHIPPED in 0.7 — all four sections (§ A the snapshot and the shared normalizer, § B the N-authority check, § C draft-panel --source pubmind, § D the hint) · Owner enricher · Motivating case the PubMind paper (doi:10.1038/s41467-026-76834-4, 20 August 2026), and a user direction on 2026-08-28 to design both a ClinVar-shaped derived table and a ClinVar concordance check · Full design PUBMIND_ASSESSMENT.md

Residuals RM320

PubMind extracts variant–disease–pathogenicity associations from 41.7 M PubMed abstracts and 5.4 M PMC full texts with LLaMA-3.3-70B behind a fine-tuned BERT triage stage. It is a source, not a competitor: its own discussion calls it "a literature-grounded complement to human curated databases", and the description holds one layer further down — it produces assertions and stops exactly where we start, at identity, integrity, licensing and the round trip. The only contested surface is its pitch to institutions wanting their own interpretation database, which is our module author's use case; what it hands them is a SQLite file behind a Flask app.

What is reachable, measured against the bytes rather than the paper. The web API takes gene, MONDO and PMID/PMCID only — an rsID query is refused — and returns aggregate counts, never a record, which the response says outright. So the single per-variant channel is the coordinate table ANNOVAR redistributes as hg38_pubmind_db (2026-08-24, 6.5 MB gzipped, 909,224 rows: PVID, pathogenicity_sum, paper_level_pathogenicity_score, confidence 0–3). Its coordinates are VCF-style despite the ANNOVAR packaging — no - alleles anywhere, deletions carry the anchor base — so it joins our chrom/start/ref/alts with no translation. Whether the indels are left-normalized is not established.

It is much smaller than 909,224. 439,388 rows (48 %) are enumerated codon alternatives, not observed variants: where only a protein change was recovered from text, every codon encoding that amino acid is written out, and 439,383 of those triplets need two or three simultaneous base changes to reach the reported protein — which is a statement about the protein, not a position anyone can genotype. Decomposing the single-base codons leaves 342,209 distinct chrom:start:ref:alt keys over 305,935 loci as the honest joinable layer. 523 rows have Ref == Alt.

Consolidation is on extracted text, never on a coordinate, so PubMind has record identity where we have variant identity: 68,744 coordinate keys (8.4 %) carry more than one PVID, worst case 35. At chr6:26092913 G>A (HFE C282Y) eight PVIDs disagree four ways, and one of them — PVID926871, verdict Benign — pairs rs1800562 with gene TMPRSS6, a chromosome 22 gene on a chromosome 6 variant. _gene_locus_conflicts catches that shape today (@gene-locus-relationship).

Worth on our own corpus: 173 of 423 GRCh38 reference_examples loci matched (40.9 %), 190 of 589 authored ALTs exactly (32.3 %), and where both sides state a verdict they agree on 83 of 134 (62 %), every disagreement running our-pathogenic vs their-uncertain-or-benign. That profile — real breadth, low confidence — is a cross-check source, not a fact source.

The design, directed 2026-08-28, is four sections. An earlier draft of this entry stopped at a report-only check and recorded the rest as blocked; that framing is overtaken, and the licence constraint moves from reason not to design to precondition on shipping.

A. pubmind build / pubmind publish, a sub-app beside clinvar, mirroring clinvar_build.py: polars builder, fixed column order for a byte-identical rebuild (P7), one parquet plus release.json through locations. Schema follows _empty_schema()'s split, except no column is a resolver link — "authority" here means an authoritative annotation source the way ClinVar is one, never resolution.csv's authority (@source-vs-authority), because PubMind's coordinates are PyEnsembl back-mappings of extracted text. pathogenicity_sum maps into VALID_CLIN_SIG with the composite kept verbatim in pubmind_sig_raw, the clin_sig_raw precedent. Every normalization drop is counted into release.json rather than silently applied (@dont-discard-computed): 160,090 codon rows decomposed, 439,388 enumerations and 523 Ref == Alt rows dropped, 20,131 indels kept but stamped, and PVID fan-out kept as separate rows because collapsing it would pick a winner by an ordering nobody defined. publish refuses, on the PharmVar precedent (@gated-source-caches) — a bulk file under terms we cannot establish is not one we may pass on, and the command exists and refuses rather than being absent, which would read as an oversight somebody helpfully fixes.

B. A three-way check, module ↔ ClinVar ↔ PubMind, beside the existing ClinVar clin_sig check rather than replacing it. Seven outcomes — concordant, authored_dissents, authorities_differ (the case nothing today can report), pubmind_only, clinvar_only, neither, unchecked — combined under Kleene, with unknown withheld and never negated. ClinSigConflict.opposed already draws the severity line (opposed vs merely different) and is reused rather than re-invented. Warning-tier in both modes, never escalating (@clinsig-never-escalates), and authorities_differ is not a module defect at all. Corpus-wide concordance is stamped into release.json at build time only — our own reproduction of their 10.6 % / >80 % claims against our denominator — because a message embedding a count that runs twice publishes two numbers (@no-rerun-with-counts).

C. Drafting, through --source pubmind on the existing draft-panel rather than a new command, since it writes the same tables from the same gene argument and a twin would duplicate the genotype worklist, placeholder guard and dedup pass. --min-confidence is the min_review_stars analogue; identity is coordinate-whole or nothing (@identity-whole-or-none), most PubMind rows carrying no rsID. The self-agreement trap has an existing answer: a module drafted from PubMind and then checked against PubMind agrees with itself, so pubmind joins DRAFT_PROJECTIONS projected onto clin_sig (@draft-digest) — raw CSV cells at draft time, and the skip a conjunction of release and digest. The ClinVar half of B is unaffected, which is why the three-way shape earns its keep.

D. The hint surface, unchanged and cheapest: surface verdict, confidence, paper count and PMIDs beside the cell, and never pre-fill clin_sig (@hint-redundancy-bearing) — the same defect @draft-digest solves one layer down, without a digest to rescue it.

The gate is one unanswered question, and asking is the unblock action. A and D are buildable now; B and C acquire and carry values. The ANNOVAR-distributed table publishes no data terms — LICENSE.md covers the software (academic, non-commercial), the paper is CC BY-NC-ND, the table itself says nothing, and unknown is not permissive (@no-named-licence). Ask WGLab and CHOP's Office of Technology Transfer in writing; it will not resolve itself by the file continuing to download without a key. Separately, the redistribution axis is RM27's, shipped in 0.6 as record-only with the registry named as the enforcer at publish (@redistribution-ungated; this sentence said RM27 still owed it until 2026-09-27) — a gate on publishing a module that carries such bytes, not on building the snapshot or running the check locally, and conflating the two is what stalled this area in the first draft.

RM133 — a card subtitle has no amendable home, and the binding is not where that gets fixed

Decided in PROPOSAL_0_7 on 2026-08-28 — BUILDS in 0.7, on the authored layer at zero cost. short_description joins the registry-owned family as a separate frozenset beside IDENTITY_AUTHORITY_KEYS, stripped by the same function, so the stored bytes are untouched and the closure stands; the ~120-character calibration ships as a constant rather than being guessed at downstream.

Severity low-medium · Status ✅ SHIPPED in 0.7 (2026-08-28) — the binding question it arrived with is answered and closed · Owner format (+ registry, for the half that is theirs) · Motivating case S64 (just-module-creator) in CONSUMER_SUGGESTIONS_HISTORY.md

Measured by the reporter: editing module.description from 44 words to 11 moves no content_signature, no artifact.digest, no fact signature — and drops the closure, because manifest.inputs covers the raw bytes of module_spec.yaml. README.md, by a wide margin the longer prose, is outside inputs and freely amendable. The shortest fixable prose in the system was the one that could not be fixed.

The binding stays as it is, and the reason is the partition, not the cost. The ask was to split it along the line content_signature already draws. That line is stated in integrity.py and excludes name, version and namespace alongside title and colour — so a binding drawn there makes a closure transferable across a rename: a module closed and signed by a named reviewer keeps its attestation after its identity is changed. content_signature excludes those so a registry strip does not move content identity, which is right for a content-dedup key and exactly wrong for an attestation. The two hashes cannot share a partition because they answer opposite questions about the same fields. Do not re-propose this.

The reporter's narrower six-field version (title/description/report_title/icon/icon_set/ color) does not carry that attack and is recorded as the better form of the idea. It inherits the cost they named themselves — hashing a parse of the yaml, and so every canonicalization question content_signature answers, with two hashes able to disagree about what counts as display. RM82 is the precedent that prices it: the last change to the binding turned on being a byte transform needing no loader, no parse and no schema knowledge, and refused BOM/whitespace/final-newline because each "makes the binding more content-ish without making it content". A field-aware split crosses that line on purpose.

What the binding buys, since the reporter asked and could not construct it: it is the reviewer's claim rather than the artifact's. The other two hashes answer is this the same data and are these the same bytes; this one answers is this the same document a named person signed off. A card subtitle is a claim about what the rows mean, so excluding it would make the attestation cover less than the reviewer actually read.

The route that actually unblocks it, and it is the item. The framing "the binding overrides the registry's rule from a layer below" assumes an amend must rewrite the stored module_spec.yaml. It need not: normalize.IDENTITY_AUTHORITY_KEYS (namespace, owner, canonical_id) is the standing precedent for registry-owned metadata that sits beside the module rather than inside it, with strip_authority_keys handing the spec to our validator without them. A registry-owned display override leaves the stored bytes untouched, so manifest.inputs still matches, verify_manifest still passes and the closure stands. So the registry's amend_display is not gated on this item — it is gated on whether the amended value is registry-owned or a spec rewrite.

What is left to design: where a bounded short_description lives so that it lands amendable. Not on ModuleInfo — under the answer above every field in module_spec.yaml is on the un-amendable side, so putting it there reproduces the defect in a new place, which is the reporter's own objection and it is correct. Their argument for why a max_length is legitimate on a new field where it is not on description holds and is why this is a real item: a field that exists to fit a fixed layout is specified by that layout, it refuses nothing anyone has written, and absent it everything behaves as today. Calibration from the live catalog: ~120 characters, against a measured 71 (comfortable) and 467 (the case that prompted it).

Not in scope: render-time truncation or folding, which hides prose an author chose to write and leaves the spec as wrong; and anything retroactive to the seven published modules, which met every requirement that existed.

RM71 — the alleles a drafted genotype stub must be written from are in no file

Decided in PROPOSAL_0_7 on 2026-08-28 — BUILDS in 0.7, and no schema moves. The answer to where does an author do this work is in the command they already ran: the worklist covers every stubbed row in the file rather than only this run's additions, and draft-panel gains the --dry-run that draft has. The bulk advisory command is rejected for putting the worklist in a third place.

Severity medium · Status ✅ SHIPPED in 0.7 (2026-08-28) — the worklist now covers every stubbed row in the file, and the --dry-run the decision asked for turned out to have shipped in 0.5.1 already, so what landed is the test that pins it · Owner enricher (clinvar_draft) · Found by dogfooding on 2026-08-13, reference_examples/hboc_palb2/

What was observed

draft-panel drafts variants.csv rows from ClinVar and leaves genotype as vocab.TEMPLATE_PLACEHOLDER, correctly: ClinVar publishes alleles, not genotypes, and whether carrying a pathogenic allele once is informative is inheritance-mode interpretation the source does not state. The mechanism under it is draft.PartialRow — the row is validated by omission and matched on match_on (the identity columns) rather than the natural key, because the natural key runs through the stub, which is what makes a re-draft after the human fills the genotype report already_present instead of appending a second stub. None of that is in question.

What is missing is that the alleles the author must write the genotype from are in no file. A drafted row is rsID-only — identity whole or not at all — so rs118203998 arrives with empty ref/alts, and the pair is stated once, in the warning stream:

warning:   genotype for rs118203998: ClinVar publishes G>T — an allele pair from {G, T}

The author's next action is an edit to a file that does not contain the information. At the 16 rows PALB2 yields at ClinVar's 3-star floor this is a transcription exercise; at the 761 the same command drafts for PALB2 at the 2-star floor it is not one.

And it is emitted exactly once. The worklist is built inside if report.added: and scoped to added_records, which is itself a correct earlier repair — it used to name rows the model had refused and rows already in the file, so a "3 row(s) carry a placeholder" header was followed by twenty-seven lines. The consequence is that re-running draft-panel after the first draft adds nothing and therefore prints no worklist at all, and draft-panel has no --dry-run (draft does). The information cannot be re-requested from the command that produced it.

Candidate repairs, and why each is wrong

  • Write ref/alts into the drafted row. The one the ledger already names. A drafting provider fills identity whole or not at all, and the model forbids ref/alts without a coordinate — so this means writing the full coordinate, which discards the rsID identity the provider deliberately chose as the stabler and more legible one. alts is also REDUNDANCY_BEARING: the compiler's allele-membership check compares the author's genotype against it, and that check keeps its force because the two were authored independently. Filling it makes the compiler compare ClinVar with ClinVar.
  • A comment column on VariantRow. extra="forbid" rejects any column the model does not declare, so a "comment" is a real optional field — full cost on the most expensive table, carrying text that is dead the moment the stub is replaced. It is also a provenance claim with no machine reader: "ClinVar publishes G>T" is a statement about a snapshot release, and a re-draft from a newer one leaves it naming the old alleles. That is exactly the staleness licensing.withdraw_stale_dataset had to be built for on dataset, on a column where nothing could notice.
  • A sidecar the author reads beside the CSV. Half cost, so the cheapest legal candidate, and still wrong three ways. Its only reader is a human, which is the one thing the charter amendment says to discourage rather than leave unmentioned. Its join key is the key the stub runs through, so it either keys on the rsID — saying nothing a hint variant call does not — or on the natural key, which contains the placeholder. And an unknown file in a spec directory is tolerated but not read, hashed or listed in artifact.files (S16), so a worklist file the author must remember to delete becomes a permanent resident of every drafted module, with one more name for _check_misspelled_tables to learn.
  • Have the enricher fill it after resolution. enrich resolves the alleles, so it could. It must not, twice: ref and alts are both in hints.REDUNDANCY_BEARING (ref against verify_reference_alleles, alts against the allele-membership check), and filling a cell a Class-2 check cross-examines makes the comparison vacuous. And the dependency runs the other way — enrich refuses to load a file containing a placeholder, correctly, because forward resolution is allele-aware (hosting_verdict) and a placeholder genotype would silently skip that filter on exactly the one-to-many rsIDs that need it. Rewriting the authored cell at all is the parked enricher-co-authoring item, which nothing here should ship by accident.
  • Make genotype optional so the stub is unnecessary. Barred by Principle 8 — it is a required field, and demoting one within a major is the forbidden move. It would be wrong at 1.0 too: the zygosity decision is what the stub protects, and an optional genotype lets a module ship without it silently, which is the reassurance-manufacturing failure this format guards hardest against.

What is actually undecided

just-dna-enricher hint variant rs118203998 already returns the alleles and already refuses to apply them (refusal="redundancy_bearing"), so the information is reachable at one command per row. The candidate that survives every objection above is therefore a bulk read-only advisory over a module's stubbed rows: it changes no schema, fills no cell, and re-answers a question the drafting run answered once. That is a build rather than a decision — but it is not obviously the answer either, because it puts the worklist in a third place while the author's complaint is that it is not in the one place they are editing.

So the open question is not "which column" but where an author does this work, and this repo has no model of that. Filed here rather than built for exactly that reason.

RM85 — a recorded release, compared against the one its source publishes now

Shipped in just-dna-enricher (plus a just-dna-format vocabulary member) on 2026-08-29. The enricher check PROPOSAL_0_7 decided: currency.check_dataset_currency, run at the end of enrich() and attested as dataset_currency, with --verify-datasets/--no-verify-datasets as its switch.

Severity low-medium · Status ✅ shipped in 0.7 · Owner enricher · Motivating case a source-drafted panel two ClinVar releases later

What it does

SourceRow.dataset had recorded which release a module's rows came from since RM4, and two things read it — the tautology skip, and withdraw_stale_dataset when a module ends up mixing two. Neither answered "ClinVar has published since you drafted this". The check reads sources.csv, asks each source which release it publishes now, and reports the gap. It writes nothing: repairing a stale label is a re-draft, which is an author's decision and a different command.

It is --rederive's cheap neighbour, and ENRICHER § rederive now says so where an author reads it. Both ask has the world moved — one about the rows, one about the release label — and the label question costs one request per source, so it is what tells an author whether the expensive one is worth running.

The three things the entry did not settle, decided in the build

  • Which source can actually be asked. The entry said "the source's current release" as though every source publishes one in a form we record. They do not: dataset labels are minted by whichever pass wrote the row, and only ClinVar's has a live counterpart this tier can read in the same namespace (clinvar_<##fileDate>, through the reader clinvar_build already uses). So one probe ships, in a registry (PROBE_SOURCES, derived from default_probes rather than restated beside it), and every other source reports unsupported — an honest this tier cannot ask, never a clean bill. Widening it is adding a member.
  • Comparability is a third state, beside the tri-state the entry did name. clinvar_dataset_label has a digest form for a snapshot built from a VCF whose header stated no date. A digest against a stated date names one release space in two spellings and equality across them means nothing, so it is uncomparable (no_reference), not behind. Reporting it as behind would send an author to re-draft a module that may already be current.
  • strict refuses over behind alone. Severity follows the mode, as the decision says — but an unreachable source and an --offline run both leave every leg unchecked, and escalating those would make --offline --strict impossible forever over something no author can edit. That is the unreachable_rsids rule (warned in both modes, escalated in neither), and the gate is written over the superseded set so the two cannot be confused.

What the shape had to avoid

A check must not be able to agree with itself. Wave 2 had just found a --rederive path seeded from its own staged answers, reporting a clean bill for exactly the subjects it was re-checking. The same shape was available here — comparing dataset against the provisioned snapshot's release.json, which is very often the snapshot the module was drafted from. So the current release is read from the source over the wire, and the rows compared are the ones on disk before this run's commit; the licence rows enrich() itself writes are at the resolution layer and carry no dataset at all.

And the denominator has to be honest. subjects counts the legs asked and answered comparably; an unreachable or unaskable source is named in the record's detail rather than counted, and with no leg settled the pass records a skip instead of ran(0, 0).

Repairs refused, and still refused

  • A column stating what this module was made from and what would age it — RM71's argument one table over: it restates dataset and rots where dataset is maintained.
  • A publish-time or catalog-side signal — puts the notice where a reader is rather than where an author is, and is out of these packages' scope. Still recorded as an ask rather than built.
  • Nothing, deliberately — defensible only while a module has one author who remembers.

Also worth knowing

The probe streams and abandons rather than sending a Range header: a server that ignores one answers 200 with the whole 200 MB body, and the probe silently becomes a download. Reading the first 256 kB off a normal stream and closing it needs no promise from the server.

RM130 — a check's findings were counted and not kept, so a conflict had no name to act on

Shipped in just-dna-format + just-dna-compiler + just-dna-enricher on 2026-08-28. Two new optional derived tables, three new closed vocabularies and one new warning code — additive throughout, and no published module's identity moves, because a module that carries neither file contributes neither entry.

Severity medium · Status ✅ shipped in 0.7 (the observability half shipped 2026-08-24) · Owner enricher · Motivating case S70 (just-module-creator) in CONSUMER_SUGGESTIONS_HISTORY.md · Decided in PROPOSAL_0_7, amended the same day by RM134

What shipped

clin_sig_concordance.csv, keyed (variant_key, genotype), and its paired clin_sig_authority_calls.csv, keyed (variant_key, genotype, authority). The first carries the agreement state — authority_concordance, authored_position, opposed, and the module's own call — and the second carries what each authority actually said, with its raw token and its confidence in its own units. Both are compiled to parquets, fact-hashed, summarized in manifest.clin_sig_concordance, and reported at validate and compile by clin_sig_concordance_contested.

The enricher half is concordance.py (the classifier, the row builder and the writer) plus clinical.clin_sig_concordance, which returns the two tables or None. ClinSigConflict.clinvar became authority_clin_sig beside a new authority, with the old name kept as a read-only alias.

Why the shape changed before it was built, and the reason is the durable part

The entry asked for a table carrying the authored value, the source's value, and whether the two are opposed or merely different. That shape names its authority in a field — ClinSigConflict really did carry clinvar: str — and RM134 arrived in the same release with a second authority. Shipping the first shape would have cost a key change or a retype one item later, and Principle 3 reserves both for a major. Two items landing in one release is what caught it; either alone would not have.

So the parent row carries an agreement state instead of a pair of values, and which authority spoke became data in the detail table. That is what makes the key stable at any N.

The stress test, and why one field could not have held it

A single vocabulary was drafted with seven outcomes and failed at five authorities: its members named the authority inside themselves (clinvar_only, pubmind_only), so a third source needed a third member and five needed every subset. The root cause was one field carrying two axes — do the authorities agree with each other and where does the module's own call sit — with concordant defined as "both agree and the authored row agrees with them" and authored_dissents as a sibling member. That is the Principle 5 anti-pattern and the combinatorial growth was its symptom. Split, both vocabularies are five members at two authorities and five at five.

Nothing resolves a split, and that is a decision rather than an omission

At five authorities with a declared order E>B>D>C>A, suppose E and A agree and B, C and D agree against them. Lexicographic resolution says E; majority says B/C/D; choosing between those rules is a judgement about how authority rank trades against agreement count, and it needs a weighting model. This workspace has refused to invent one three times — RM126's should_rebuild (the same fact costs consumers differently, so the decision is theirs and only the fact is ours), @clinsig-never-escalates, and RM16's PRS weights. So authored_position is a relation to the set: computable with no weights, true at any topology, and the E+A case reads discordant + matches_some under either rule.

The same refusal one level down keeps confidence unnormalized. A gold-star count and a literature miner's evidence-depth count are different instruments, and folding them into one number is three axes in one field — so the detail row carries the published value with confidence_unit beside it, and the model refuses a magnitude with no instrument named (@weight-has-no-unit, enforced rather than documented).

The lifetime, and the succession it promotes

A conflict is a question and an overrides.csv row is the answer. The record joined the overlay's covered set, taking it from seven to eight, and it is in for a different reason from the other seven: not because it carries hand-curation a re-derivation would destroy — it carries none and is rewritten whole on every run — but because answering a contested subject is what an overlay row is. RM124's vindication signal then works for free: when the archive catches up, the author's suppress stops changing anything.

The paired detail table is out, by name, in the same equality test. The author answers the question; they do not get to rewrite what an archive published, and an overlay over the detail table would let a module ship ClinVar's name above a classification ClinVar never made.

The table's documentation and the warning both name overrides.csv and never provenance.json's outranks. The two are the same idea one table apart, 0.7 settled the overlap as a dated succession in the overlay's favour, and steering a new author onto the side that survives 1.0 cost a sentence.

Severity, and the one thing it must never become

Warning-tier in both modes, never escalating under strict (@clinsig-never-escalates). A disagreement with an archive is a fact about the field, not a defect in the module: half the time the archive is the stale side, and failing a build on one would have this format arbitrate a clinical dispute.

The finding is actionable rather than carried, which inverts its neighbour verification_findings_recorded and does so deliberately. Nothing an author writes moves a number sitting in verification.json; a contested row is answered by writing an overlay row, and the count is taken over the post-overlay table, so writing one clears the finding. overlay_rows_suppressed reports the removal, so an answered conflict is visible rather than silent.

Two things found while building it

opposed is a tautology at one authority, and the record is what makes it stop being one. The two-way check only reports where both sides are opinionated and their camps differ, and pathogenic/benign are the only two opinionated camps — so every conflict it reports is opposed by construction, and _clin_sig_detail's differing-but-not-opposed group has no producer today. Filed rather than mended: the formatter lives in enrich.py, the group becomes reachable as soon as two authorities can disagree while neither contradicts the module, and that is exactly what the record is shaped for.

Several vocabulary members are reachable by the classifier and not by today's producer — absent needs a subject the module makes no clinical claim about, and none needs every archive asked and empty; neither is a contested subject, so neither is written. They are kept on the VALID_RSID_STATUS.withdrawn precedent: a member is permanent within a major, so reserving one now is free and adding one later is not. The classifier tests walk every topology at three and five authorities and assert an equality against both vocabularies, which is where the members are exercised.

Repairs rejected

  • Folding the conflict into the overlay as an evidence column. A conflict nobody has answered has no overlay row to live on, so unanswered conflicts — the entire point — would have nowhere to be.
  • Escalation under strict, or auto-correction. Out of scope on the reporter's own scoping and ours: a conflict is a question, and half the time the archive is the stale side.
  • A majority or consensus field. The E+A case is the argument; precomputing it is should_rebuild wearing a different name, and it would publish a judgement as a fact.
  • A second significance map. The check's whole output is a comparison of two normalizations, so a drift between two maps would report a disagreement with ourselves as a disagreement between two archives. CLIN_SIG_CAMP moved out of clinical.py rather than being copied, for the same reason one level up.
  • Writing a row for every compared subject. A record of every agreement is a copy of the module's own clin_sig column with a second opinion attached, and the number of subjects compared is already published as the check's denominator.

RM131 — the warnings channel says what each finding is, and whether an author can clear it

Shipped in just-dna-format + just-dna-compiler on 2026-08-28, with the deprecated DuckDB resolver in just-dna-enricher brought along because its warnings land in the same published channel. Both halves the proposal sequenced, in one release, because the audit is the cost and doing it twice is what the sequencing existed to avoid.

Severity medium · Status ✅ shipped in 0.7 · Owner compiler · Motivating case S68 (just-module-creator) in CONSUMER_SUGGESTIONS_HISTORY.md

What shipped

compilation.carried and compilation.warnings_summary beside compilation.warnings, which is unchanged down to the byte — the same sentences in the same order, so nothing that greps a phrase broke. carried is the subset no edit to the spec directory can clear; a consumer subtracts it to get the actionable set. warnings_summary is {code: count} over vocab.VALID_WARNING_CODES, with the values summing to len(warnings) so a reader can tell the digest is complete. The same three fields are on ValidationResult, CompilationResult and ClosureResult, on every path including a failed compile.

Sixty-eight codes, nine of them carried. findings.CodedWarning is a str subclass, so the transport stayed list[str] and every de-duplication, extend and phrase-grep went untouched. sweep.compare_module reports carried_added beside actionable_added, which is the discriminator RM126's own comment said would land here.

The three things worth not re-deriving

The container was free and the vocabulary was the release, which was the whole of the original deferral and is answered rather than dismissed: the set was derived across every emission site in three tiers, and the derivation rule is one code, one remediation — two sentences cleared by the same edit share a member and the sentence says which cell, two cleared differently do not. So the weight-sign pair is one code across state and direction (two axes under P5, one edit) and the five orphan fact tables are one code, while a VCF pointer collision and an unselected element are two.

The emission surface was larger than the entry's "~29 append sites and 16 returning helpers", and the parts it missed are the parts that would have shipped unclassified: the findings/messages collectors a survey of .append cannot see, two .extend sites reaching into the schema tier's measurement_shape_warnings/deprecation_warnings, validate_bins, overrides.apply_overrides, and the deprecated resolver in the enricher, whose warnings reach manifest.compilation.warnings like everything else. Re-derive such a count; never trust the one in an entry.

A carried list beside warnings was the right shape and a field on each finding was not, but the str-subclass transport that makes it cheap leaks the code at exactly two places, and both are load-bearing: a pydantic field flattens the subclass (so compile_module/close_module seed from an internal _validate_spec that returns the classified list beside the result), and any reformat returns plain prose (so three prefixing sites go through findings.restate, which refuses an uncoded input rather than inventing a code). Both are pinned by tests, and the second half of the guard is a run over the whole reference corpus — a static walk proves every site names a code, and only a run proves every message that arrives still carries one.

What it did not do

No cap, no truncation, no verbosity flag, per the reporter and us: all three hide findings rather than organising them, and the author with the most warnings is the one who most needs the hidden ones. No metainfo artifact — the channel already ships and artifact_digest is a Merkle root over the parquet FileEntry list, so manifest.json sits outside it and neither new field moved a hash on any published module. Codes were not derived from the pinned phrase catalogue (partial by construction, and a digest that silently omits findings is worse than none because the reader believes it) nor from the emission site (a refactor then renames a published key — P3's rename arriving by the back door).

axes["warnings"] still fires on any movement of the set, deliberately: narrowing it would make a published axis mean something other than what every record already written claims about it, and the axis drives no rebuild. A pre-0.7 manifest reports every addition as actionable, which is the safe direction — calling an unrecorded finding carried would tell a reader that something fixable is not.

The suppression record it carried in (RM124 × RM131)

A row removed by a suppress was invisible in the build product: absent, with no trace of why, and a consumer holding the compiled bytes has no overrides.csv to read. It now reports one line per reason with a count — which is what reason being a required column buys — and the count is over the overlay's rows, never over the rows removed. That is not tidiness: after reverse_module the derived table is already post-overlay, so an effect-based count would say a number on lap 1 and vanish on lap 2, making a module disagree with its own round trip on a published field. Proved against the real compile → reverse → compile path. Classified actionable rather than carried, because the author owns the overlay and deleting the row clears it.

The three candidate derivations are argued at length in PROPOSAL_0_7 § RM131, which is where the decision was taken; the entry this replaces lived in ROADMAP.md and not in ROADMAP_0_7, so there is no second copy to keep in step.

RM124 — an author's correction to a derived table now has somewhere to live

Shipped in just-dna-format + just-dna-compiler + just-dna-enricher on 2026-08-28, as overrides.csv — a new optional authored table, additive under Principles 3 and 8, so no published module's content_signature or artifact.digest moves. It is the keystone of the 0.7 round: RM83 closes into it, RM130 was blocked on one of its questions, and RM128's central ask thins because of it.

What it discharges. The 2026-08-12 cost amendment names the class in its own words — a derived table that is both machine-written and human-overridable can be edited into a state that is not merely stale but a false claim, which wants a mechanism rather than a convention. RM45 discharged that for exactly one table by making verification.json unwritable by hand. Nothing discharged it for the seven where overriding is the intended feature, and their merge-not-clobber rule meant that re-deriving one required deleting it, which discarded every hand-curated row in it.

The covered set is seven, and the number is a correction. The proposal says "the six covered derived tables" and never enumerates them; the roadmap entry it inherits the number from does not either. The maintainer settled it on 2026-08-28 as every merge-not-clobber derived sidecar — resolution.csv, frequencies.csv, gene_metrics.csv, gene_validity.csv, clinical_assertions.csv, literature.csv, gwas_effects.csv — with sources.csv / licensing.csv outside it, because it has its own merge path and is the one derived table the schema tells a human to write. overrides.OVERRIDABLE_TABLES is the registry and a test asserts the equality against the compiler's own table tuples rather than a floor.

Three decisions worth not re-deriving, all of them recorded in SCHEMAS § the authored overlay:

  • One member column, whose meaning the named table fixes, rather than a per-table key grammar — which is a rule every consumer would re-derive, differently. An empty member on a grouped table is group-scoped for update and refused for suppress (not recoverable by reading the result) and for insert (the row it would create carries no member value, so nothing could match it again).
  • No previous_value column. reverse_module emits the post-overlay derived table plus the overlay, so the overlay applies twice; all three operations are idempotent set operations, so the second lap is a fixed point, checked by test rather than assumed. The alternative would put a derived cell inside an authored table, which rots the moment the source moves.
  • No operation reports its own no-op, and that is forced rather than tidy: after a reverse, all three no-ops are true of a healthy module, so reporting any of them would make a module and its own round trip disagree on manifest.compilation.warnings. The price is stated rather than hidden — a suppress with a typo'd subject does nothing, forever, and cannot warn.

Merge-not-clobber's behaviour is unchanged and its cost is gone. A re-run still gap-fills rather than re-asking every subject — re-asking was explicitly rejected, since it would put the full resolution time on every pass. What changed is that a recorded row now carries no authored content, so leaving it alone risks nothing and a full re-derivation (rm plus a re-run) is free. The seven writers' docstrings say so where a reader outside this repo actually meets them, in the same commit as the behaviour.

The outranks overlap is a dated succession rather than a merge. Both mechanisms stand in 0.7, the duplication is stated in SCHEMAS, and the unification is RM135 on the 1.0 tracker. 0.7 emits no deprecation warning, which is P3 rather than caution: an author warned off outranks has nowhere to go until the overlay reaches authored tables.

Coordination. just-dna-registry rebuilds a spec directory from RECOGNIZED_SPEC_FILES, a hand-kept mirror of our table constants, and a name missing there is a file dropped on re-publish — which is how licensing.csv was lost before their 0.16.2. overrides.csv needs one entry added there; it is recorded in INTEGRATION_0_6.md rather than left to be discovered.

RM128 — enrich() persisted nothing until its tail, so a run killed at minute 29 had written nothing

Shipped in just-dna-enricher on 2026-08-28, as just_dna_enricher.transaction plus three keyword arguments on enrich() and two flags on the command. Additive: no schema, no manifest field, no vocabulary. Motivating case S66 (just-module-creator).

The truncation half was already closed on 2026-08-24 — nine sidecar writers go through layout.atomic_writer, so a killed process leaves the previous table rather than a short one. What this entry records is the three asks beside it, each of which was a decision rather than a missing line.

The central ask dissolved rather than being argued down. It was filed as incremental or checkpointed persistence, and it turned on a question nobody had written down: is a strict refusal allowed to leave rows behind? The choice looked like keep the promise or recover the thirty minutes. It is not a choice. The run becomes a transaction, which keeps the promise absolutely and recovers the work as well.

  • Durable staging beside the target, plus an atomic commit at the gate. Each live link's answer is staged to .<name>.staging/answers.csv beside resolution.csv as it arrives; the table is still written once, at the bottom, by a writer that renames into place. layout.atomic_writer already staged exactly there, so this extends a shipped primitive from one file to a whole run rather than inventing one.
  • Same-directory staging is the correctness condition, not a convenience. A rename within one filesystem is atomic; shutil.move across a partition degrades to copy-then-delete and is not. Staging beside the target makes a cross-device move structurally impossible rather than merely avoided, which is why the test asserts the sibling relationship structurally.
  • What is staged is the answer, never the row. Everything downstream of an answer recomputes — the hosting filter, the pseudoautosomal selection, locus_index, the minted ids — so a flag that changed between the kill and the resume changes the table exactly as it would have, and the journal cannot carry a stale derivation. It is seeded between the caches and the live links, so a snapshot provisioned in between still wins the variant it would have won on a first run.
  • Only positive answers are staged. A failed request is unchecked rather than absent (@unreachable-not-absent), and freezing one into the journal would make a transient outage permanent on every future run. And a staged answer is honoured only if the link that produced it would run this time: the seeding reads the same two booleans that gate the live blocks, so a --no-gnomad or --offline resume drops that link's answers rather than stamping a row a first run with those flags could never have written — alts is a fact column, so the alternative would move the compiled digest.
  • The gate commits, so a refused strict run changes nothing became a written promise instead of an accident of statement order — the item's actual question, answered in the direction that breaks nothing. The test asserts it on the bytes of a pre-existing table, not on a return value.
  • --keep-staging keeps the staged answers after a successful commit, for debugging; the default removes them, and both values are exercised.
  • Not mode-conditional, as the entry refused in advance: write=True meaning "at the end" under strict and "as we go" under best_effort is a flag that does not mean the same thing in every function that takes one. Under a transaction it does, because committing is the only write, and write=False stages nothing and takes no lock — with nothing written there is no window to exclude.

RM124 thins what the promise has to protect, and the two were reached independently. What a staged, uncommitted table can contain is now provably machine-derived and never an authored value, because the author's corrections live in the overlay.

The lock, and why it is flock

The transaction does not close the concurrency window: two runs can each stage and each commit, last writer winning over a merge with neither knowing. The reported incident is the sharp form — a client-side kill did not stop the worker, a zombie run reached the write and overwrote a restored 330-row table with 162 rows, and the module then validated, closed and compiled green. Nothing downstream could see it, because the three branches that deliberately write no row for an unanswerable subject make a shorter table indistinguishable from a module whose author resolved less. Those branches are correct and were not in scope.

flock on the spec directory's own descriptor, non-blocking, no lockfile. A lockfile left by exactly the kill this item is about would block every subsequent run — a worse unattended failure than the one it prevents — and the staleness rule that would fix it is a clock, which this repo has refused before (guard the plan, not the clock). flock dies with the process, so there is nothing to expire. Non-blocking because a run silently waiting half an hour behind a zombie is its own unattended failure, and the refusal is accurate by construction: the lock is only ever held by a live process.

The degradation is documented rather than silent, which the design explicitly owed. No fcntl on a non-POSIX platform, or a filesystem answering ENOLCK/EOPNOTSUPP, logs that the run is not excluded from a concurrent one and carries on. Both branches are reached by tests — an unreached refusal branch is not an API, which the wave-1 audit had just demonstrated. flock is untested here on the network filesystems a consumer may use, and ENRICHER says so where a consumer meets it.

The progress unit, argued rather than guessed

progress: Callable[[int, int], None] | None = None, reporting (done, total) over subjects. The entry filed this rather than shipping it because the resolver chain is batched inside resolver.py rather than being a per-subject loop, so the unit reported is a design choice — and a leaf shipped against a guess is one Principle 3 keeps working forever.

  • The incident is an idle timeout. Both reported runs died at 1800 s with essentially every variant resolved, so what the caller needs first is a keepalive with monotonic progress — which rules out phases, since a 29-minute phase emits nothing and the timeout fires anyway.
  • total must be known up front for the number to mean anything to a caller rendering it. The subject count is; the link count is not, since it depends on what resolution finds.
  • Subjects are the only unit the author's mental model already has. Links are an implementation detail of the batched resolver, and publishing one would make a refactor of resolver.py a contract change — the rename P3 forbids arriving through the back door.

No protocol was added, because none was asked for: two integers, no object, no event vocabulary to keep working forever. Monotonicity is structural — done is the size of a set that only grows — and the assembly loop touches every subject, so the last report is always (total, total).

enrich --rederive — RM83's residue, and it composes rather than adds

A full re-derivation that keeps a baseline reports what moved, which is MODULE_LIFECYCLE § 5.1's canary performed. It composes with the transaction: the recorded table is still in memory and the fresh one has not been committed, so both sides exist at the commit boundary and the comparison is free. The comparison is over RESOLUTION_FACT_FIELDS, read off the registry rather than restated, because the provenance columns move on every run by design.

  • None is not []. None says nobody re-derived; [] says every recorded subject was re-asked and every one still answers the same. Only a real difference prints — a comparison whose empty result is the normal case must not announce a zero as though it were evidence.
  • A recorded subject the run could not ask about keeps its recorded rows, and the carry-forward warns naming them. Without it, an offline --rederive would replace a full table with an empty one: the reported incident wearing a new flag, and the sharpest test in the unit. Answered-and-absent is an answer and does replace (it writes a not_found row); could-not-ask is not.
  • A re-derivation resumes only another re-derivation. After a gap-filling run commits, its staged answers are exactly what produced the recorded table, so seeding them would compare that table against its own provenance and report a clean bill for precisely the subjects being re-checked — the canary silenced by a file left behind for debugging. The journal records which run wrote each row; the reverse direction is allowed, because an answer a re-derivation obtained is still an answer.
  • The honest limit is stated rather than hidden. rm resolution.csv plus a re-run re-derives just as correctly and reports nothing, because it destroys the old values before the fresh ones arrive and nothing holds both sides.

Repairs rejected, kept because each looks obvious from the headline: a --refresh command (RM83's three open questions were all answered elsewhere, leaving a mode on the command that already does the derivation); a diffs file or table, or a proposed table beside the current one (version control with no consumer, beside the version control the author already has); a pass that applies the newer value (rewriting an authored or curator-set cell destroys the evidence of the upstream change — still the rule, and the overlay does not soften it); and re-asking every subject on every run (dropping merge-not-clobber did not mean that, and reading it that way would put the full resolution time on every pass to buy drift detection nobody asked to run continuously).

Charter check

P2 — enricher-only; the compile path imports none of it. P3 — three keyword arguments with defaults, a staging directory and a new module are additive; no schema, no manifest field, no vocabulary. P7 — a committed run produces the table an uninterrupted run produces, which the resume path proves by test.

RM83 — a derived sidecar can only be refreshed by deleting it, which discards the overrides it exists to hold

Closed, not shipped, on 2026-08-28, in the commit that landed RM124 and not before — a closure recorded against an unlanded dependency is the kind of bookkeeping that makes a ledger untrustworthy. Dissolved rather than argued down: the premise stopped holding.

The entry named a missing operation, a --refresh that re-asks the source about recorded rows and reports the difference, and it had two halves. The refresh half stops existing — its problem was that re-deriving a sidecar means deleting it and losing the curator's rows, and once the derived files are pure build products with the corrections in the overlay there is nothing inside a sidecar to preserve, so rm costs nothing and needs no command wrapped around it to be safe. The drift half stops being unperformable — merge-not-clobber meant a re-run never re-asked about a recorded row, so a source that silently revised an answer moved no fetched_at, no fact signature and no digest, making MODULE_LIFECYCLE § 5.1's canary an instrument that could not fire, because detecting drift was the delete-and-re-derive that discarded the overrides. With the discard harmless, a full re-derivation is an ordinary operation and the canary fires from it.

The blocking question is answered rather than deferred. The entry named it: on most sidecars nothing records that a row was overridden, so "re-derive the machine rows and keep the overrides" was not implementable, because the tier could not tell a curator's edit from what the source said last time. Under the overlay the tier never has to — the edit is recorded by construction and the derived row carries no authored content at all.

Nothing named in the entry is built. No --refresh command, no proposed table beside the current one, no diffs file. What remains is a residue and it is a flag rather than a command: enrich --rederive, which stages a fresh table beside the current one and commits by rename (composing with RM128's transaction), so both files exist at the commit boundary and the report of what moved is free. The honest limit is stated with it — rm followed by a re-run destroys the old values before the fresh ones arrive, so that path re-derives silently and correctly and no report is possible.

Repairs rejected, kept because each looks obvious from the headline: a diffs file or table tracking what moved between passes (version control with no consumer, beside the version control the author already has, over a file now regenerable from source plus overlay); a pass that applies the newer value (rewriting a curator-set cell destroys the evidence of the upstream change — still the rule, and the overlay does not soften it: an overlay row is the author's answer to a difference, never the tier's); and re-asking every subject on every run (dropping merge-not-clobber does not mean this, and reading it that way would put the full resolution time on every pass to buy drift detection nobody asked to run continuously).

RM132 — pharm_variants.csv made a clinical claim per row and could only cite per variant

Decided in PROPOSAL_0_7 on 2026-08-28 — SHIPPED in 0.7. PharmVariantRow.pmid plus both literature cross-check sites in the same release; provenance_quote did not follow, stated rather than implied.

Severity medium · Status ✅ shipped in 0.7 · Owner format (schema) + compiler + enricher · Motivating case S73 (just-module-creator) in CONSUMER_SUGGESTIONS_HISTORY.md

What was observed

A ClinPGx-drafted module carried 1,482 drug-response rows and had nowhere to ground any of them: sixteen model fields, thirteen authored, none a PMID or DOI. The reporter asked which of three provenance models was intended, worked out that none of them held, and declined to build on any.

The tree had already answered it one release earlier. RM47 decided this shape for a structurally identical table, and the rule underneath generalizes: a row cites when its claim is finer-grained than studies.csv's key. studies.csv keys on (variant_key, pmid), so a study row attaches to a variant; pharm_variants.csv keys on (variant_key, drug, genotype, phenotype_category, annotation_id), so one study row would attach the paper to every drug, genotype and phenotype category recorded for that variant at once. evidence_level is not the provenance handle — it points at somebody else's grading of the evidence rather than at the evidence — and the licence row's source/dataset state redistribution terms rather than grounding a claim.

Why a full-cost authored column was taken rather than deferred

This is the item the round's sort rule turns on, so the argument is kept rather than assumed.

What P9 prices is not the byte. An authored column is full cost because a human must learn it and P3 keeps it working forever, so the risk being priced is getting the shape wrong — and that risk was spent a release ago. The column is a copy of two shipped fields under one grammar, so an author who has met either learns nothing new. Demand fixes an unfixed shape; there was none left here for demand to fix.

It is closer to a half-defect than to a new capability. The table already made a clinical claim per genotype and structurally could not ground one. That is a hole in an existing concern rather than a new concern added to a table, which is the distinction the one concern per table gate turns on.

What was built

PharmVariantRow.pmid, optional and free-form, validated by spec.validate_pmid_cell — the one grammar every citation pointer in the schema routes through, so the PMCID diagnosis and the [PMID: N] spelling come with it and cannot drift. No compiler change was needed for the column itself: the parquet materializer and the reverse writer both derive their column lists from the model.

Both cross-check sites learned the site in the same release, which is the half that made this a piece of work rather than a column, and is RM47's recorded lesson in its own words — shipping the column without both would be evidence the format never checks, which is worse than the gap. _cross_check_literature (with split_cited_literature and _check_quote_counter_is_current beneath it) and the enricher's enrich_literature both read it. Since RM79 the orphan finding has teeth: blind to the new site, the compiler would not merely report a pharm-grounded citation as stale, it would discard the literature row the claim's evidence lives in.

The roster is derived, which is the part that generalizes. Rather than a third hand-kept list, _CITING_TABLE_KINDS is every _TABLE_KINDS model declaring a pmid, and the new public load_citing_rows / table_citations walk it. The enricher reads through that pair — the RM40/RM41 requirement, met structurally: a test walks the enricher's own source with ast and asserts no citing CSV name appears in a string constant there, so the next kind to declare the column is read by both tiers with no edit to either. load_binning_rows / binning_citations stay and stay narrow; a caller asking for the binning kinds is asking about thresholds, not about the citations a module makes.

One warning text moved with it — literature_row_uncited now reads "no study, bin or pharm row in this module cites". The code is the stable handle and did not change; the phrase is pinned by four tests, which is what makes each rewording a deliberate act.

The open question, answered

provenance_quote does not follow, and the release says so rather than leaving it implied. The binning side drew the same line deliberately: the row cites, and studies.csv/literature.csv describe. That is what stops StudyRow's whole provenance column set — population, p_value_num, effect_size, provenance_quote, curator — migrating onto a citing row one column at a time. A 1,482-row body of clinical claims is exactly where somebody asks next, which is the reason to state the line rather than the reason to cross it. The consequence is carried in the code too: a pharm row cites and cannot quote, so it contributes a denominator of zero to the quote-counter check rather than being skipped, or a literature row reachable only from a pharm row would read as cited by nothing.

Repairs refused

  • Widening studies.csv's key. The repair that looks obvious and the one RM47 already refused: it would make a study row's subject depend on which table read it.
  • Treating evidence_level as the provenance handle. It grades evidence rather than pointing at it, and the two now sit side by side in the model so the distinction stays visible (P5).
  • A second table roster in the enricher. The RM40/RM41 shape, and a list that goes stale the next time a model declares the column.
  • A grounding warning for an uncited pharm row. _check_binning_grounding exists for the interpretive-threshold case — where a boundary is a clinical judgement with nothing behind it — and a drug-response table is not that case. Adding one would have fired on every ClinPGx draft.

Charter check

P3 — a new optional column, additive; no published module is invalidated. P5 — citation and grading are separate axes on separate columns. P7 — the round trip is asserted on the pharm_variants.parquet bytes as well as on content_signature and artifact.digest. P8 — optional with respect to every published module, proved by running it: a spec with no pmid header hashes equal to the same spec carrying the header with every cell empty. P9 — full cost, taken with the argument above rather than by weighing file count.

RM70 — requires_callable is VariantRow-only, so no PGx table can state CPIC's core assumption

Decided in PROPOSAL_0_7 on 2026-08-28 — BUILDS in 0.7. requires_callable on HaplotypeRow and PharmVariantRow, not on DiplotypeRow; callable_from does not travel with them.

Severity medium · Status SHIPPED in 0.7 — optional requires_callable on HaplotypeRow and PharmVariantRow, not on DiplotypeRow, and callable_from did not travel · Owner format (schema) · Found by dogfooding on 2026-08-13, reference_examples/cyp2c9_warfarin_grch37/

What was observed

CPIC's star-allele system assumes that a position not called is reference — that is literally requires_callable=false — and haplotypes.csv, pharm_variants.csv and diplotypes.csv carry no such column. requires_callable and its companion callable_from are on VariantRow alone. So a star-allele module cannot record whether its call needed the defining positions to be callable, which is the single assumption a consumer most needs to know before trusting a *1/*1 result.

The corpus shows both sides of it. D6 confirmed RM57's inversion warning fires correctly on the row type it exists for: a requires_callable=true row with quality_from=QUAL, min_quality=30 warns, cites VCF §1.6.1.6, and names GQ and MIN_DP as the fix. D2 could not exercise it at all, because a PGx module has no variants.csv — the check and the column are unreachable from the module kind whose upstream states the assumption in prose.

What was built

The two columns as decided, and nothing else. The parquet schema and the reverse writer both derive their column lists from the model, so no compiler change was needed — _polars_type maps bool | None to a nullable pl.Boolean and _scalar_cell already rendered None and False as "" and "false". That was proven rather than assumed: a temporary mutation collapsing an authored False into a blank cell was run against the round-trip test first, and it failed on both tables.

reference_examples/cyp2c9_warfarin_grch37, the module the gap was found against, now populates the column and exercises all three states. haplotypes.csv records CPIC's assumption verbatim (false on both defining SNPs). pharm_variants.csv is keyed on genotype and so splits: the reference-homozygote rows carry true, because a variant-only callset emits no record for them and absence is not the call; the rows naming an alternate allele carry false; and the twelve rows whose reference allele the module's own resolution.csv never named are left blank rather than guessed. That answers the PGx half of the consumer ask for requires_callable "populated somewhere real, to try the round trip against". The module was re-closed, so its attestation binds the edited bytes.

No cross-table equality check, and the reason is not cost. haplotypes.csv and pharm_variants.csv can name one locus and legitimately disagree: a haplotype row's claim is about assigning the reference haplotype there, and a pharm row's is about matching that row's genotype. The fixture holds exactly this shape — a haplotype default-to-reference (false) beside a reference-homozygote genotype needing a proof (true) — so a checker asserting the two agree would refuse a correct module. Both field descriptions say what each claim is about, and a test compiles the disagreeing pair clean so the check is not added later.

Cost, priced honestly

requires_callable is an authored column, which is full cost under the 0.6 charter amendment — the most expensive kind of addition this format makes, on the layer the rare human writes. That is the reason the item is filed rather than done, and it is also why the scoping question below is not a detail: covering three tables and covering the two that name a position are different prices for the same capability, and the difference is a column on the table a human writes.

Candidate repairs, and why each is wrong

  • Copy the column onto all three PGx tables. Full cost, three times, and wrong on the third. haplotypes.csv and pharm_variants.csv name loci — they are two of RM43's three positional tables — so a callability claim on either is about a position the row states, which is exactly what the column means on VariantRow. diplotypes.csv names a star-allele pair, not a locus, so the same column there could only mean "the variants defining these two haplotypes were callable" — a fact about haplotypes.csv's rows, restated one table over where it drifts the moment a definition is edited. One concept, one home (P5).
  • Declare it once in module_spec.yaml. The verdict is per locus, and this repo has twice paid for assuming otherwise: RM36 rejected per-CSV build declaration because two files could disagree about one fact, and RM32 rejected a gene-scoped PAR verdict because XG and SPRY3 straddle a boundary. CPIC's own assumption is not uniform either — a gene whose common alleles are single SNPs and one defined partly by a structural event do not have the same callability requirement, and CYP2D6 has both inside one gene.
  • Derive it from callable_from. There is no callable_from on the PGx tables either, so this starts by adding the more expensive of the two columns. It is also an axis overload: callable_from says where the proof lives, requires_callable says a proof is required, and a row may legitimately require one and not know where the evidence is. Deriving requiredness from the presence of a pointer collapses two questions into one column.
  • A stamped, compiler-managed parquet column. Nearly free under the amendment, and it cannot work: this is a curator's claim about what the annotation assumes, so there is nothing for the compiler to compute. A stamped column carries only what the compiler derives.
  • Author the defining positions a second time in variants.csv. Two tables then name one locus, and variants.csv alone carries alts as a resolution fact, so the shadow rows move artifact.digest while asserting nothing new — and it re-opens a star allele can be used without being defined from the other end, with two definitions instead of none.

Is it gated on the same thing as RM65/RM66?

No, and the difference is the useful part of this entry. RM65 and RM66 wait on a real repeat-caller or CNV VCF because the open question there is what a caller emits — the shape of the data decides the schema. This question is about what a curator asserts, and the assertion already exists in prose: CPIC states it. A PGx caller VCF would say nothing about which of three tables should carry a curator's claim. The adjacency the ledger records is that both ask whether a non-variants.csv table should carry something variants.csv has, not that they share a blocker.

What unblocked it: the entry's own closing reading, put to the maintainer and taken as written — two optional columns, on HaplotypeRow and PharmVariantRow, the PGx tables that name a position, and not on DiplotypeRow. The second question the entry left open, whether callable_from travels with them, was answered the cheap way: it does not, and it is added when a module needs to say where the proof lives. What the entry got wrong is the other half of its unblocker — it also asked for a real module whose author wants to state it, and the module was already in the corpus. The one this was found against is the one that now states it.

The 2026-08-24 consumer round (S63–S74)

Twelve items from two reporters, triaged in one pass. The per-item record is in CONSUMER_SUGGESTIONS_HISTORY.md; what is here is the reasoning behind each RMn the round produced.

RM129 — producer described the document and was read as describing the checks

Shipped in just-dna-format + just-dna-enricher on 2026-08-24, a minor. verification.json carried producer at the document level only, and record_verification refills it from producer_label() on every write — so a merge that correctly kept an older run's record restamped that record's attribution to the writing release. Reported against a module carrying a 0.6.4 clinical_significance record that came back attributed to 0.6.6.

The reporter's argument is the item and it is an argument from the other fields. Every field describing one piece of work was already on the record — source (which authority answered), release (which snapshot), checked_at (when) — and producer, naming who ran it, was the only one on the document. Once the list is written out that way the asymmetry reads as an oversight rather than a design, and the fix is where the field goes rather than what it says.

produced_at stays on the document and is correct there, which is the discriminator worth keeping: it genuinely describes the file's last write, and so does producer under its new reading. The two are now a pair meaning what last wrote this file, and the per-record field means who put this check. Verification.producer's own description had said "Tool and version that put the checks" — the false claim, sitting in the printed contract where describe/reference render it verbatim — and correcting it was part of the fix, not a follow-up (@field-description-is-a-claim).

Three obligations a new field on a fact-hashed record owes, discharged rather than assumed. producer is outside VERIFICATION_FACT_FIELDS on exactly the reasoning that excluded checked_at (who ran a check is a fact about the run, not about the module), so no published verification.signature moved — asserted by a test rather than reasoned about. It is str | None defaulting to None, so a record written before the field existed reads as not recorded; defaulting it to the reading version would manufacture the false attribution the item is about, which is the tri-state rule applied to a provenance field. And merge_records carries whole records, so the value travels with no change to the merge — pinned by a test that hand-builds a 0.6.4 record, merges over it, and asserts the old attribution survives.

What was not changed: the merge. The reporter went out of their way to record that merge_records did the right thing — RM72's rule that a fresh skip does not displace an earlier answer held, and nothing was lost. That mattered to the triage: a report framed as "the merge is broken" would have aimed the repair at the one part that was correct.

The 2026-08-21 output-contract round — what a patch may change about a compiled artifact

One report from a new consumer, just-dna-registry (S62), and the two items it produced are open in ROADMAP.md. What belongs here is a framing that was filed and then withdrawn the same day, kept because the withdrawn version is the more tempting one and will be re-proposed by anyone who reads only the measurement.

RM127 was first filed as the release-class table and the release practice disagree. The argument ran: our table sizes a new optional column as a minor; StudyRow.curator shipped in 0.6.5, a patch, and the cut's own entry names it ("Additive only: one new authored column"); so the rule we state and the rule we practise disagree and one of them must give. Three candidates were recorded — the table is right and 0.6.5 was mis-sized; the practice is right and both documents should say a change that moves no authored identity may take a patch; or split the axis so authored surface sizes the release and derived surface does not.

It was withdrawn because it indicts the wrong release. curator is additive, no already-published module can carry it, and no stored value became wrong — the only consequence is that a recompile writes different bytes, which P4 already declines to guarantee across compiler versions. Sizing it as a patch is defensible; the table calling it a minor is the table being strict, not the cut being wrong. Chasing that disagreement would have produced a rule change that fixed nothing the consumer reported.

The defect is RM121, and it is a change class the taxonomy does not have — an existing published field whose derivation was corrected, so the same spec yields a different value. Neither additive nor a removal/retype. And because a corrected derivation is a bug fix, deferring it to a minor means knowingly serving a wrong value meanwhile, so no release-class scheme can carry it: the version number answers is the code contract compatible, never are your stored outputs stale. The two axes have to be separated rather than reconciled, which dissolves all three original candidates instead of choosing among them. The rewritten entry is RM127.

The lesson worth keeping is the tautology. The safety argument for RM121 was content_signature is unchanged, measured — true, and incapable of being false, because stats sits outside content_signature by design. A check that cannot fail was read as a pass (@tautology-zero), one level up from where that rule is usually applied. The same property has a second edge: a field outside identity is a field no digest, no signature and no revalidate can see move, so the cheapest changes to make are exactly the ones with no detection channel. Measured across 0.6.1→0.6.6: six of sixteen reference examples changed a published, indexed manifest field with both hashes byte-identical.

RM127 — a corrected derivation has no release class, and the version number is the wrong place to carry one

✅ Severity medium · Status CLOSED 2026-08-21 — the charter was amended the same day it was filed, which is the whole item; filed, rewritten and answered within one pass · Owner maintainer · Motivating case S62 (just-dna-registry)

What shipped. Principle 3 gained two rules — Release class and artifact staleness are different axes and Authored identity is not the sizing test — and the charter gained a Rules only header item plus Principle 9, the cost-by-layer pricing promoted out of an amendment entry where it had been the only rule stated nowhere else. The reasoning moved to CONSTITUTION_AMENDMENTS_HISTORY.md, a new file, and the charter came out 11.5% smaller while gaining three rules. The obligation the amendment creates — a release declares its corrections — is owed by RM126, queued for 0.7, and until it is built the charter names a channel that does not exist.

This entry was first filed as the release table and the practice disagree, and that was aimed at the wrong target. The original framing indicted StudyRow.curator shipping in 0.6.5. It should not have: curator is additive, no already-published module can carry it, no stored value became wrong, and the only consequence is that a recompile writes different bytes — which P4 already declines to guarantee across compiler versions. Sizing it as a patch is defensible, and the table calling it a minor is the table being strict rather than the cut being wrong. The original text is preserved in the 2026-08-21 output-contract round.

The real item is RM121, and it is a change class the taxonomy does not have. stats.genes is an existing published field whose derivation was corrected — the same spec now yields a different value. Nothing was added, removed, promoted or retyped. The three rows we have are additive → minor, legibility → patch, removal/promotion/retype → major, and a corrected derivation is in none of them. It did not fall between two rules; it fell outside the list.

Why it read as safe, and this is the mechanism. The only test applied was does authored identity move? But stats sits outside content_signature by design — it is a derived facet, not content. So that test returns "safe" for any change to stats whatsoever, including replacing it with nonsense. It cannot fail there. It was not evidence; it was a tautology, and @tautology-zero is our own name for the shape — a check that cannot fail must not report a zero. RM123 shipped that same week about compile checks; the identical error was made one level up, in the release-sizing argument, where nothing was watching for it.

And the structural half. The property that makes a derived field cheap to change is the same property that makes the change undetectable downstream. stats is outside identity, so changing it costs nothing by the identity test and no digest, no signature and no revalidate can see it move. Measured: six of sixteen reference examples changed a published, indexed manifest field while both hashes stayed byte-identical. The cheapest changes to make are exactly the ones with no detection channel, and the identity test rewards them.

The version number cannot carry this, and the reason closes the original question rather than answering it. A corrected derivation is a bug fix. Deferring it to the next minor means knowingly serving a wrong value for an undefined period, which is not a trade anybody should take — so "make it a minor" is not available, and neither is any other scheme that encodes staleness in the release class. SemVer answers is the code contract compatible; it was never designed to answer are your stored outputs stale, and those are orthogonal. They must be separated rather than reconciled — which dissolves this entry's original three candidates instead of picking one.

What is left here is one charter question, and it is the maintainer's: does P3's sentence — "a new optional column… lands in a minor: the authored identity is unchanged, and only a recompile's artifact.digest moves" — get amended to say that release class and artifact staleness are different axes, with the second carried by the mechanism in RM126? The sentence currently states a ruling and, in the same breath, offers the identity test as its rationale — which is exactly the reading that sized RM121, so leaving it unamended leaves the trap armed. Everything else RM127 used to ask now belongs to RM126.

The 2026-08-21 decision round — six undecided minors answered in one pass

ROADMAP.md § Active items held six items whose common property was that every one of them was a decision rather than a missing line of code, and none had been made. All six were answered in a single pass on 2026-08-21. Four stayed open with their shape settled or narrowed and are still in the active file (RM103's manifest half, RM108, RM110, RM117); RM122 parked on demand and moved to the minor-deferral file (ROADMAP_0_8.md since the 0.7 cut); RM103's refusal half moved to ROADMAP § The 1.0 cleanup; and RM102 closed outright, which is why it is here.

The finding worth keeping is about the queue rather than any item in it. Two of the six were not design-blocked at all. RM110's encoding was already pinned by a test on one of its two producers, so nothing was undecided — it was parked because normalizing the other producer moves a fact signature and the round that found it was a patch round, which is a release-class objection that reads, in a status line, exactly like an open design question. RM102's was the mirror image: the entry argued two candidate repairs at length and the thing nobody had written down was that no incident had ever followed from the behaviour, which made "close it" a live option that had never been on the list. Both cost more attention than they were worth, and the same question would have found both: what would a decision here actually change?

RM102 — the enricher loads a .env into os.environ from library paths

Reopened 2026-09-27 by S124 as RM301, on this entry's own trigger: a host's configuration record was the boundary. RM301 takes the credential half only. The cache resolvers keep exporting, behind their switch, as decided below.

✖ Closed 2026-08-21 as a decision not to act, after the half of it that was a real defect had already shipped. Motivating case S39 from just-module-creator. Owner enricher.

What shipped, and it was the actual bug. load_dotenv_file=False reached none of the six cache resolvers: each passes its default_*_cache_dir() as an argument, and that helper went through a _cache_dir whose load_env() was unconditional, so the file was loaded before the resolver looked at its own flag. The knob did nothing at all. Threaded through _cache_dir and the six default_*_cache_dir helpers in 0.6.3, with test_locations.py running each resolver in a subprocess and pinning both directions plus the pre-fix arrangement, and a twelfth test walking both families so a seventh resolver cannot quietly reopen it. That is @off-switch-needs-a-probe and @registry-completeness in one repair.

What was filed and is now closed. Everything the repair does not reach: load_dotenv writes the whole file into os.environ, not the cache variables alone, and four credential paths — net, eutils, literature, pharmvar — call load_env() with no flag at all, deliberately, because a credential is loaded where it is read (@credential-where-read). So a caller passing False everywhere still has the process environment mutated by the first network client they construct.

Why it closed rather than shipping a fix. The record holds exactly one incident, and it is not one: S39's reporter lost about an hour to a test named test_a_token_does_not_leak_between_sessions failing with "The server is configured offline" instead of its assertion, because their fixture had cleared a variable with monkeypatch.delenv and override=False — which skips a variable that is present — let the file refill it. The credential involved was their own, in their own process, from their own .env; nothing crossed a boundary, no build shipped wrong data. Weighed against that: both candidate repairs cost a full minor, and the better-looking one is silent for every caller who never passed the parameter, so a deployment pointing its cache through .env alone simply stops finding it — the exact "the cache is right there" report the unconditional load was added to end (S14's shape: the addition being legal does not make the change legal).

The two repairs, recorded so they are not re-proposed as if new.

  • Flip the default and leave loading to the entry point. Right shape — a CLI loading .env is ordinary, a library function doing it while answering "where is the cache" is not — but a bare flip is silent, so the honest route is warn-in-one-minor-then-flip, and it has to cover the four flagless credential paths too or it is an assurance that is not one.
  • Narrow it to the cache variables. Rejected on its own terms: it makes the enricher a filter over somebody else's file, and the allowlist becomes a hand-kept list of every variable any tier might read — @registry-completeness, arriving as a design rather than as a bug. It also does not answer the reporter's actual complaint, which is about mutating the process environment at all.

What stands as the answer for 0.x. ENRICHER.md § cache locations states that the load writes into os.environ, that it is a library path rather than a CLI one, that override=False skips a variable that is present so deleting one is what lets the file win, and names both the switch and the flagless credential paths. That was the reporter's own fallback ask. Their defence — walking sys.modules and replacing every bound load_dotenv, rather than patching dotenv.load_dotenv, since every from dotenv import load_dotenv holds its own binding — is correct and stays correct.

Reopen it if the record changes, and the trigger is specific: something worse than a lost hour — a credential reaching a subprocess, a crash report, or any boundary at all. The failure mode argues for watching rather than for building, because it is green in CI and different on every developer's machine, which is the shape that stays undiagnosed longest.