citator: consume the corpus's curated citation graph; miner becomes differential

↗ view on GitHub · Eli Ziff · 2026-07-30 · c9d21066

The A2AJ case rows carry a curated citation graph (cases_cited_en/_fr,
cases_citing_en/_fr - lists of neutral citations; 64.2% of the 225,017
case rows have a non-empty cited list, 1.02M cited + 935K citing edges,
probed 2026-07-30). Until now every consumer dropped these columns at
ingest and re-mined citations by regex - the survey's finding #1.

- import_a2aj_bulk.py: the five graph columns (cases_cited_*,
  cases_citing_*, citing_cases_count) join the document schema as JSON
  text; schema_version 2. The reader SELECTs document.* by name, so
  existing databases keep working.
- build_citator_graph.py: curated lists land verbatim in provider_edge
  (case_id, direction, citation, citation_key) in the shared key space,
  plus case_key mapping each case to its own citation keys. The regex
  miner is demoted to what only it can supply - paragraph anchors,
  offsets, pinpoints, excerpts - and is measured against the provider
  lists per doc (provider_keys_mined_confirmed / provider_keys_unmined /
  mined_keys_unlisted in meta), never reconciled.
- caselawCitator.ts: NoteUpResult gains provider {citingInCorpus,
  citingReported}; citingReported reaches the decision's citing list
  through ANY of its own keys (French twin included). graphStats gains
  provider_edges. Both are null on a schema-1 graph.
- citatorTools.ts: provider surface exposed to the model.

Real-data smoke (1,000 SCC cases, 16.6s): 327 curated cited edges over
35 docs, ALL 327 confirmed by the miner (0 provider-only), 761
mined-only keys the lists omit; 7,225 citing edges. The demonstrating
query: noteUp("2011 SCC 62") has 0 mined citing cases in the slice but
50 provider-reported citing citations (lower courts outside the slice).

Suites: caselawCitator (extended fixture: curated citing list, verbatim
provider_edge rows, case_key closure, differential counters),
a2ajLocalBulk; tsc clean.

Integration plan item 2 (task #28).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012AgUm5EcRKbT3duVFMbrQD
Repository eliziff/Beaver
Author Eli Ziff <eliasziff@gmail.com>
Authored
Parents c824f2b4
Stats 5 files changed , +241 , -7
Part of Citator: note-up graph and attested case characterizations

Capture this commit into my fork

Download a Markdown prompt that tells Claude how to port this exact commit into your working tree. Run it via claude -p < capture-commit-c9d21066.md from inside the repo you want the change in.

⬇ Download capture-commit-c9d21066.md