reference-audit 0.1.0__py3-none-any.whl

reference_audit/matching/pool.py

@@ -0,0 +1,344 @@
+"""Candidate pooling: merge source records that are the same work into one candidate.
+
+Merging is IDENTIFIER-GROUNDED only — never title fuzz — so distinct works (distinct DOIs, T2) stay
+separate, while:
+  * records sharing an exact id (DOI / arXiv / ISBN13 / OpenAlex Work id) collapse, and
+  * a preprint and its published version merge when one record's id appears in the other's
+    `version_links` (the arXiv↔published edge — T1).
+The richer record (DOI-bearing, then higher citation count) represents the group; ids and version
+links are unioned, and both source records are retained on the merged candidate for the report.
+The ambiguous, identifier-disjoint zone (similar titles, no link) is left to M5's LLM tie-break.
+"""
+
+from __future__ import annotations
+
+from reference_audit.matching.features import is_repository_venue, title_prefix_trap, title_ratio
+from reference_audit.matching.names import authors_compatible
+from reference_audit.models import Identifiers, SourceRecord
+from reference_audit.parsing.identifiers import extract_arxiv_id, normalize_doi
+
+# Title threshold for the preprint↔published version merge (tight: titles are "usually correct").
+_VERSION_MERGE_TITLE = 0.93
+
+
+def _own_keys(rec: SourceRecord) -> set[str]:
+    keys: set[str] = set()
+    if rec.ids.doi:
+        keys.add(f"doi:{rec.ids.doi}")
+    if rec.ids.arxiv_id:
+        keys.add(f"arxiv:{rec.ids.arxiv_id.lower()}")
+    # Pool on the canonical ISBN only — deliberately NOT the whole `all_isbn13()` set. A book
+    # *chapter*'s scholarly record inherits its containing volume's ISBNs, so pooling on any shared
+    # ISBN would fuse sibling chapters (and the chapter with its parent book) into one record whose
+    # representative is picked by citation-richness, not title — which could bury the title-matching
+    # chapter. Same-work editions (print vs electronic) are still unified downstream by the
+    # SAME-OBJECT clustering at verdict time, which compares title+author, not ISBN membership alone.
+    if rec.ids.isbn13:
+        keys.add(f"isbn:{rec.ids.isbn13}")
+    if rec.openalex_work_id:
+        keys.add(f"oa:{rec.openalex_work_id}")
+    return keys
+
+
+def _link_to_keys(link: str) -> set[str]:
+    """Identifier keys referenced by a version-link string (URL or bare id)."""
+    keys: set[str] = set()
+    arxiv = extract_arxiv_id(None, None, fallback_text=link)
+    if arxiv:
+        keys.add(f"arxiv:{arxiv.lower()}")
+    doi = normalize_doi(link)
+    if doi and not doi.startswith("10.48550/arxiv"):  # the arXiv DOI is already captured as arxiv:
+        keys.add(f"doi:{doi}")
+    return keys
+
+
+def _link_keys(rec: SourceRecord) -> set[str]:
+    keys: set[str] = set()
+    for link in rec.version_links:
+        keys |= _link_to_keys(link)
+    return keys
+
+
+def _merge_ids(a: Identifiers, b: Identifiers) -> Identifiers:
+    return Identifiers(
+        doi=a.doi or b.doi,
+        arxiv_id=a.arxiv_id or b.arxiv_id,
+        isbn13=a.isbn13 or b.isbn13,
+        isbn13s=tuple(dict.fromkeys((*a.isbn13s, *b.isbn13s, *a.all_isbn13(), *b.all_isbn13()))),
+        pmid=a.pmid or b.pmid,
+        bibcode=a.bibcode or b.bibcode,
+        openalex=a.openalex or b.openalex,
+        url=a.url or b.url,
+    )
+
+
+def _richness(rec: SourceRecord) -> tuple[int, int, int]:
+    return (1 if rec.ids.doi else 0, rec.citation_count, len(rec.authors))
+
+
+def _underlying_sources(rec: SourceRecord) -> list[str]:
+    """Sources actually behind a record: the merge set if it is a pooled representative, else its own
+    source. Pooling must be idempotent — re-pooling an already-merged record (the enrichment pass)
+    must not lose provenance. (The prior two-phase pooling rebuilt representatives from earlier
+    representatives and ranked them by a single lossy `.source` label, so a preprint copy could
+    outrank a richer published record hidden inside another representative — the Flow-Lenia bug.)"""
+    merged_from = rec.raw.get("merged_from") if isinstance(rec.raw, dict) else None
+    return list(merged_from) if merged_from else [rec.source]
+
+
+# Bibliographic fields are filled on the merged representative from the most authoritative source
+# that carries them, independent of which record is the citation-richest. The publisher of record
+# (the DOI landing-page citation export) outranks the aggregators; Crossref/OpenAlex (the
+# registration-grade sources) outrank Semantic Scholar, whose venue strings are often truncated
+# ('Complexity' → 'Complex') and which omits volume/issue/pages. Records are ranked by their *best
+# underlying* source, so a pooled representative is ranked by the richest source inside it — not by
+# its lossy `.source` label. This realizes the SPEC's "compile all available information". DBLP
+# carries the conference of a CS paper that the aggregators often index only as its arXiv copy.
+_FIELD_SOURCE_PRIORITY: dict[str, tuple[str, ...]] = {
+    "venue": ("publisher", "crossref", "openalex", "dblp", "openlibrary"),
+    "volume": ("publisher", "crossref", "openalex"),
+    "issue": ("publisher", "crossref", "openalex"),
+    "pages": ("publisher", "crossref", "openalex"),
+    "publisher": ("publisher", "crossref", "openlibrary", "openalex"),
+}
+
+
+_YEAR_SOURCE_PRIORITY = ("publisher", "crossref", "openalex")
+
+# The author list scoring and adjudication see. The citation-richest record is often Semantic
+# Scholar's, whose lists can be defective (a name twice, one missing: Neural Collapse's 'Hung Tran'
+# for Stanley Osher), and the LLM rejected the real paper over it. DBLP and the registration-grade
+# sources keep complete, clean lists; arXiv's is author-supplied.
+_AUTHOR_SOURCE_PRIORITY = ("publisher", "dblp", "crossref", "arxiv", "openalex", "semantic_scholar")
+
+
+def _rank(rec: SourceRecord, priority: tuple[str, ...]) -> int:
+    """Priority rank of a record by its best (lowest-rank) underlying source."""
+    return min(
+        (priority.index(s) if s in priority else len(priority))
+        for s in _underlying_sources(rec)
+    )
+
+
+def _best_field(recs: list[SourceRecord], attr: str, priority: tuple[str, ...]) -> str:
+    """Most authoritative non-empty value for `attr` across a same-work group ('' if none has it).
+
+    For the venue, a preprint server or repository ('arXiv (Cornell University)', DBLP's 'CoRR') is
+    used only when no member names a journal or conference: OpenAlex's arXiv copy of an ICLR paper
+    must not outrank DBLP's 'ICLR'.
+    """
+    ranked = sorted(recs, key=lambda r: _rank(r, priority))
+    if attr == "venue":
+        ranked.sort(key=lambda r: is_repository_venue(r.venue))  # stable: rank kept within each
+    for r in ranked:
+        value = (getattr(r, attr) or "").strip()
+        if value:
+            return value
+    return ""
+
+
+def _best_authors(recs: list[SourceRecord]) -> list[str]:
+    """The author list of the most reliable source in a same-work group ([] if none has one)."""
+    for r in sorted(recs, key=lambda r: _rank(r, _AUTHOR_SOURCE_PRIORITY)):
+        if r.authors:
+            return list(r.authors)
+    return []
+
+
+def _best_abstract(recs: list[SourceRecord]) -> str:
+    """The fullest abstract across a same-work group (longest non-empty).
+
+    Abstracts come from OpenAlex / Semantic Scholar; the citation-richest representative may be a
+    source (e.g. Crossref) that carries none, so — like the other bibliographic fields — the abstract
+    is compiled across the group rather than taken only from the representative, so it survives onto
+    the matched artifact (and the cached verdict) for the citation-alignment check.
+    """
+    return max(((r.abstract or "").strip() for r in recs), key=len, default="")
+
+
+def _best_year(recs: list[SourceRecord]) -> int | None:
+    """Publication year from the registration-grade source (publisher/Crossref/OpenAlex) when
+    available.
+
+    Semantic Scholar often reports the online/preprint year (it gave 2018 for the 2019 Complex
+    Systems 'Lenia' DOI whose Crossref record is 2019), so its richer-citation record must not
+    override the DOI registrant's year.
+    """
+    for r in sorted(recs, key=lambda r: _rank(r, _YEAR_SOURCE_PRIORITY)):
+        if r.year:
+            return r.year
+    return None
+
+
+def pool_candidates(records: list[SourceRecord]) -> list[SourceRecord]:
+    """Merge records that describe the same work into one representative candidate each.
+
+    A single union-find over all records with two kinds of (transitively closed) edge:
+      * identifier edge — both records carry ids and they overlap, or one side's version link
+        bridges the other's id (shared DOI/arXiv/ISBN13/OpenAlex id; the arXiv↔published edge).
+        Grounded in identifiers, never title fuzz.
+      * version edge — `_same_work_version`: a preprint and its published version, or two editions of
+        one book, agreeing on title+authors. This is the *only* place title similarity is allowed,
+        and only to UNITE versions of one work — two distinct published DOIs are still held apart by
+        the V1 veto inside `_same_work_version`.
+
+    Transitive closure (order-independent union-find) is essential and is why this replaced the
+    earlier greedy first-match grouping: a Semantic Scholar record that carries BOTH the arXiv id and
+    the published DOI must fuse the preprint group and the published group into one candidate. When
+    they stayed split, canonical fields were sourced from the preprint copy (the Flow-Lenia bug).
+    """
+    n = len(records)
+    if n <= 1:
+        return list(records)
+
+    own = [_own_keys(r) for r in records]
+    links = [_link_keys(r) for r in records]
+    parent = list(range(n))
+    # The records in each cluster, keyed by its root.
+    cluster = {i: [r] for i, r in enumerate(records)}
+
+    def find(i: int) -> int:
+        while parent[i] != i:
+            parent[i] = parent[parent[i]]
+            i = parent[i]
+        return i
+
+    def union(i: int, j: int) -> None:
+        ri, rj = find(i), find(j)
+        parent[rj] = ri
+        cluster[ri].extend(cluster.pop(rj))
+
+    def authors_agree_across(i: int, j: int) -> bool:
+        """A version relation joins two clusters only if every record of one has authors compatible
+        with every record of the other. A conference paper and its journal extension (CrossFormer at
+        ICLR, CrossFormer++ in TPAMI) are two works; fusing them hides the record that matches the
+        entry behind the other one's metadata. Checking each pair, not each edge, keeps a record that
+        fits both (a one-author supplementary-material DOI) from bridging them. Version *links* are
+        held to this too: they come from the aggregators' own work-merging, which can be wrong."""
+        return all(
+            authors_compatible(a.authors, b.authors)
+            for a in cluster[find(i)]
+            for b in cluster[find(j)]
+        )
+
+    for i in range(n):
+        for j in range(i + 1, n):
+            if find(i) == find(j):
+                continue
+            shared_id = bool(own[i] & own[j])  # the same DOI/arXiv/ISBN/OpenAlex id: one record
+            linked = bool(own[i] and own[j] and ((own[i] & links[j]) or (links[i] & own[j])))
+            if shared_id or (
+                (linked or _same_work_version(records[i], records[j]))
+                and authors_agree_across(i, j)
+            ):
+                union(i, j)
+
+    clusters: dict[int, list[SourceRecord]] = {}
+    for idx in range(n):
+        clusters.setdefault(find(idx), []).append(records[idx])
+    return [_representative(g) if len(g) > 1 else g[0] for g in clusters.values()]
+
+
+def _as_member(rec: SourceRecord) -> SourceRecord:
+    return rec.model_copy(update={"raw": {}, "abstract": "", "members": []}, deep=True)
+
+
+def _members(rec: SourceRecord) -> list[SourceRecord]:
+    """The source records behind `rec`: its members if it is pooled, else itself."""
+    return list(rec.members) if rec.members else [_as_member(rec)]
+
+
+def _representative(recs: list[SourceRecord]) -> SourceRecord:
+    best = max(recs, key=_richness)
+    merged = best.model_copy(deep=True)
+    for r in recs:
+        merged.ids = _merge_ids(merged.ids, r.ids)
+        for link in r.version_links:
+            if link not in merged.version_links:
+                merged.version_links.append(link)
+        if r.openalex_work_id and not merged.openalex_work_id:
+            merged.openalex_work_id = r.openalex_work_id
+        merged.is_preprint = merged.is_preprint and r.is_preprint
+    # Compile the best bibliographic metadata across the group (not just the richest record's).
+    for attr, priority in _FIELD_SOURCE_PRIORITY.items():
+        value = _best_field(recs, attr, priority)
+        if value:
+            setattr(merged, attr, value)
+    best_year = _best_year(recs)
+    if best_year is not None:
+        merged.year = best_year
+    best_authors = _best_authors(recs)
+    if best_authors:
+        merged.authors = best_authors
+    best_abstract = _best_abstract(recs)
+    if best_abstract:
+        merged.abstract = best_abstract
+    merged.raw = {
+        "merged_from": sorted({s for r in recs for s in _underlying_sources(r)}),
+        # `ids.doi` keeps one DOI (the richest record's, often an arXiv DataCite DOI); every member's
+        # DOI is kept here so a cited published DOI can still be recognised as this work's.
+        "merged_dois": sorted({d for r in recs for d in _member_dois(r)}),
+    }
+    merged.members = _distinct([m for r in recs for m in _members(r)])
+    return merged
+
+
+def _distinct(members: list[SourceRecord]) -> list[SourceRecord]:
+    """Members without repeats: enrichment re-pools a work with the same sources' by-id records."""
+    seen: set[tuple] = set()
+    out = []
+    for m in members:
+        key = (m.source, m.source_native_id) if m.source_native_id else (
+            m.source, m.ids.doi, m.ids.arxiv_id, m.title.casefold(), m.year
+        )
+        if key not in seen:
+            seen.add(key)
+            out.append(m)
+    return out
+
+
+def _member_dois(rec: SourceRecord) -> list[str]:
+    """The record's own DOI plus those of the records it already merged (pooling is re-run)."""
+    merged = rec.raw.get("merged_dois") if isinstance(rec.raw, dict) else None
+    return [*(merged or []), *([rec.ids.doi] if rec.ids.doi else [])]
+
+
+def _is_preprintish(rec: SourceRecord) -> bool:
+    return rec.is_preprint or bool(rec.ids.doi and rec.ids.doi.startswith("10.48550/arxiv"))
+
+
+def _published_doi(rec: SourceRecord) -> str | None:
+    doi = rec.ids.doi
+    return doi if doi and not doi.startswith("10.48550/arxiv") else None
+
+
+def _title_authors_agree(a: SourceRecord, b: SourceRecord) -> bool:
+    if title_ratio(a.title, b.title) < _VERSION_MERGE_TITLE:
+        return False
+    if title_prefix_trap(a.title, b.title, tail_threshold=0.34):
+        return False  # V3: shared prefix, divergent tail (bagrov vs kravchenko)
+    # Person-level, not a fuzzy surname average: short surnames (Wang, Chen, Lin, He, Liu) let
+    # CrossFormer's authors "overlap" CrossFormer++'s at 0.85 with two of seven people different.
+    # A title alone never makes a version: both records must name their authors.
+    return bool(a.authors and b.authors) and authors_compatible(a.authors, b.authors)
+
+
+def _same_work_version(a: SourceRecord, b: SourceRecord) -> bool:
+    """Two records describe one work when titles+authors agree AND either:
+
+    R1 (preprint↔published): exactly one side is a preprint — a version relationship that overrides
+       the two-distinct-DOIs signal (the published DOI and the arXiv preprint DOI legitimately
+       differ); or
+    R2 (same edition/printing): the two do NOT both carry distinct *published* DOIs (one or both
+       lack one) — different editions/reprints of one book, or a metadata-only duplicate.
+
+    Two distinct *published* DOIs with neither side a preprint is left UNMERGED (the design's V1
+    veto): it is a genuine "same surface" case for M5's LLM tie-break (e.g. duplicate DOIs for one
+    paper), not a formal merge.
+    """
+    if not _title_authors_agree(a, b):
+        return False
+    if _is_preprintish(a) != _is_preprintish(b):  # R1
+        return True
+    pa, pb = _published_doi(a), _published_doi(b)
+    return not (pa and pb and pa != pb)  # R2: merge unless two distinct published DOIs

reference_audit/matching/sameobject.py

@@ -0,0 +1,150 @@
+"""SAME-OBJECT clustering over an entry's ACCEPTED candidates → matched artifacts.
+
+`pool.py` already merged the identifier-grounded same-work cases (shared id, version edge, preprint
+pair, same edition). What remains for an entry with ≥2 accepted candidates is the genuinely
+ambiguous zone: two records with near-identical title+authors but two DISTINCT published DOIs (the
+design's V1 veto holds them apart formally — e.g. one paper registered under two DOIs). Those, and
+only those, escalate to the `SAME_WORK` LLM tie-break. The distinct-work vetoes V2 (disjoint pages),
+V3 (title-prefix trap) and V4 (author-set distinct) are decisive and never reach the LLM.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from reference_audit.cache.store import AuditCache, prompt_hash
+from reference_audit.config import AuditConfig
+from reference_audit.llm.client import LLMClient, LLMError
+from reference_audit.llm.prompts import SAME_WORK_SYSTEM, same_work_user
+from reference_audit.matching.features import (
+    author_set_jaccard,
+    id_agreement,
+    pages_conflict_records,
+    title_prefix_trap,
+    title_ratio,
+)
+from reference_audit.matching.names import author_overlap, author_subset
+from reference_audit.models import (
+    CandidateAssessment,
+    Identifiers,
+    MatchedArtifact,
+    SameWorkResult,
+    SourceRecord,
+)
+
+Relation = Literal["same", "distinct", "ambiguous"]
+
+_SAME_TITLE = 0.90
+_SAME_AUTHOR = 0.7
+
+
+def formal_relation(a: SourceRecord, b: SourceRecord, config: AuditConfig) -> Relation:
+    """Formal same-object relation between two accepted records (no LLM)."""
+    if id_agreement(a.ids, b.ids) == "match":
+        return "same"  # shared exact identifier (M1/M3)
+    # Distinct-work vetoes (decisive).
+    if pages_conflict_records(a, b):
+        return "distinct"  # V2
+    if title_prefix_trap(a.title, b.title, tail_threshold=config.prefix_trap_tail_jaccard):
+        return "distinct"  # V3
+    if (
+        author_set_jaccard(a.authors, b.authors) < config.author_set_distinct_jaccard
+        and not author_subset(a.authors, b.authors)
+    ):
+        return "distinct"  # V4
+    # Near-identical title + authors but no shared id ⇒ ambiguous (→ SAME_WORK LLM).
+    titles_agree = title_ratio(a.title, b.title) >= _SAME_TITLE
+    authors_agree = author_overlap(a.authors, b.authors) >= _SAME_AUTHOR or author_subset(
+        a.authors, b.authors
+    )
+    if titles_agree and authors_agree:
+        return "ambiguous"
+    return "distinct"
+
+
+def _merge_ids(a: Identifiers, b: Identifiers) -> Identifiers:
+    return Identifiers(
+        doi=a.doi or b.doi,
+        arxiv_id=a.arxiv_id or b.arxiv_id,
+        isbn13=a.isbn13 or b.isbn13,
+        isbn13s=tuple(dict.fromkeys((*a.isbn13s, *b.isbn13s, *a.all_isbn13(), *b.all_isbn13()))),
+        pmid=a.pmid or b.pmid,
+        bibcode=a.bibcode or b.bibcode,
+        openalex=a.openalex or b.openalex,
+        url=a.url or b.url,
+    )
+
+
+def _artifact_from_records(records: list[SourceRecord]) -> MatchedArtifact:
+    # Prefer a published (non-preprint), DOI-bearing, highly-cited record as the canonical best.
+    best = max(
+        records,
+        key=lambda r: (0 if r.is_preprint else 1, 1 if r.ids.doi else 0, r.citation_count),
+    )
+    merged = Identifiers()
+    for r in records:
+        merged = _merge_ids(merged, r.ids)
+    return MatchedArtifact(
+        records=list(records), merged_ids=merged, versions=list(records), best_record=best
+    )
+
+
+async def _same_work_llm(
+    a: SourceRecord, b: SourceRecord, llm: LLMClient, cache: AuditCache | None
+) -> tuple[SameWorkResult | None, bool]:
+    user = same_work_user(a, b)
+    p_hash = prompt_hash(SAME_WORK_SYSTEM + "\n" + user)
+    if cache is not None:
+        cached = cache.get_llm_decision(p_hash, "same_work")
+        if cached is not None:
+            return SameWorkResult.model_validate_json(cached), False
+    try:
+        result = await llm.structured(SAME_WORK_SYSTEM, user, SameWorkResult, "same_work")
+    except LLMError:
+        return None, True
+    if cache is not None:
+        cache.put_llm_decision(p_hash, "same_work", result.model_dump_json())
+    return result, False
+
+
+async def cluster_accepted(
+    accepted: list[CandidateAssessment],
+    config: AuditConfig,
+    llm: LLMClient | None,
+    cache: AuditCache | None,
+) -> tuple[list[MatchedArtifact], bool]:
+    """Cluster accepted candidates into artifacts (union-find). Returns (artifacts, errored)."""
+    records = [c.record for c in accepted]
+    n = len(records)
+    if n <= 1:
+        return ([_artifact_from_records(records)] if records else []), False
+
+    parent = list(range(n))
+
+    def find(i: int) -> int:
+        while parent[i] != i:
+            parent[i] = parent[parent[i]]
+            i = parent[i]
+        return i
+
+    def union(i: int, j: int) -> None:
+        parent[find(j)] = find(i)
+
+    errored = False
+    for i in range(n):
+        for j in range(i + 1, n):
+            if find(i) == find(j):
+                continue
+            rel = formal_relation(records[i], records[j], config)
+            if rel == "same":
+                union(i, j)
+            elif rel == "ambiguous" and llm is not None:
+                result, err = await _same_work_llm(records[i], records[j], llm, cache)
+                errored = errored or err
+                if result and result.relation in ("same_artifact", "versions_of_same_work"):
+                    union(i, j)
+
+    clusters: dict[int, list[SourceRecord]] = {}
+    for idx, rec in enumerate(records):
+        clusters.setdefault(find(idx), []).append(rec)
+    return [_artifact_from_records(group) for group in clusters.values()], errored

reference_audit/matching/scoring.py

@@ -0,0 +1,75 @@
+"""Bucketing: auto_accept / auto_reject / adjudicate — the funnel before any LLM call.
+
+The 100%-match short-circuit (README "unless a returned record is a 100% match, use an LLM")
+reads the feature VECTOR, not the scalar: an id match alone is not enough (a hallucinated DOI that
+resolves must still pass title+author), and a prefix-trap/pages-conflict forces adjudication even
+at high composite (stops T2 from auto-accepting).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from reference_audit.config import AuditConfig
+from reference_audit.models import FeatureVector
+
+Bucket = Literal["auto_accept", "auto_reject", "adjudicate"]
+
+
+def bucket(features: FeatureVector, config: AuditConfig, *, entry_has_id: bool = True) -> Bucket:
+    """Bucket one (entry, candidate) by its feature vector.
+
+    `entry_has_id` enables the strict backfill path: when the bib entry carries no *strong* anchor
+    (DOI / ISBN / arXiv / OpenAlex / Google Books — a bare URL does not count, see
+    `Identifiers.has_strong_id`), a near-exact title + strong authors (and no distinct-work veto) is
+    accepted so the matched DOI can be backfilled. The threshold is stricter than the id-based path
+    because there is no identifier to anchor the match.
+    """
+    # A low author-set overlap forces adjudication ONLY when neither set is a subset of the other:
+    # a subset is consistent with an abbreviated "et al." list (same work), not a distinct work.
+    author_set_distinct = (
+        features.author_set_jaccard < config.author_set_distinct_jaccard
+        and not features.author_subset
+    )
+    authors_ok = features.author_overlap >= config.author_accept or features.author_subset
+
+    # A disjoint page range in the same venue normally signals a DISTINCT work (laughlin T2c: two
+    # different-titled papers on consecutive pages). But when the title is a near-exact match AND the
+    # authors agree, two different works is not a credible explanation — the likely one is a wrong
+    # `pages` field in the citation (soros2014: cited 306--313 vs the identical paper's canonical
+    # 793--800). Treat that as a field error to be REPORTED by the field check downstream, not as
+    # grounds to call a real, title-and-author-identical paper a possible hallucination. (prefix_trap
+    # stays load-bearing: it fires on divergent title TAILS, i.e. when the titles are NOT near-exact.)
+    title_authors_lock = features.title_ratio >= config.title_backfill and authors_ok
+    pages_conflict_distinct = features.pages_conflict and not title_authors_lock
+    forced_adjudicate = (
+        features.title_prefix_trap or pages_conflict_distinct or author_set_distinct
+    )
+
+    # Path A — entry has an identifier that the candidate matches (authoritative; README: IDs
+    # uniquely identify). Accept even if the DB holds a subset of authors (wilson1974/Kogut); the
+    # title gate still rejects a hallucinated DOI resolving to a different paper (T4-by-bad-id).
+    if (
+        features.id_agreement == "match"
+        and features.title_ratio >= config.title_accept
+        and authors_ok
+        and not forced_adjudicate
+    ):
+        return "auto_accept"
+
+    # Path B — entry has NO identifier; accept a near-exact title + strong authors to backfill the
+    # candidate's DOI/ISBN. Stricter title floor; all distinct-work vetoes still apply (keeps T2a's
+    # bagrov/kravchenko prefix-trap from auto-accepting).
+    if (
+        not entry_has_id
+        and features.id_agreement != "conflict"
+        and features.title_ratio >= config.title_backfill
+        and features.author_overlap >= config.author_accept
+        and not forced_adjudicate
+    ):
+        return "auto_accept"
+
+    if features.id_agreement != "match" and features.composite < config.composite_reject:
+        return "auto_reject"
+
+    return "adjudicate"

reference_audit/matching/verdict.py

@@ -0,0 +1,56 @@
+"""Turn scored + clustered candidates into a 3-way Verdict (README 5.1/5.2/5.3).
+
+`artifacts` is the SAME-OBJECT clustering of the *accepted* candidates (see `sameobject.py`): each
+element is one distinct real-world work. The verdict counts them.
+"""
+
+from __future__ import annotations
+
+from reference_audit.models import CandidateAssessment, MatchedArtifact, Verdict
+
+
+# @cpt-dod:cpt-referenceaudit-dod-identification-three-way-verdict:p1
+# @cpt-dod:cpt-referenceaudit-dod-identification-hallucination-screen:p1
+def build_verdict(
+    assessments: list[CandidateAssessment],
+    artifacts: list[MatchedArtifact],
+    *,
+    errored: bool,
+) -> Verdict | None:
+    if artifacts:
+        if len(artifacts) == 1:
+            best = artifacts[0].best_record
+            src = best.source if best else ""
+            n_versions = len(artifacts[0].versions)
+            extra = f" ({n_versions} versions)" if n_versions > 1 else ""
+            return Verdict(
+                kind="exactly_one",
+                artifacts=artifacts,
+                confidence="high",
+                rationale=f"Matched a single work via {src}{extra}.",
+            )
+        return Verdict(
+            kind="multiple",
+            artifacts=artifacts,
+            confidence="medium",
+            rationale=f"Matched {len(artifacts)} distinct works.",
+        )
+
+    if errored:
+        return None  # transient failure — leave unresolved, retry next run (error ≠ not-found)
+
+    if not assessments:
+        return Verdict(
+            kind="none",
+            confidence="high",
+            rationale="No database record found for this reference (possible hallucination).",
+        )
+
+    if all(a.bucket == "auto_reject" for a in assessments):
+        return Verdict(
+            kind="none",
+            confidence="medium",
+            rationale="Database records were found but none matched the entry's title/authors.",
+        )
+
+    return None  # adjudicate bucket remaining — deferred to the LLM funnel