Propose absence semantics: one diagnosis, three different remedies (#294, #304, #307)

[realmarcin]

Docs only. A written proposal covering #294, #304 and #307 as one theme, ending in three decisions to make.

The theme is real; the remedy is not shared

All three come from the same gap: the schema can say "has value X" or "is empty", and nothing else, so empty is overloaded across at least four meanings — not done, impossible, undecidable from the source, and deliberately excluded.

But the proposal's main structural claim is that they should not be fixed together:

• Ungroundable taxa are indistinguishable from not-yet-grounded ones (the real remainder of #276) #294 is missing vocabulary — the information already exists, gtdb_ground.py computes it and throws it away.
• Counter-selection (candidates deliberately excluded) has no machine-readable home in the schema #307 is a missing slot — the information exists in the source and has nowhere to go.
• DISCONNECTED rewards unsourced metadata: removing a fabricated abundance_level creates findings #304 is not a schema problem at all — it is auditor logic reading a perfectly good schema wrongly.

Bundling them would drag a code fix into a data migration for no benefit.

Measured, not asserted (307 records / 1007 taxa)

issue	finding
#294	Of 372 ungrounded taxa: 285 have no GTDB equivalent, 85 are ambiguous, and the last 5 are entries deliberately withheld under #292. Honest tally: 370 permanent, 2 withheld, zero pending work.
#304	107 of 302 records with interactions (35%) are entirely COMMUNITY_LEVEL, which the auditor credits with no connections; 931 of 1007 taxa (92%) are exempt from DISCONNECTED via abundance_level/functional_role.
#307	193 records carry engineering_design, only 40 carry free-text notes — most have nowhere at all for a load-bearing negative result.

Two of these are load-bearing for the argument. GTDB grounding is complete to its ceiling and the schema cannot say so — which is precisely why #276 read as ~40% outstanding work when the achievable ceiling is ~63%. And for #304, the exemption rather than the connectivity check is doing essentially all the work, so DISCONNECTED does not mean what its name says and actively rewards unsourced metadata.

Verification changed the proposal while writing it

The first draft claimed 5 taxa were "immediately actionable regardless of what is decided here". Checking what they actually were showed every one is a withheld entry blocked on #292. That correction did two things: it added WITHHELD as a fifth enum value, and it removed the quick win.

It also produced the sharpest argument for the enum. The pin in tests/test_gtdb_withheld_groundings.py exists to stop a tool re-run reinstating those groundings — that is a test compensating for vocabulary the schema lacks.

What is proposed

1. Ungroundable taxa are indistinguishable from not-yet-grounded ones (the real remainder of #276) #294 — gtdb_grounding_status enum on TaxonDescriptor (GROUNDED | NO_GTDB_EQUIVALENT | AMBIGUOUS | WITHHELD | NOT_ATTEMPTED), three of which the tool already computes.
2. DISCONNECTED rewards unsourced metadata: removing a fabricated abundance_level creates findings #304 — credit COMMUNITY_LEVEL interactions as connecting members, then drop the metadata exemption. Change (1) alone is safe and strictly an improvement; (2) alone is not.
3. Counter-selection (candidates deliberately excluded) has no machine-readable home in the schema #307 — a counter_selection block on CommunityEngineeringDesign, with excluded_taxon optional, because ARC is exactly the case where excluded strains cannot be distinguished from retained ones.

Recommended order: #304's first change, then #294, then #307 — smallest first, and it unblocks #273, which cannot decide whether to restore the network gate while DISCONNECTED means something other than its name.

§6 records what is deliberately not proposed, including a general absence-annotation framework: three instances is not enough evidence to design one.

Decision requested per remedy — they are independent. No code or data changes here; 899 tests pass unaffected.

🤖 Generated with Claude Code

---

Review round: simulating the #304 change reversed the recommendation

§4.2 originally asserted that "doing (1) without (2) is safe and strictly an improvement". That was reasoning, not measuring. Simulating all four configurations over the current KB:

configuration	DISCONNECTED reported
today — no credit, exemption kept	32
drop the exemption only	390
credit COMMUNITY_LEVEL only	1
credit COMMUNITY_LEVEL + drop the exemption	19

Crediting COMMUNITY_LEVEL alone is safe — and drops reporting to one finding across 307 records. The rule becomes vacuous, and a gate that never fires is not an improvement over one that fires for the wrong reason. Dropping the exemption alone reports 390, a 12× increase that buries the signal.

Only together do they land somewhere defensible: 19 — fewer than today's 32, while measuring what the name promises, and a genuine work-list rather than an artefact.

§4.2 now carries this table and states the halves must ship together; §5's recommended sequence changes from "change (1) first" to "both changes together, do not split".

This is the second time writing this proposal that checking a number changed the recommendation. The first was discovering the five apparently-groundable taxa were deliberately withheld, which added WITHHELD to the proposed enum and removed a claimed quick win. Both were claims that felt safe enough to assert — which is the argument for simulating a rule change before proposing it, since the proposal is the artefact someone will act on.

899 tests pass; docs-only, no code or data touched.

---

Review round: re-derived the proposal's own figures

Rebased onto main and re-measured rather than trusting the numbers. Three things changed.

§4.2 is no longer a proposal — it shipped. #304 landed as PR #311 while this sat open: both halves together, exactly the predicted 19 findings, network issues 49 → 23. It is marked IMPLEMENTED and kept as the worked example, since it is the only one of the three where the simulation can be checked against the outcome. Two things it surfaced are cross-referenced — #312 (the credit is all-or-nothing, which overlaps §4.3's design question) and #313 (dangling-edge detection lives in an orphaned script nothing runs).

Re-checking §3.1 found a real gap. Refreshed to 311 records / 1024 taxa: 288 no-equivalent, 87 ambiguous, 6 groundable. Five are the withheld entries from #292 as before — but the sixth is a genuine gap, filed as #314: a taxon in 000315 whose term.id I corrected after grounding ran (following Edison's advice to reground Microcystis to genus), leaving the derived block absent with nothing to notice.

That incident is the proposal's own thesis in miniature, so it is written up as such. One blank column now encodes four distinct situations — impossible, undecidable, deliberately withheld, accidentally stale — and telling them apart required running the grounding tool across the whole KB and cross-referencing the withheld list. With the proposed enum it is a one-line query.

Stale figures corrected: engineering_design 193 → 197 records; the 92% exemption restated in past tense now that it no longer exists; and the decision line narrowed from three remedies to the two still open.

#314 also notes a fix worth doing regardless of what is decided here: a gtdb_classification records ncbi_source_id, so a mismatch against term.id is detectable today with a cheap test and no schema change.

908 tests pass; docs-only.

[Copilot]

Pull request overview

Adds a docs-only proposal that unifies issues #294, #304, and #307 under the theme of “absence semantics” (empty slots overloading multiple meanings), while arguing the remedies should be independent (vocabulary vs slot vs auditor logic).

Changes:

• Introduces a written proposal diagnosing “empty slot overload” and quantifying its impact across the KB.
• Proposes three independent remedies: a GTDB grounding-status enum (#294), an auditor logic fix for DISCONNECTED (#304), and a schema block for counter-selection (#307).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[realmarcin]

Review

Proposal-only — one file under proposals/, no schema or data touched. Confirmed.

I spot-checked the two load-bearing factual claims rather than taking the diagnosis on trust, since a proposal is only as good as the problem statement.

Claim: gtdb_ground.py already computes the states but does not persist them. Holds. scripts/gtdb_ground.py:12,16,427 computes and prints AMBIGUOUS, including the concrete case the proposal cites — an NCBI genus shattering into many GTDB genera. It reports and discards.

Claim: the audit rewards an unsourced abundance_level. Holds, and it is sharper than the prose suggests. src/communitymech/network/auditor.py:258:

if taxon_data.get("abundance_level") or taxon_data.get("functional_role"):
    continue

Any truthy value suppresses the DISCONNECTED finding. Nothing checks provenance, so a fabricated abundance silences the audit exactly as well as a sourced one — and deleting a fabricated value creates a finding. That is a gate that pays out for filling a slot rather than for filling it correctly, which is the same shape as the checks-that-pass-while-verifying-nothing this fleet has hit repeatedly.

The judgement I'd most want to keep is §2 — refusing to unify the three into one "absence annotation" mechanism. The temptation is obvious and the reasoning against it is correct: #294 is a missing vocabulary (the information exists, unpersisted), #307 is a missing slot (the information exists in the source with nowhere to go). Those need different remedies, and a single general mechanism would have obscured that. Resisting a tidy abstraction that does not fit is worth more here than the specific remedies.

No findings. Nothing to file.

One note on process rather than content: this asks for three independent approve/reject decisions, which makes it a document that stops being useful once decided. Worth recording the outcome in the file itself when you decide — otherwise the next reader cannot tell a live proposal from a settled one, which is how #209 ended up being followed after it had already been reversed.