Reverse 15 electron-transfer edges off TRAIT subjects (#295)

[realmarcin]

Closes #295 (for the electron pair; see follow-up below for the rest).

The issue's premise was right, but for a different reason than stated

The issue says METPO:2000008/METPO:2000009 "are declared with an organism
domain". They are not — not directly. Both declare no rdfs:domain and no
rdfs:range at all in the vendored data/raw/metpo.owl.

But both are rdfs:subPropertyOf METPO:2000001 ("organism interacts with
chemical"), and that property declares:

<rdfs:domain rdf:resource="https://w3id.org/metpo/1000525"/>   <!-- microbe -->
<rdfs:range  rdf:resource="https://w3id.org/metpo/1000526"/>   <!-- chemical entity -->

OWL propagates a domain through subPropertyOf, so the organism domain is
inherited and upstream. It is not self-inflicted by TraitMech's own
domain: declarations, and it cannot be edited away locally.

That matters because domain in OWL is an inference rule, not a constraint.
<trait> uses electron acceptor <chemical> does not fail validation — it makes
a reasoner conclude the TRAIT node is a microbe. predicate_id is an unbound
string in the schema, so nothing in just qc could see it. Same failure mode as
the RO:0002411 mapping in #235.

What changed

15 edges reversed (13 uses electron donor, 2 uses electron acceptor)
from <trait> --uses electron X--> <chemical> to
<chemical> --enables--> <trait> (RO:0002327), across 14 files.

This is the idiom the corpus already uses for exactly this shape: enables
appears 7x as CHEMICAL -> TRAIT, including ferric_iron --enables--> dir_trait
in dissimilatory_iron_reduction.yaml — the same graph two of the reversed
edges live in, with the description "Fe(III) acts as terminal electron acceptor
enabling DIR." Evidence blocks are untouched.

The donor/acceptor role is not lost: it stays in the object node's label and
grounding (inorganic_electron_donor, METPO:1007502) and in each edge
description, which is where the pre-existing sibling edge already carried it.

A forward guard against it recurring. subject_types for both rows in
mappings/predicate_grounding.tsv is now NONE — a new sentinel meaning "no
node type satisfies this domain", distinct from */empty ("any"). It was
needed because CausalNodeTypeEnum has no organism member (graphs are
deliberately taxon-agnostic), so the constraint was previously inexpressible:
"exclude TRAIT" would still have wrongly permitted CHEMICAL, GENE_OR_PROTEIN, etc.
ground_causal_predicates.py now refuses to ground such a label onto any edge
and reports blocked_by_node_type, mirroring how #236 handled RO:0002411.

Playbook corrected. docs/CURATION_PLAYBOOK.md previously taught this
pattern, with a worked example using a trait subject. It now shows the
chemical-subject form and explains why. The OBJECT_PROPERTY records' domain:
is unchanged and stays correct — the organism-subject form is valid at the
assertion site; only the causal-graph reuse was wrong.

Why not the alternatives

• TRAIT as a stand-in for "an organism bearing the trait" makes the node
  polysemous. dir_trait rdfs:subClassOf anaerobic_respiration sits in the same
  graph, so the node is already committed to being a phenotype class. That
  ambiguity would propagate through the Causal graphs are 62% fragmented and audit-graphs cannot see it #183 backfill.
• Adding ORGANISM nodes over-models graphs that are intentionally
  taxon-agnostic, and would need a new enum member used by nothing else.

Scope: this fixes ~4% of the actual defect

While verifying, I found the same inherited domain reaches 66 METPO
properties, and the corpus asserts them on non-organism subjects in
366 edges across 193 files and 14 predicate labels:

count	predicate		count	predicate
249	produces		8	uses energy source
30	reduces		6	hydrolyzes
21	oxidizes		6	degrades
14	exports		3	accumulates
12	imports		2	disproportionates
12	uses carbon source		3	(does not produce, is hydrolyzed to, transports)

Each needs its own replacement judgement — produces on a
BIOLOGICAL_PROCESS subject is not obviously enables — so rewriting them
here would have been 366 edges of unreviewed ontology guesswork. Filed as a
follow-up issue instead; this PR stays scoped to the pair #295 named.

Verification

• just qc — exit 0, 477/477 files validate, 0 ERROR rows, derived reports current
• uv run pytest — 379 passed
• 3 ELLIPTICAL_SNIPPET findings were re-keyed in conf/evidence_snippet_baseline.tsv,
  not re-baselined: the baseline key embeds subject->object, so reversing an edge
  changes the key. Same file, same code, byte-identical message; retargeted the 3
  rows individually rather than running --write-baseline, which would have
  re-frozen the whole corpus and could mask real regressions.

🤖 Generated with Claude Code

---

⚠️ Update after review — read before merging

Two independent reviews found that enables is not range-correct either.
data/raw/biolink-model.yaml:5099-5110 defines enables (exact_mappings: [RO:0002327]) with range: biological process or activity. A TRAIT is a
disposition, not a process, so <chemical> enables <trait> swaps the METPO
domain violation for an RO range violation. Verified independently; the claim
holds.

This is pre-existing, not introduced here. main already had 149
enables edges with TRAIT objects; this PR takes it to 164. Gating the
enables row honestly would block all 164 and fail just qc, so the range
question is filed rather than solved here:

• 164 enables edges point at TRAIT nodes, violating RO:0002327's range — and the enables mapping row is ungated #302 — the 164-edge range violation and the three ways out. The
  strongest looks like minting a chemical→trait relation in METPO, following
  proposals/metpo_traitmech_v2/proposal.md:71, which proposed manifests as
  for exactly this reason.
• Reversing electron edges to enables collapsed the donor/acceptor distinction for 7 nodes #303 — collapsing uses electron donor and uses electron acceptor onto
  one relation loses the donor/acceptor distinction for 7 of the 15 nodes,
  including both DIR acceptor edges.

What changed in response: the playbook no longer prescribes
<chemical> enables <trait> as the general remedy for the 66-predicate family
— that block was going to be the reference for #301's 366 edges and the #183
backfill. It now carries the range caveat and recommends pointing the chemical
at the graph's process node, which is range-correct today. Also added:
curation_history events on all 14 files (a correcting event on DIR that
supersedes #294's now-inaccurate entry), a sentinel/enum collision guard with a
test, and canonical sort order restored to the baseline.

Merge judgement: the 15 edges move off a taxonomy-crossing entailment
("trait is a microbe") onto an established corpus convention that is wrong in a
narrower way, so #295's specific defect is gone. That is a real but partial
improvement. If #302 decides these belong on a process node or a new METPO
relation, these 15 get rewritten again — worth deciding before merging.

Note on the gate's reach: ground_edges_in_doc skips any edge that already has a non-empty predicate_id, so the NONE sentinel blocks newly written, ungrounded edges. A hand-written edge arriving with predicate_id: METPO:2000009 already filled in — the form all 15 of these were in — is not caught. It is a forward guard, not a retroactive one.

[culturebot-reviewer]

Reviewing PR #300

• Read repo conventions (README.md, docs/)
• Review the 15 reversed edges in data/traits/**
• Verify the NONE sentinel in predicate_grounding.tsv + ground_causal_predicates.py
• Check evidence-snippet baseline re-keying
• Check graph reachability / derived HTML consistency
• Post verdict

View job run

[culturebot-reviewer]

Claude finished @realmarcin's task in 4m 48s —— View job

---

Review: PR #300

• Read repo conventions (README.md, docs/)
• Review the 15 reversed edges in data/traits/**
• Verify the NONE sentinel in predicate_grounding.tsv + ground_causal_predicates.py
• Check evidence-snippet baseline re-keying
• Check graph reachability / derived HTML consistency
• Post verdict

---

The diagnosis is right and the subPropertyOf tracing is correct. The problem is the replacement.

🟡 RO:0002327 has a process range — CHEMICAL --enables--> TRAIT violates it

This repo's own vendored data/raw/biolink-model.yaml:5099-5110, which is what the mapping row cites as the cross-walk:

enables:
  description: holds between a physical entity and a process, where the physical entity executes the process
  domain: physical entity
  range: biological process or activity
  exact_mappings: [RO:0002327]

A TRAIT node is not a biological process or activity, and inorganic sulfide does not execute lithotrophy. So the 15 edges trade a domain violation for a range violation — the same shape as the RO:0002411 defect in #235 that the PR cites as its own precedent, and equally invisible to just qc (label-correspondence passes because the CURIE's label really is "enables"; the enables row at mappings/predicate_grounding.tsv:9 is */*, so the gate this PR just built is not applied to the predicate it moved 15 edges onto).

The clearest demonstration is inside a file the PR edits. data/traits/physiology/lithoautotrophic.yaml:109-127 now carries two edges with the same subject and predicate:

- subject: inorganic_electron_donor
  predicate: enables
  object: lithoautotrophic_trait          # TRAIT — range violation
- subject: inorganic_electron_donor
  predicate: enables
  object: respiratory_energy_conservation # BIOLOGICAL_PROCESS — correct

The range-correct edge is already there. Most of the 14 files have an equivalent process node (energy_metabolism, respiratory_energy_conservation, electron_transport_chain) that the donor could point at instead. Where the target really has to be the trait class, this repo already has a documented remedy: proposals/metpo_traitmech_v2/proposal.md:71 proposes manifests as precisely because "TraitMech's typical object is a TraitMech-internal trait class" and the upstream candidates' ranges were wrong. That reasoning applies here verbatim.

The 7 pre-existing CHEMICAL -> TRAIT enables edges are debt, not a warrant. Whichever way this lands, object_types on the enables row needs to say so, or the next PR repeats it.

🟡 The playbook now teaches the same range violation, at 366-edge scale

docs/CURATION_PLAYBOOK.md generalizes the pattern well past the electron pair:

- subject: glucose                     # CHEMICAL grounded to CHEBI:17234
  predicate: enables                   # RO:0002327
  object: <some_trait>

Glucose executes nothing. This block is what #301 (366 edges, 193 files) and the #183 backfill will be curated against, so a wrong idiom here costs an order of magnitude more than the 15 edges in this PR. Worth settling the relation before the doc blesses it.

🔵 The gate is one-sided

ground_edges_in_doc skips any edge that already has a non-empty predicate_id (scripts/ground_causal_predicates.py:153-155). The NONE sentinel therefore catches a newly written, ungrounded uses electron donor edge, but not a hand-written one that arrives with predicate_id: METPO:2000009 already filled in — which is the form all 15 of these were in. "A gate so it cannot recur" is stronger than what the mechanism does.

What checks out

• NONE sentinel — parsed before the enum-name validation, so a typo still hard-fails; subj_ok is not None handles the falsy empty frozenset correctly (an if subj_ok: would have silently disabled it). Tests cover both.
• Baseline re-keying — correct and minimal. _key drops the index and detail and compares occurrence counts per key, so the three re-keys preserve exactly the right totals (chemoorganoheterotrophic 2 → 1+1, photoorganoheterotrophic 2 → 1+1, organoheterotrophic 1 → 1). Not re-baselining was the right call.
• Reachability — audit_causal_graphs.py:32-35 is deliberately undirected, so reversal is structurally neutral. The unchanged reports/causal_graph_audit.tsv is consistent with that.
• Evidence — snippets untouched; the reworded descriptions still match what the snippets support.
• Advisory only: no history/records/** entry for the 14 modified trait files.

Verdict

Requesting changes on the choice of replacement relation, not on the analysis. The METPO domain problem is real and worth fixing; enables just isn't the term that fixes it.

Fix this →
· branch

[culturebot-reviewer]

RO:0002327 enables has range "biological process or activity" (data/raw/biolink-model.yaml:5099-5110, which the mapping row itself cites as the cross-walk). The 15 reversed edges point it at TRAIT nodes, so they trade the METPO domain violation for an RO range violation — the same shape as the RO:0002411 defect in #235 that this PR cites as precedent, and equally invisible to qc. lithoautotrophic.yaml:109-127 now carries the violating edge directly beside a range-correct one with the same subject and predicate (object respiratory_energy_conservation, a BIOLOGICAL_PROCESS). The playbook generalizes the idiom to 'glucose enables ', which is what #301's 366 edges and the #183 backfill will be curated against.

The diagnosis, the subPropertyOf tracing, the NONE sentinel (correctly parsed before enum validation; is not None handles the falsy empty frozenset), the baseline re-keying (counts preserved exactly; not re-baselining was right), and the undirected-reachability reasoning all check out. It is the choice of replacement relation that needs revisiting. Full detail in the review comment.

[realmarcin]

Reviewed and confirmed — the range finding is correct, and I verified it independently rather than taking it on faith. data/raw/biolink-model.yaml:5099-5110:

enables:
  domain: physical entity
  range: biological process or activity
  exact_mappings: [RO:0002327]

A TRAIT is a disposition, not a process, so <chemical> enables <trait> does carry a false type entailment. My PR body's framing was too confident.

Where I disagree: the scope of the remedy. This isn't debt the PR created or can pay off. On main there were already 149 enables edges with a TRAIT object; this PR takes that to 164. Setting honest object_types on the enables row — the fix suggested — would block all 164 and fail just qc immediately. So the choice was between solving a 164-edge corpus convention inside a PR scoped to 15 edges, or filing it. I filed it:

• 164 enables edges point at TRAIT nodes, violating RO:0002327's range — and the enables mapping row is ungated #302 — the range violation, with the three options laid out. I flagged the proposals/metpo_traitmech_v2/proposal.md:71 manifests as precedent as the strongest, for the reason you gave: it exists precisely because "TraitMech's typical object is a TraitMech-internal trait class."
• Reversing electron edges to enables collapsed the donor/acceptor distinction for 7 nodes #303 — the donor/acceptor collapse. That one I'd underweighted; you're right that for 7 of the 15 the role now survives only in free text, and the two DIR edges were acceptor edges sharing a predicate with the donor convention.

What I did change, because it was the part that actually scaled: the playbook no longer prescribes <chemical> enables <trait> as the general remedy for the 66-predicate family. That block was going to be the reference for #301's 366 edges and the #183 backfill, which is where a wrong idiom gets expensive. It now carries the range caveat, points at #302/#303, and recommends the form that is range-correct today — chemical to the graph's process node, as lithoautotrophic.yaml already does.

Also fixed from the review: curation_history events on all 14 files (they had none), with the DIR one explicitly superseding the #294 entry that still describes those edges in their old direction — added as a correcting event rather than editing history in place. Plus the sentinel/enum collision guard with a test, and the baseline restored to canonical sort order.

On merging as-is: the 15 edges move from "trait is a microbe" — which crosses into taxonomy — onto an established 149-edge corpus convention that is wrong in a narrower way. That's a real if partial improvement, and #295's specific entailment is gone. But it is a judgement call, and #302 may well decide these 15 should land somewhere else entirely, in which case they'd be rewritten again. Flagging that explicitly rather than merging past it.

[culturebot-reviewer]

Claude finished @realmarcin's task in 3m 20s —— View job

---

Re-review: PR #300 (after caad3904)

• Diff the latest commit against my prior review
• Check the reworked docs/CURATION_PLAYBOOK.md block
• Verify the new curation_history events on the 14 trait files
• Verify the sentinel/enum collision guard + test
• Check the baseline sort-order restore
• Post verdict

---

The substantive disagreement from round one is settled, and I'm not re-litigating it. You verified the range claim independently, filed #302/#303, and pulled the over-claim out of the doc that was going to be read by #301's 366 edges — that was the part that scaled, and it's fixed. docs/CURATION_PLAYBOOK.md:129-172 now leads with "do not assume enables" and shows the process-node form. Accepting the filing decision.

One thing didn't come along with it.

🟡 The mapping row still prescribes the idiom the playbook now warns off

mappings/predicate_grounding.tsv:5-6, notes column on both electron rows:

The corpus records these relations as <chemical> RO:0002327 <trait> instead

Written flat, as the answer. Added in the same commit as the playbook block that says the opposite:

What to use instead is not settled — do not assume enables. … Until #302 lands, prefer pointing the chemical at the graph's process node

A curator who hits uses electron donor and gets blocked_by_node_type reads the notes column — that's what it's for and where the block sends them. They will not necessarily then open the playbook. Right now the two places disagree, and the TSV is the one on the shorter path. Either make it descriptive rather than prescriptive ("the 15 edges in #295 were moved to <chemical> RO:0002327 <trait>; see #302 — this form is not settled") or point it at the process-node form the playbook recommends.

Same fix belongs on the enables row at line 9, whose notes read "common in causal-graph node→activity edges." 164 of its edges have a TRAIT object, not an activity — the row's own description of itself is the thing that made this easy to miss. A #302 pointer there costs a clause and lands where the next curator is looking. I'm not asking for object_types to be gated; you're right that it fails just qc on 164 edges and belongs to #302.

On the 15 edges

Not blocking on these. For the record, so #302 doesn't restart cold: 12 of the 14 files already have a BIOLOGICAL_PROCESS node (chemolithoautotrophic.yaml and organoheterotrophic.yaml don't), so the range-correct target mostly exists — but it isn't the mechanical repoint I implied last round. In lithoautotrophic.yaml:117-127 the donor→process edge is already there, so repointing would collapse two edges into one and drop the evidence block on the trait-targeted edge. That's a merge judgement per graph, not a rewrite. Your read was better than mine here.

What checks out in this commit

• Sentinel collision guard — scripts/ground_causal_predicates.py:112-119 runs before any row is parsed, so a schema that gains a NONE member fails at load rather than silently blocking every gated row. Test asserts on the message.
• Provenance — all 14 files carry a REVERSE_CAUSAL_EDGE_DIRECTION event, and each one states the residual range caveat rather than presenting the new form as clean. The dissimilatory_iron_reduction.yaml:202-216 event names the 2026-08-05T00:00:00Z entry it supersedes instead of editing it — right call.
• Baseline — back in canonical _key order (verified both hunks sort correctly), still exactly 3 rows vs. main.
• "No corpus edge carries either label" — holds. The 20 remaining uses electron hits are prose, history, and respiration.yaml:107's distinct uses electron flow from.

Advisory, not blocking: ground_edges_in_doc still skips edges with a non-empty predicate_id (scripts/ground_causal_predicates.py:161-163), so the gate is forward-only. The playbook says so now ("forward guard"); the PR body still says "a gate so it cannot recur."

Verdict

Requesting changes on the mapping-row notes only — two clauses in one file. Everything else I raised is addressed.

Fix this →
· branch

[culturebot-reviewer]

Requesting changes on one item only; the round-one disagreement is settled.

mappings/predicate_grounding.tsv:5-6 notes still prescribe <chemical> RO:0002327 <trait> as what the corpus records — contradicting docs/CURATION_PLAYBOOK.md, added in the same commit, which now says "do not assume enables" and recommends the graph's process node until #302 lands. A curator who trips the blocked_by_node_type gate reads the notes column, not the playbook, so the wrong idiom is on the shorter path. Same clause belongs on the enables row at line 9, whose notes describe it as "common in causal-graph node→activity edges" when 164 of its edges have a TRAIT object. Not asking for object_types to be gated — that fails just qc on 164 edges and is #302's.

Everything else raised last round is addressed: the playbook no longer generalizes the idiom to the 66-predicate family, the sentinel/enum collision guard is correctly ordered before row parsing, all 14 files carry provenance (with the DIR event superseding rather than editing #294's), and the baseline is back in canonical sort order at exactly 3 changed rows.

Not blocking the 15 edges. For #302: 12 of the 14 files do have a BIOLOGICAL_PROCESS node, but repointing is not mechanical — lithoautotrophic.yaml:117-127 already has the donor→process edge, so it would collapse two edges and drop an evidence block. Your read on scope was better than mine.

[culturebot-reviewer]

Claude finished @realmarcin's task in 14m 45s —— View job

---

Re-review: PR #300 (after 592e4db7)

• Diff 592e4db7 against my round-two review
• Check the reworked notes column in mappings/predicate_grounding.tsv
• Verify the numbers the notes now assert
• Confirm nothing else regressed
• Post verdict

---

The one item I was blocking on is fixed. mappings/predicate_grounding.tsv:5-6 no longer prescribes <chemical> RO:0002327 <trait> — it records what the 15 edges were moved to, says the form is not settled, names the range problem and the donor/acceptor collapse, points at #302/#303, and sends the curator to the process-node object. That's the version that agrees with the playbook, and it's on the path a blocked curator actually walks. Line 9 carries the same correction, including the sentence that matters most: "do not read the */* as license to add more TRAIT-object edges." Better than what I asked for — I'd have settled for a pointer.

Verified rather than assumed

The notes now assert numbers, so I counted them independently rather than trusting the PR body:

claim	result
164 enables edges with a TRAIT object	164 on HEAD ✓
pre-existing, not introduced here	149 on origin/main — delta is exactly the 15 ✓
gate is a forward guard, no corpus edge carries either label	0 uses electron donor/acceptor edges remain ✓
12 of 14 files have a BIOLOGICAL_PROCESS node	✓ — chemolithoautotrophic.yaml and organoheterotrophic.yaml are the two without

TSV integrity: all 101 rows parse at 9 fields, so the long prose introduced no embedded tab. The notes column is read by csv.DictReader and consumed by nothing — check_biolink_coverage.py doesn't touch it and it isn't surfaced in generated HTML — so the angle brackets and #302 refs are inert rather than a rendering or comment-parsing hazard.

Two things for #302, not for this PR

Only 22 of the 164 have a CHEMICAL subject. The row's note frames the problem as range-only ("biolink gives enables domain 'physical entity' and range 'biological process or activity'"), but 142 of those 164 edges have a subject that is not a chemical and may not satisfy physical entity either. #302 is a domain question as well as a range one, and it's a larger surface than the electron-edge discussion has implied. Worth carrying into the issue before anyone scopes it as "repoint the chemicals."

The PR body still overstates the gate. It says "a gate so it cannot recur," but ground_edges_in_doc skips any edge arriving with a non-empty predicate_id (scripts/ground_causal_predicates.py:161-163) — which is the form all 15 of these were in. docs/CURATION_PLAYBOOK.md:136 says "forward guard" and is correct; the PR body is the one that's still ahead of the mechanism. Cosmetic, and squash-merge text is easy to fix at merge time.

Verdict

Approved. Everything I raised across both rounds is addressed, and the two items above belong to #302 and to the merge commit message respectively, not to this diff.

On the merge judgement you flagged: I agree it's a judgement call and I'd make the same one. The 15 edges move off a taxonomy-crossing entailment onto an established convention that is wrong more narrowly, and the corpus-scale documentation — the part #301's 366 edges and the #183 backfill get curated against — now tells the truth about that convention instead of blessing it. If #302 relocates these 15, it relocates them alongside 149 others, which is the right unit of work for that decision.

Disclosure: uv run pytest and just qc are blocked by this environment's permission layer, so those results are taken on your word. The only change since my last review is TSV prose, which cannot affect them.
· branch

[culturebot-reviewer]

Round-two blocker resolved. The notes column on both electron rows is now descriptive rather than prescriptive, marks the enables form unsettled, points at #302/#303, and recommends the process-node object; the enables row states the biolink range, the 164-edge count, and why object_types is not gated today.

Independently verified: 164 enables->TRAIT edges on HEAD vs 149 on origin/main (delta +15, matching the reversed edges); 0 remaining 'uses electron donor'/'uses electron acceptor' edges, so the playbook's forward-guard claim holds; 12 of 14 files have a BIOLOGICAL_PROCESS node and exactly one (lithoautotrophic.yaml) already carries the donor->process edge. All 101 TSV rows parse at 9 fields; the notes column is not consumed by code or surfaced in generated HTML, so the angle brackets and issue refs are inert.

Two non-blocking notes for #302, not for this PR: only 22 of the 164 enables->TRAIT edges have a CHEMICAL subject, so #302 is a domain question as well as a range one -- 142 of them have subjects that may not satisfy 'physical entity' either. And the PR body still describes the sentinel as 'a gate so it cannot recur' when ground_edges_in_doc skips any edge arriving with a non-empty predicate_id; the playbook says 'forward guard' correctly, the PR body does not.

Could not run pytest or just qc in this environment (permission layer), so the verification claims in the PR body are taken on the author's word; the only change since my last review is TSV prose.