From ce75bc02e59dcc3b25ee50c21b18c700bdd100d6 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Mon, 15 Jun 2026 12:10:46 +0200 Subject: [PATCH] =?UTF-8?q?docs(adr):=20audit=20addendum=20to=20ADR-F15=20?= =?UTF-8?q?=E2=80=94=20ID=20mismatch=20resolved=20(audit=20D-1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ADR's GO rested on a live-corpus spike (478 dangling, Bobenko/Springborn rank 7, 5.7% spread) measured before the resolution + canonicalisation landed. Add an audit addendum: mark the 'Known Limitation: ID-Format Mismatch' as resolved (C-1 shared resolver + C-7 canonical ids), and flag the Spike Result numbers as pending re-measurement after the C-7 re-ingest. History preserved. Co-Authored-By: Claude Fable 5 --- docs/adr/ADR-F15-literature-graph.md | 36 ++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/adr/ADR-F15-literature-graph.md b/docs/adr/ADR-F15-literature-graph.md index 8a25bff..4733885 100644 --- a/docs/adr/ADR-F15-literature-graph.md +++ b/docs/adr/ADR-F15-literature-graph.md @@ -1,8 +1,10 @@ # ADR-F15 — Literature Graph / Citation PageRank -**Status:** IMPL (GO after live-corpus spike 2026-06-15) +**Status:** IMPL — GO after live-corpus spike 2026-06-15. See **Audit Update +(2026-06-15)** at the end: the ID-format mismatch is now resolved in code +(audit C-1, C-7) and the Spike Result numbers below predate that resolution. **Owners:** F-15 Worker (Sonnet) -**Last updated:** 2026-06-15 +**Last updated:** 2026-06-15 (audit addendum) --- @@ -138,6 +140,12 @@ If the `citations` table is empty: graph has 0 nodes; `graph report` prints ## Known Limitation: ID-Format Mismatch +> **RESOLVED (audit 2026-06-15) — see Audit Update below.** This no longer holds: +> `build_citation_graph` resolves OpenAlex `cited_id`s to the canonical +> `papers.id` via the shared `RESOLVED_CITATIONS_SQL` (C-1) and ingest stores +> canonical ids (C-7), so inter-KB citations *are* now edges. Original text kept +> for the record. + `cited_id` uses OpenAlex IDs; `papers.id` uses DOIs. Cross-citations between ingested papers are therefore not represented as graph edges. This is a D-05-class issue (same root cause as the `citing_id`/`openalex_id` @@ -155,3 +163,27 @@ small while the corpus is < 100 papers. - R-44: `codex graph report [--top-n N] [--json]` ✓ - R-45: graceful degradation < 5 nodes: uniform scores, warning ✓ - R-46: **this document** — GO; Bobenko+Springborn 2007 at rank 7 validates hub detection; score flatness expected at corpus size 29; increase to > 100 papers for stronger PageRank differentiation + +--- + +## Audit Update (2026-06-15) + +A post-hoc audit of the shipped F-15 code found that the live-corpus spike above +was measured on a graph the current code no longer produces: + +- **ID-format mismatch resolved.** `build_citation_graph` resolves OpenAlex + `cited_id`s to the canonical `papers.id` through the shared + `RESOLVED_CITATIONS_SQL`, now also used by `codex.discover` so the two cannot + diverge (audit C-1). Ingest stores the caller's canonical id as `papers.id` + instead of OpenAlex's URL-form doi (audit C-7). Inter-KB citations are + therefore represented as edges — the "Known Limitation" above is obsolete. +- **Spike numbers are stale.** The 478 dangling nodes, the rank-7 + Bobenko/Springborn result, and the 5.7 % score spread were measured *before* + the resolution + canonicalisation. They must be **re-measured after the corpus + is re-ingested** onto canonical ids (the chosen C-7 migration); until then the + GO rests on a superseded topology. + +**Action (pending):** after re-ingesting via `ingest_all.sh`, re-run +`codex graph report`, refresh the Spike Result table, and confirm the +foundational hubs (Pinkall/Polthier, Yamabe, Schoen, Bobenko/Springborn) still +surface.