Contributing data — strengthen the register¶

Most nutrition data is crowd-sourced into a swamp because nothing gates it. This project is different: every contribution walks a fail-closed gate before it can strengthen anything. An unsourced number can never become a confident one, so the crowd can only ever strengthen the register — never weaken its epistemics.

A contribution is a small JSON file. You add one, open a PR, and CI validates it with biology_as_code.contrib.validate_contribution (see tests/test_contribution.py). The verdict is one of three:

Verdict	Meaning
`ACCEPTED`	Schema-valid, the target resolves, and a primary source backs it. It can raise the target's strength in the validation ledger.
`NEEDS_SOURCE`	Well-formed and on-target, but unsourced. Recorded `OPEN` (strength `0`) — kept, but promotes nothing.
`REFUSE`	Malformed, the target doesn't exist, or a magnitude is asserted with no primary evidence.

The one rule behind all three: empty beats fake.

What you can contribute¶

Start with evidence — it's the highest-leverage type, because it raises the tier of rules the whole engine already uses.

`type`	Strengthens	Must carry
`evidence`	a law's evidence tier (FLOW → EVIDENCE → UNITS)	a resolvable `source`
`packet_fill`	fills a food packet field, fewer `UNEVALUABLE`	structural fills need no magnitude; magnitudes need a source
`claim`	the reference claim corpus (claim × food × expected verdict)	the law path that produces the verdict
`gate_bound`	a new gate or bound rule	a source and it must satisfy the CI invariant (`GateRule` ↔ `gate.present`)

The shape¶

{
  "id": "contrib.evidence-unlu-2005-law020",
  "type": "evidence",
  "target": { "kind": "law", "ref": "LAW-020" },
  "payload": { "law": "LAW-020", "finding": "intrinsic food lipid opens the fat-vehicle gate" },
  "source": { "kind": "pubmed", "pmid": "15735074", "citation": "Unlu NZ et al. J Nutr. 2005;135(3):431-436." },
  "submitted": "2026-07-25"
}

target.kind is law, packet, nutrient, claim, mechanism, or pathway_step. law, packet, mechanism, and pathway_step refs must exist in the live register, or the contribution is REFUSEd.
source is pubmed (a PMID), doi, guideline, or textbook (a citation string). No fabricated metadata — a PMID that isn't a PMID is NEEDS_SOURCE.
asserts_magnitude: true means you're claiming a specific number. That path is REFUSEd without a primary source. Directions (expands/narrows) don't need one; magnitudes always do.
strength is assigned by review on the ledger's 0–5 scale — leave it out.

Worked examples live in examples/contributions/: ACCEPTED, NEEDS_SOURCE, REFUSE, and a peer-reviewed pathway step.

Reviewing cogs and steps (mechanisms, pathway steps)¶

The same gate reviews code cogs, not just the register. Point a contribution at a mechanism or a single modelled step and it flows through the identical pipeline:

mechanism — ref is a mechanism id, e.g. "dmt1".
pathway_step — ref is "<pathway>::<from_node>-><to_node>", e.g. "iron_absorption::fe2_lumen->fe2_enterocyte". A ref that doesn't match a real edge is REFUSEd, so a step review can't drift from the graph.

Peer sign-offs and tiers¶

A contribution can carry independent human signoffs. They don't change the verdict; they raise the tier (the ledger's 0–5 strength), so a thing keeps operating at whatever tier it has actually earned:

Distinct reviewers	Tier reached	May do
0 (sourced only)	3	usable as an established mechanism/gate
1	4	direction locked, magnitude bounded
≥2 independent	5	a magnitude may be locked

disputed sign-offs and duplicate reviewers never promote — locking a number (tier 5) always needs two independent verifiers, the same bar a journal uses. Sign-offs are assigned by review, not the submitter.

{
  "id": "contrib.review-dmt1-iron-step",
  "type": "evidence",
  "target": { "kind": "pathway_step", "ref": "iron_absorption::fe2_lumen->fe2_enterocyte" },
  "payload": { "mechanism": "dmt1" },
  "source": { "kind": "pubmed", "pmid": "39005063" },
  "signoffs": [
    { "reviewer": "reviewer-a", "date": "2026-07-25", "verdict": "verified" },
    { "reviewer": "reviewer-b", "date": "2026-07-25", "verdict": "verified" }
  ]
}

The review board that renders every cog/law/step at its current tier (tools/check_cog_evidence.py) lives at the monorepo root, outside the installed wheel. The contribution shape above is the part that ships with the package; the board just reads the ledger these files form.

How to submit¶

Fork the repo.
Add one file: examples/contributions/contrib.<short-slug>.json.
Open a pull request. CI runs the gate; the verdict shows in the checks.
A maintainer merges ACCEPTED contributions, and the target's ledger row rises.

Prefer not to touch JSON? Open an evidence issue — the form maps one-to-one onto the fields above, and a maintainer turns it into the file.

What survives scale¶

Never a magnitude without a primary source.
Never a green verdict over a missing field.
Every accepted contribution carries its source into the ledger. That trail — not anyone's authority — is what makes the register trustworthy.