PR 4: Ontology resolution stage + CELLxGENE organism wiring

[mengerj]

Scope

Implements PR 4 — Ontology resolver from the roadmap: the shared
parce/ontology/ resolution stage plus organism wiring into the CELLxGENE
normalizer. Every source's free-text design fields now resolve to the same
ontology IDs — the precondition for cross-source linking (ARCHITECTURE §5).

Split note: the original PR 4 also bundled the canonical-schema change
(replace free-text modality with an EFO assay term + a stored
molecular_layer field). That migration is now PR 4b (new ▶ Next up). The
molecular_layer derivation is implemented here; only its storage on the nodes
is deferred.

What's in it

• ontology/registry.py — Facet → ontology constant (EFO/OBI/PSI-MS, UBERON,
  MONDO, NCBITaxon, ChEBI, EDAM). Pins ontologies, not term IDs.
• ontology/ols.py — OlsClient over OLS4 REST (search + is-a ancestors),
  injectable HTTP getter (offline tests), retry-wrapped via sources._retry.
• ontology/cache.py — ResolutionCache: on-disk JSON, atomic writes,
  negative results cached so unresolvable strings aren't re-queried.
• ontology/layers.py — derive_molecular_layer(): EFO ancestor-label
  anchors, most-specific-first, no-anchor default UNKNOWN. Anchors are
  provisional (unvalidated against live EFO).
• ontology/resolver.py — OntologyResolver: cache → OLS exact-then-fuzzy →
  optional LLM fallback hook (default None, keeps ontology free of any
  agent/Azure import; PR 5 wires the extraction agent in).
• models/graph_schema.py — adds the MolecularLayer enum (consumed by PR 4b).
• normalize/cellxgene.py — grounds the organism string to NCBITaxon at runtime,
  replacing the hardcoded _ORGANISM_ONTOLOGY map. Tissue/disease/assay keep the
  IDs Census already ships. Unresolved organisms are skipped, not emitted
  ungrounded.

Decisions

• OLS4-only for now; text2term/Zooma deferred to GEO (PR 5) where messy
  characteristics_ch1 strings appear (resolves an ARCHITECTURE §7 open question).
• LLM fallback is a pluggable callable, not a dependency — dependency
  direction preserved.
• Anchors keyed by EFO label, not ID (honours "pin ontologies/anchors, not
  IDs"). A marked live-OLS integration test is the validation harness; PR 4b must
  tighten the labels first.

Verification

All four CI gates pass locally, hermetic (worktree has no .env, no network):

• ruff check . — clean
• ruff format --check . — 40 files formatted
• mypy src/parce — clean, 24 files, no new exemptions
• pytest -m "not integration" — 121 passed, 9 deselected

New offline unit suites: registry, cache, OLS (fake HTTP), layers, resolver
(fake client + real cache on tmp_path). Live-OLS checks are
@pytest.mark.integration (excluded from CI). No dependency changes.

🤖 Generated with Claude Code