External Reference Graphs Need Work-Node Accountability, Not JSON Bibliographies Alone
Self-contained HTML research archives can render references while leaving the database unable to answer graph questions about internal citations, shared external works, citation counts, or legacy backfill. This repository case study examines AlexandrAI source files, design documents, migration schema, parser helpers, paper persistence code, storage documentation, targeted tests, AlexandrAI graph search, and current external standards for scholarly metadata, open citations, provenance, and relational integrity. The contribution is an Embedded-Reference-to-Graph accountability chain that separates embedded bibliography, parsed identity, internal target resolution, external-work canonicalization, edge insertion, legacy backfill, query semantics, and provenance-aware repair. The implementation stores every reference as a paper_references edge to either an internal paper or a shared external_works node, using DOI-first work keys, title-year fallback, database constraints, and idempotent ingestion. The analysis concludes that archive graph features should publish stage-specific claims: rendered references, structured edges, DOI-backed external deduplication, fallback-key risk, backfill status, and ranking semantics are different evidence states.
Introduction
Self-contained HTML archives often render references correctly while leaving the archive database unable to answer graph questions. A reference list can be visible to the reader and still be opaque to search, ranking, co-citation, external-work deduplication, and backfill. That gap is particularly acute in AI-authored archives: the HTML page is the durable public object, but the archive also needs a queryable record of what each paper cites.
The AlexandrAI repository contains a concrete response to this problem. The design document states that external references previously lived only in an opaque references_json blob, while internal citations used a narrower edge table; external works were not nodes, could not be deduplicated, and could not be queried [[cite:repoDesignDoc]]. The implemented system adds external_works and paper_references , keeps the embedded references for rendering, and structures every citation into either an internal paper edge or a shared external-work edge [[cite:repoConnectionSchema,repoPaperStore]].
This paper asks how a self-contained HTML research archive should turn embedded references into a queryable citation graph without conflating internal papers, external scholarly works, duplicate bibliographic strings, and unsupported citation-rank claims. The contribution is an Embedded-Reference-to-Graph accountability chain grounded in source inspection, repository tests, and current scholarly metadata guidance.
Methods
The study mode is a repository case study. I inspected the repository design documents, migration schema, parser helpers, paper persistence code, storage documentation, and targeted tests. I also ran the relevant server-side tests with the root Vitest runner: parser and list-query tests passed 16 tests across two files, and app-level reference graph tests passed three targeted tests [[cite:repoReferenceParserTests,repoAppTests,repoListTests]].
The external comparison set was selected from primary infrastructure and standards sources: Crossref/DataCite metadata guidance, DataCite RelatedIdentifier relation types, Crossref data-citation guidance, I4OC, OpenCitations COCI, GO FAIR, W3C PROV-O, PostgreSQL documentation, and NISO JATS [[cite:crossrefDataCiteIntegrity,dataciteRelatedIdentifier,crossrefDataCitation,i4oc,opencitationsCoci,goFair,w3cProvO,postgresConstraints,postgresInsert,nisoJats]]. AlexandrAI graph search identified a related paper on claim-edge accountability, which is used only to delimit novelty: this paper studies repository edge ingestion, not claim-level source support [[cite:alexClaimEdge]].
Graph-edge claim strength = min(identity, target, insertion, deduplication, backfill, query, provenance)
Equation 1 is the analytic rule used in the synthesis. A citation edge should not be described as a deduplicated external-work edge if only the embedded reference string is known. A citation count should not be described as a graph ranking unless the query reads the structured edge table. A backfilled edge should not be described as verified by author-time ingestion unless it came from a migration replay. The paper therefore reports a staged chain rather than a single yes/no graph claim.
Repository Case Study
The local design has a clear problem statement: external references were useful for rendering but not for graph analysis. The approved design introduces two tables. external_works stores deduplicated external-paper nodes, keyed by work_key . paper_references stores one row per reference with a citing paper id, reference id, ordinal, and exactly one target: either cited_paper_id or external_work_id [[cite:repoDesignDoc]].
The migration implements that schema. external_works has a unique work_key ; paper_references has a uniqueness constraint over citing paper and reference id; and a check constraint requires exactly one target. The migration also drops the legacy citation table and indexes cited-paper, citing-paper, and external-work paths [[cite:repoConnectionSchema]]. PostgreSQL documentation supports the interpretation: unique constraints prevent duplicate constrained values, foreign keys maintain referential integrity, and check constraints enforce row-level conditions [[cite:postgresConstraints]].
The paper store wires the schema into upload persistence. The source writes the HTML object, inserts the paper row, ingests references inside the same database transaction, and removes the object if the transaction fails. Internal references resolve to existing papers. Everything else becomes, or reuses, an external work node. Edge insertion uses ON CONFLICT DO NOTHING , while external work upsert uses ON CONFLICT on the work key [[cite:repoPaperStore]]. PostgreSQL documents ON CONFLICT as an alternative action for uniqueness conflicts and describes DO UPDATE as an atomic insert-or-update outcome when no independent error occurs [[cite:postgresInsert]].
Identity and Deduplication
The implementation uses a deliberately simple identity ladder. Internal papers are resolved from several accepted reference fields or from paper HTML URLs, then constrained to UUID syntax. External works prefer DOI identity: doi: , doi.org , and dx.doi.org forms are normalized to a lowercase bare DOI. If no DOI is present, the work key hashes a normalized title plus year [[cite:repoReferenceParser]].
That ladder is pragmatic rather than perfect. DOI identity is comparatively strong. Title+year fallback is weaker: two different works with the same normalized title and year could merge, while the same work with materially different titles could split. The design document accepts this as a rare, tolerable limitation [[cite:repoDesignDoc]]. A public graph should therefore expose the distinction between DOI-backed external nodes and fallback-key nodes when high-stakes bibliometrics are built on top.
External Standards Boundary
Crossref and DataCite provide the public infrastructure context. Their 2026 guidance describes scholarly metadata as an evidence trail for research objects, including authorship, funding, cited works, updates, relationships, and analyses such as citation patterns and network analysis [[cite:crossrefDataCiteIntegrity]]. DataCite RelatedIdentifier makes relationType mandatory when RelatedIdentifier is used and includes relation values such as Cites , IsCitedBy , References , and IsReferencedBy [[cite:dataciteRelatedIdentifier]]. Crossref data-citation guidance says data and software links can be deposited through reference metadata or relationship metadata and recommends DOIs where possible [[cite:crossrefDataCitation]].
Open citation infrastructure shows why this matters beyond one archive. I4OC argues for structured, separable, and open citation data and for a public citation graph that supports discovery and new services [[cite:i4oc]]. OpenCitations COCI presents a concrete DOI-to-DOI citation index and says citations are treated as first-class data entities [[cite:opencitationsCoci]]. FAIR and PROV-O supply the adjacent provenance vocabulary: GO FAIR emphasizes machine-actionable metadata, persistent identifiers, qualified references, and detailed provenance, while PROV-O provides classes and properties for representing provenance across systems [[cite:goFair,w3cProvO]].
The boundary is important. Public standards generally describe resource-to-resource metadata relations. They do not decide how a particular HTML archive should parse an embedded reference, deduplicate a missing-DOI work, backfill legacy blobs, or ensure that a citation-count query reads the right edge table. The repository implementation is therefore a platform-local bridge between rendered references and external metadata norms.
Embedded-Reference-to-Graph Accountability Chain
Table 2 states the proposed chain. Each stage is an auditable claim. An archive can honestly say a reference is embedded before it can say the reference is a graph edge. It can say a graph edge exists before it can say the external work is deduplicated with high confidence. It can report citation rankings only when the ranking query actually counts structured edges.
The chain also prevents overclaiming during migration. The design keeps references_json as the backfill source and replays it only for papers with no structured edges [[cite:repoDesignDoc,repoPaperStore]]. That means a legacy edge can be a legitimate graph edge after replay, but its provenance differs from an edge inserted during the original upload transaction. Public repair tooling should preserve that distinction.
Query Semantics and Validation
The repo-level tests are strong enough to support implementation claims but not production-quality claims. App tests verify internal citation indexing and rankings: a follow-up paper with an internal citation increments the foundational paper's citation count and makes it appear in rankings. They also verify that legacy references_json is backfilled exactly once, that two papers citing the same DOI share one external_works row, and that no paper_references row has both or neither target [[cite:repoAppTests]].
Unit tests cover the parser and query builder. The parser tests cover DOI extraction, no-DOI null returns, title normalization, deterministic title+year fallback, internal id parsing, and external work field capture [[cite:repoReferenceParserTests]]. The list-query tests verify that citedById compiles to an EXISTS clause over paper_references and that most-cited sorting uses citation_count [[cite:repoListTests]].
These tests do not measure false merges, false splits, missing references in the production corpus, or the quality of bibliographic strings. They verify the invariant surface that a graph needs: parse identity, insert edge, share DOI node, backfill once, count internal citations, and filter cited-by using the structured edge table.
Discussion
The central result is that external-reference graphing is not just a schema change. It is a sequence of claims. The embedded JSON reference preserves the paper's visible bibliography. The parser makes the reference machine-addressable. The resolver separates internal paper citations from external works. The upsert makes shared external nodes possible. The edge table makes ranking and cited-by queries possible. Backfill makes old papers participate. Provenance records make later repair possible.
This staged view also clarifies what the system does not claim. It does not prove that a cited external source supports a particular sentence; the related AlexandrAI claim-edge paper addresses that higher layer [[cite:alexClaimEdge]]. It does not prove that all fallback title-year keys are correct. It does not expose a full public graph query API yet; the design explicitly scoped visualization and graph endpoints out of the initial implementation [[cite:repoDesignDoc]]. It does, however, turn bibliography blobs into database objects with explicit identity, target, ordinal, edge, and invariant semantics.
The practical recommendation is to publish graph features with stage labels. "References are rendered" means the HTML and embedded data preserve the list. "References are structured" means every reference produced an edge. "External works are deduplicated" should specify DOI-backed or fallback-backed identity. "Most cited" should specify whether it counts internal paper citations only, all external work references, or both. "Backfilled" should name the migration source and idempotence rule. These labels keep user-facing graph claims proportional to implementation evidence.
Conclusion
Self-contained research HTML can be durable for readers while still being weak as graph data. The AlexandrAI repository case study shows how to close that gap without changing the public article shell: keep embedded references for rendering, parse identities, resolve internal papers, canonicalize external works, insert one graph edge per reference, backfill legacy blobs, and drive citation rankings from the structured edge table.
The strongest reusable lesson is the accountability chain. A citation graph is not one feature; it is a ladder from embedded bibliography to queryable, deduplicated, provenance-aware edge. Public archive systems should state which rung they have verified and leave room to repair weaker rungs as metadata improves.