reference-audit 0.1.0__py3-none-any.whl

reference_audit/fieldcheck.py

@@ -0,0 +1,599 @@
+"""Step 3 (correctness): are the .bib *fields* right?
+
+Once step 1 has matched an entry to exactly one real artifact (by a strong identifier), the work's
+identity is settled — but individual fields can still be wrong: a dropped word in a journal name, a
+split typo ('Un iversity'), a placeholder issue number, a garbled page range. This module compares
+each field of the entry against the canonical record and labels it `ok` / `formatting` / `error` /
+`uncertain` / `unverifiable`.
+
+The classifier is an intelligent combination of two layers:
+
+1. **Per-field deterministic rules** (`deterministic_field_checks`, pure, no network). These own the
+   cases a rule can settle: numeric fields (year/volume/issue) compare by value; page ranges are
+   normalized so that dash style (`--` vs en-dash vs the malformed `185-–197`) never reads as a
+   wrong page; empty/placeholder fields are flagged outright; exact and case/accent-folded string
+   matches resolve to `ok`/`formatting`.
+2. **An LLM check** for the genuinely ambiguous string differences a rule cannot judge — is
+   'Annual Review Condensed Matter Physics' a wrong name (dropped 'of') or just a variant? is
+   'J. Theor. Biol.' the same journal as 'Journal of Theoretical Biology'? `resolve_field_findings`
+   escalates exactly those, caching each decision.
+
+Per the reliability contract, an unconfirmable field becomes `unverifiable`/`uncertain` and is
+reported — never silently passed. Field checks are advisory: they never change the step-1 verdict.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from dataclasses import dataclass, field as dataclass_field
+
+from anyascii import anyascii
+
+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 FIELD_CHECK_SYSTEM, field_check_user
+from reference_audit.matching.features import is_repository_venue
+from reference_audit.matching.names import check_cited_authors, omitted_authors
+from reference_audit.models import (
+    BibEntry,
+    EntryType,
+    FieldFinding,
+    FieldJudgment,
+    MatchedArtifact,
+    SourceRecord,
+)
+from reference_audit.parsing.identifiers import arxiv_submission_year
+from reference_audit.versioning import cited_arxiv_id
+
+_BOOK_TYPES = {EntryType.BOOK, EntryType.INCOLLECTION}
+
+# Values that mean "no real value" even though the field is present (sotnikov `number={}`,
+# goldenfeld `number={-}`). Compared after stripping braces/whitespace and lowercasing.
+_PLACEHOLDERS = {"", "-", "--", "–", "—", "n/a", "n.a.", "na", "none", "null", "tbd", "?", "..."}
+
+# Source preference for sourcing a canonical field value: the publisher of record first, then the
+# rich registration-grade bibliographic records.
+_SOURCE_RANK = {
+    "publisher": 0,
+    "crossref": 1,
+    "openalex": 2,
+    "dblp": 3,
+    "openlibrary": 4,
+    "semantic_scholar": 5,
+    "arxiv": 6,
+}
+
+_DASH_RUN = re.compile(r"\s*[-–—‐]+\s*")
+_RANGE = re.compile(r"\w-\w")
+
+
+def _strip(s: str | None) -> str:
+    """Collapse whitespace and drop LaTeX braces, preserving case/accents."""
+    return re.sub(r"\s+", " ", (s or "").replace("{", "").replace("}", "")).strip()
+
+
+def _fold(s: str | None) -> str:
+    """Case/accent/punctuation-insensitive form for equivalence. Braces are *removed* (so the
+    protection in '{L}enia' rejoins 'Lenia') before other punctuation collapses to spaces."""
+    bare = (s or "").replace("{", "").replace("}", "")
+    return re.sub(r"\s+", " ", re.sub(r"[^a-z0-9 ]", " ", anyascii(bare).lower())).strip()
+
+
+def _is_placeholder(raw: str) -> bool:
+    return _strip(raw).lower() in _PLACEHOLDERS
+
+
+def _num(s: str) -> str:
+    """Normalize an integer-valued field (drop leading zeros); fall back to a folded string."""
+    t = _strip(s)
+    return str(int(t)) if t.isdigit() else _fold(t)
+
+
+def _norm_pages(p: str) -> str:
+    """Canonical page form for comparison: any dash run → single '-', folded ('E8678--E8687'→
+    'e8678-e8687'; '139–-158'→'139-158'; '40'→'40')."""
+    return _DASH_RUN.sub("-", _strip(p)).casefold()
+
+
+def _pages_clean_range(raw: str) -> bool:
+    """True if a page *range* is written with the canonical BibTeX '--' and nothing odd."""
+    s = _strip(raw)
+    if "–" in s or "—" in s:  # contains an en/em dash → not the canonical '--'
+        return False
+    return bool(re.search(r"\w--\w", s))
+
+
+# ── canonical value sourcing ─────────────────────────────────────────────────
+
+
+def _is_preprint_copy(rec: SourceRecord) -> bool:
+    """A preprint or repository copy of the work, rather than its journal/conference version."""
+    doi = rec.ids.doi or ""
+    return rec.is_preprint or doi.startswith("10.48550/arxiv") or is_repository_venue(rec.venue)
+
+
+def cites_preprint(entry: BibEntry) -> bool:
+    """The entry cites the preprint: its venue is a preprint server or repository, or it names no
+    venue but an arXiv id. Anything else cites a journal or conference version."""
+    if entry.venue:
+        return is_repository_venue(entry.venue)
+    return cited_arxiv_id(entry) is not None
+
+
+class _Ordered(list):
+    """Records in comparison order. `tiers[i]` is record i's (other kind, other year) group, or None
+    for a pooled fallback record; `_canonical` votes within the first group that has a value."""
+
+    tiers: list
+
+    def where(self, keep) -> _Ordered:
+        out = _Ordered(r for r in self if keep(r))
+        out.tiers = [t for r, t in zip(self, self.tiers, strict=True) if keep(r)]
+        return out
+
+
+def _ordered_records(entry: BibEntry, artifact: MatchedArtifact) -> _Ordered:
+    """The matched work's source records, the version the entry cites first.
+
+    A pooled record compiles one view across a work's versions, but an entry cites one version: the
+    arXiv preprint (its year, its title) or the published paper, and of a conference paper and its
+    later journal version, one of the two. So the fields are compared against the pooled record's
+    members: first those of the kind the entry cites (preprint or published), then those from the
+    cited year, then by source authority. The pooled records follow, as a fallback.
+    """
+    members = [m for r in artifact.records for m in (r.members or [r])]
+    wants_preprint = cites_preprint(entry)
+
+    def key(r: SourceRecord) -> tuple:
+        other_kind = _is_preprint_copy(r) != wants_preprint
+        other_year = entry.year is not None and r.year != entry.year
+        return (other_kind, other_year, _SOURCE_RANK.get(r.source, 9))
+
+    keyed = sorted(((key(r), r) for r in members), key=lambda kr: kr[0])
+    fallbacks = [r for r in artifact.records if r.members]
+    out = _Ordered([r for _, r in keyed] + fallbacks)
+    out.tiers = [k[:2] for k, _ in keyed] + [None] * len(fallbacks)
+    return out
+
+
+def _rec_sources(rec: SourceRecord) -> list[str]:
+    """Sources behind a (possibly pooled) record — the merge set if present, else its own source."""
+    merged_from = rec.raw.get("merged_from") if isinstance(rec.raw, dict) else None
+    return list(merged_from) if merged_from else [rec.source]
+
+
+def _canonical(records: list[SourceRecord], getter) -> tuple[str, list[str]]:
+    """The canonical value of a field, plus every source that agrees on it.
+
+    Within the first group of records (see `_Ordered`) that has a value, the value most sources agree
+    on wins, the more authoritative one on a tie. One source's defect is outvoted: OpenAlex gives
+    arXiv:2212.08073, Constitutional AI, the title "Affective Coherence Monitoring for
+    Transformer-Based Language Models", where S2, arXiv and DBLP have the real one.
+    """
+    def has(r: SourceRecord) -> bool:
+        return bool((getter(r) or "").strip())
+
+    first = next((i for i, r in enumerate(records) if has(r)), None)
+    if first is None:
+        return "", []
+    if records[first].members:  # a pooled fallback record: its own compiled value and merge set
+        return getter(records[first]).strip(), _rec_sources(records[first])
+    tiers = getattr(records, "tiers", None)
+    group = [
+        r for i, r in enumerate(records)
+        if has(r) and not r.members and (tiers is None or tiers[i] == tiers[first])
+    ]
+    support: dict[str, set[str]] = {}
+    for r in group:
+        support.setdefault(_fold(getter(r)), set()).add(r.source)
+    best = max(group, key=lambda r: (len(support[_fold(getter(r))]), -group.index(r)))
+    value = getter(best).strip()
+    agree = {r.source for r in records if not r.members and _fold(getter(r)) == _fold(value)}
+    return value, sorted(agree)
+
+
+# ── per-field deterministic comparison ───────────────────────────────────────
+
+
+@dataclass
+class _Check:
+    """A field comparison before (optional) LLM escalation. `needs_llm` marks the ambiguous
+    string differences a rule cannot settle on its own."""
+
+    field: str
+    bib_value: str
+    canonical_value: str
+    sources: list[str] = dataclass_field(default_factory=list)
+    status: str = "ok"  # ok | formatting | error | unverifiable | needs_llm
+    detail: str = ""
+    needs_llm: bool = False
+
+    def finding(self, *, via_llm: bool = False) -> FieldFinding:
+        return FieldFinding(
+            field=self.field,
+            bib_value=self.bib_value,
+            canonical_value=self.canonical_value,
+            sources=self.sources,
+            status="uncertain" if self.status == "needs_llm" else self.status,
+            detail=self.detail,
+            via_llm=via_llm,
+        )
+
+
+def _string_field(name: str, bib_raw: str, canonical: str, sources: list[str]) -> _Check:
+    """Exact → ok; case/accent-fold equal → formatting; otherwise escalate to the LLM."""
+    bib = _strip(bib_raw)
+    chk = _Check(name, bib, canonical, sources)
+    if not canonical:
+        chk.status, chk.detail = "unverifiable", "no source returned this field to check against"
+        return chk
+    if bib == _strip(canonical):
+        return chk
+    if _fold(bib) == _fold(canonical):
+        chk.status = "formatting"
+        chk.detail = f"only capitalization/punctuation/accents differ from canonical '{canonical}'"
+        return chk
+    chk.status, chk.needs_llm = "needs_llm", True
+    return chk
+
+
+def _venue_check(entry: BibEntry, records: _Ordered) -> _Check | None:
+    if not entry.venue:
+        return None
+    wants_preprint = cites_preprint(entry)
+    # A cited journal or conference is compared against a record that names one; a preprint server
+    # is the canonical venue only when no source has anything else.
+    published = records.where(lambda r: not is_repository_venue(r.venue))
+    canonical, sources = _canonical(records if wants_preprint else published, lambda r: r.venue)
+    if not canonical and not wants_preprint:
+        canonical, sources = _canonical(records, lambda r: r.venue)
+        if canonical:
+            chk = _Check("journal/venue", _strip(entry.venue), canonical, sources)
+            chk.status = "unverifiable"
+            chk.detail = (
+                f"every source has only a preprint/repository copy ('{canonical}'); the published "
+                "venue could not be confirmed"
+            )
+            return chk
+    return _string_field("journal/venue", entry.venue, canonical, sources)
+
+
+def _title_check(entry: BibEntry, records: list[SourceRecord]) -> _Check | None:
+    if not entry.title:
+        return None
+    canonical, sources = _canonical(records, lambda r: r.title)
+    chk = _Check("title", _strip(entry.title), canonical, sources)
+    if not canonical:
+        chk.status, chk.detail = "unverifiable", "no source returned a title to check against"
+        return chk
+    if _fold(entry.title) == _fold(canonical):
+        return chk  # braces/case/accents folded away → ok
+    chk.status, chk.needs_llm = "needs_llm", True
+    return chk
+
+
+def _year_check(entry: BibEntry, records: list[SourceRecord]) -> _Check | None:
+    if entry.year is None:
+        return None
+    value, sources = _canonical(records, lambda r: str(r.year) if r.year else "")
+    canonical_year = int(value) if value else None
+    chk = _Check("year", str(entry.year), value, sources)
+    if canonical_year is None:
+        chk.status, chk.detail = "unverifiable", "no source returned a year to check against"
+        return chk
+    delta = abs(entry.year - canonical_year)
+    if delta == 0:
+        return chk
+    # Preprint cited by its arXiv id: the .bib year is the original version's submission year
+    # (encoded in the id). arXiv updates push the canonical/latest year forward, so a *later*
+    # canonical year is a newer VERSION of the same preprint, not a wrong year — the record is valid
+    # for the version cited (the newer-version advisory is emitted by versioning.better_version_notes).
+    # A cited year that does NOT equal the id-encoded submission year falls through and is still flagged.
+    arxiv_id = cited_arxiv_id(entry)
+    if arxiv_id is not None and canonical_year > entry.year:
+        submitted = arxiv_submission_year(arxiv_id)
+        if submitted is not None and entry.year == submitted:
+            chk.detail = (
+                f"matches the cited arXiv version ({submitted}); canonical {canonical_year} is a "
+                "later version of the same preprint"
+            )
+            return chk  # status stays 'ok' — valid for the version cited
+    if entry.entry_type in _BOOK_TYPES:
+        # Books have edition-specific years; the match may be a different printing, so a year gap
+        # is a prompt to verify the edition — not, on its own, a bib mistake.
+        chk.status = "uncertain"
+        chk.detail = f"differs from matched edition ({canonical_year}); verify the edition/printing"
+    elif delta == 1:
+        chk.status = "uncertain"
+        chk.detail = f"differs by one from canonical {canonical_year} (often online vs print year)"
+    else:
+        chk.status = "error"
+        chk.detail = f"year {entry.year} does not match canonical {canonical_year}"
+    return chk
+
+
+def _author_check(
+    entry: BibEntry, records: list[SourceRecord], partial_authors: str
+) -> _Check | None:
+    """Every cited author must be an author of the matched work in at least one source record.
+
+    A cited list that names only some of the work's authors, without saying so ('and others'), is
+    reported per `partial_authors`: `ignore` (not reported), `warn` (uncertain) or `error`.
+    """
+    if not entry.authors:
+        return None
+    cited = "; ".join(entry.authors)
+    with_authors = [r for r in records if r.authors]
+    if not with_authors:
+        chk = _Check("author", cited, "", [])
+        chk.status, chk.detail = "unverifiable", "no source returned an author list to check against"
+        return chk
+    carrier = with_authors[0]  # the cited version's list (see _ordered_records)
+    chk = _Check("author", cited, "; ".join(carrier.authors), _rec_sources(carrier))
+    missing, unchecked = check_cited_authors(entry.authors, [r.authors for r in with_authors])
+    if missing or unchecked:
+        chk.sources = sorted({s for r in with_authors for s in _rec_sources(r)})
+    if missing:
+        chk.status = "error"
+        chk.detail = f"not an author of the matched work in any source: {', '.join(missing)}"
+        return chk
+    if unchecked:
+        longest = max(len(r.authors) for r in with_authors)
+        chk.status = "unverifiable"
+        chk.detail = (
+            f"every source lists only the first {longest} of the {len(entry.authors)} cited "
+            f"authors, so {', '.join(unchecked)} could not be checked"
+        )
+        return chk
+    if partial_authors == "ignore":
+        return chk
+    omitted = omitted_authors(entry.authors, carrier.authors)
+    if omitted:
+        chk.status = "error" if partial_authors == "error" else "uncertain"
+        shown = ", ".join(omitted[:5]) + (", …" if len(omitted) > 5 else "")
+        chk.detail = (
+            f"the cited list omits {len(omitted)} of the work's {len(carrier.authors)} authors "
+            f"({shown}) without marking it shortened ('and others')"
+        )
+    return chk
+
+
+def _numeric_field(
+    name: str, bib_raw: str | None, canonical: str, sources: list[str]
+) -> _Check | None:
+    """volume / issue: present-but-placeholder → error; numeric/string compare otherwise."""
+    if bib_raw is None:
+        return None  # field absent from the entry — nothing to check
+    chk = _Check(name, _strip(bib_raw), canonical, sources)
+    if _is_placeholder(bib_raw):
+        chk.status = "error"
+        chk.detail = f"{name} is empty or a placeholder ('{_strip(bib_raw)}')"
+        if canonical:
+            chk.detail += f"; canonical {name} is '{canonical}'"
+        return chk
+    if not canonical:
+        chk.status, chk.detail = "unverifiable", f"no source returned {name} to check against"
+        return chk
+    if _num(bib_raw) != _num(canonical):
+        chk.status = "error"
+        chk.detail = f"{name} '{_strip(bib_raw)}' does not match canonical '{canonical}'"
+    return chk
+
+
+def _pages_check(entry: BibEntry, records: list[SourceRecord]) -> _Check | None:
+    if not entry.pages:
+        return None
+    canonical, sources = _canonical(records, lambda r: r.pages)
+    chk = _Check("pages", _strip(entry.pages), canonical, sources)
+    if not canonical:
+        chk.status, chk.detail = "unverifiable", "no source returned pages to check against"
+        return chk
+    if _norm_pages(entry.pages) != _norm_pages(canonical):
+        chk.status = "error"
+        cano, ent = _norm_pages(canonical), _norm_pages(entry.pages)
+        if "-" not in cano and "-" in ent and ent.split("-", 1)[0] == cano:
+            # canonical is a single article number (e.g. an article-numbered proceedings); the entry
+            # turned it into a range, inventing an end page that no source confirms.
+            chk.detail = (
+                f"canonical lists a single article number '{canonical}'; the entry's range "
+                f"'{_strip(entry.pages)}' adds an end page no source confirms"
+            )
+        else:
+            chk.detail = f"pages '{_strip(entry.pages)}' do not match canonical '{canonical}'"
+        return chk
+    # Same page numbers: only the separator style may differ.
+    if _RANGE.search(_norm_pages(entry.pages)) and not _pages_clean_range(entry.pages):
+        chk.status = "formatting"
+        chk.detail = f"non-standard page separator in '{_strip(entry.pages)}'; use '--'"
+    return chk
+
+
+def deterministic_field_checks(
+    entry: BibEntry,
+    artifact: MatchedArtifact,
+    *,
+    skip_fields: frozenset[str] = frozenset(),
+    partial_authors: str = "warn",
+) -> list[_Check]:
+    """All per-field rule outcomes for a matched entry (pure, no network/LLM).
+
+    `skip_fields` drops named fields — used for books, whose `year`/`publisher` are edition-specific
+    and verified separately against the cited Open Library edition (see `check_book_edition_fields`),
+    not against the pooled artifact (which may hold a newer edition).
+    """
+    records = _ordered_records(entry, artifact)
+    checks: list[_Check | None] = [
+        _title_check(entry, records),
+        _author_check(entry, records, partial_authors),
+        _venue_check(entry, records),
+        _year_check(entry, records),
+    ]
+
+    vol_canon, vol_src = _canonical(records, lambda r: r.volume)
+    checks.append(_numeric_field("volume", entry.raw_fields.get("volume"), vol_canon, vol_src))
+
+    # The entry may carry the issue under the standard `number` or the variant `issue` field.
+    number_raw = entry.raw_fields.get("number")
+    if number_raw is None:
+        number_raw = entry.raw_fields.get("issue")
+    iss_canon, iss_src = _canonical(records, lambda r: r.issue)
+    checks.append(_numeric_field("number", number_raw, iss_canon, iss_src))
+
+    checks.append(_pages_check(entry, records))
+
+    if entry.publisher:
+        canonical, sources = _canonical(records, lambda r: r.publisher)
+        checks.append(_string_field("publisher", entry.publisher, canonical, sources))
+
+    return [c for c in checks if c is not None and c.field not in skip_fields]
+
+
+# ── LLM escalation ───────────────────────────────────────────────────────────
+
+
+def _apply_judgment(chk: _Check, judgment: FieldJudgment) -> FieldFinding:
+    finding = chk.finding(via_llm=True)
+    finding.detail = judgment.reason
+    if judgment.classification == "formatting_variant":
+        finding.status = "formatting"
+    elif judgment.classification == "error" and judgment.confidence in ("high", "medium"):
+        finding.status = "error"
+    else:  # low-confidence error or explicit uncertain → don't over-claim
+        finding.status = "uncertain"
+    return finding
+
+
+async def _judge_field(
+    entry: BibEntry,
+    chk: _Check,
+    llm: LLMClient | None,
+    cache: AuditCache | None,
+    context: SourceRecord,
+) -> FieldFinding:
+    if llm is None:
+        finding = chk.finding()
+        finding.status = "uncertain"
+        finding.detail = (
+            f"differs from canonical '{chk.canonical_value}'; LLM unavailable, verify manually"
+        )
+        return finding
+    user = field_check_user(chk.field, chk.bib_value, chk.canonical_value, chk.sources, context)
+    p_hash = prompt_hash(FIELD_CHECK_SYSTEM + "\n" + user)
+    if cache is not None:
+        cached = cache.get_llm_decision(p_hash, "field_check")
+        if cached is not None:
+            return _apply_judgment(chk, FieldJudgment.model_validate_json(cached))
+    try:
+        judgment = await llm.structured(FIELD_CHECK_SYSTEM, user, FieldJudgment, "field_check")
+    except LLMError as exc:
+        finding = chk.finding()
+        finding.status = "uncertain"
+        finding.detail = f"differs from canonical '{chk.canonical_value}'; LLM check failed ({exc})"
+        return finding
+    if cache is not None:
+        cache.put_llm_decision(p_hash, "field_check", judgment.model_dump_json())
+    return _apply_judgment(chk, judgment)
+
+
+async def resolve_field_findings(
+    entry: BibEntry,
+    artifact: MatchedArtifact,
+    llm: LLMClient | None,
+    config: AuditConfig,
+    cache: AuditCache | None,
+    *,
+    skip_fields: frozenset[str] = frozenset(),
+) -> list[FieldFinding]:
+    """Full step-3 result for one matched entry: deterministic rules + LLM tie-break, in order."""
+    checks = deterministic_field_checks(
+        entry, artifact, skip_fields=skip_fields, partial_authors=config.partial_authors
+    )
+    # The LLM is shown the matched work as the database records it (the cited version, with the
+    # canonical title), never the entry itself: told that the entry's title is the confirmed one, it
+    # waved through a different title as formatting.
+    records = _ordered_records(entry, artifact)
+    title, _ = _canonical(records, lambda r: r.title)
+    context = next((r for r in records if _fold(r.title) == _fold(title)), records[0])
+    escalated = await asyncio.gather(
+        *(_judge_field(entry, c, llm, cache, context) for c in checks if c.needs_llm)
+    )
+    escalated_iter = iter(escalated)
+    return [next(escalated_iter) if c.needs_llm else c.finding() for c in checks]
+
+
+def _book_publisher_check(entry: BibEntry, canonical: str, sources: list[str]) -> _Check:
+    """Publisher check against the cited edition's publisher.
+
+    A folded-substring relationship ('W. A. Benjamin' ⊆ 'W. A. Benjamin, Advanced Book Program') is a
+    shortened-but-correct imprint name → `formatting`, settled without the LLM. A genuinely different
+    string (a typo like 'Princeton Un iversity Press', or a different publisher) still escalates so it
+    is judged, not silently passed.
+    """
+    bib = _strip(entry.publisher)
+    chk = _Check("publisher", bib, canonical, sources)
+    if not canonical:
+        chk.status, chk.detail = "unverifiable", "the matched Open Library edition lists no publisher"
+        return chk
+    if bib == _strip(canonical):
+        return chk
+    a, b = _fold(bib), _fold(canonical)
+    if a and b and (a in b or b in a):
+        chk.status = "formatting"
+        chk.detail = f"a shortened form of the edition's publisher '{canonical}'"
+        return chk
+    chk.status, chk.needs_llm = "needs_llm", True
+    return chk
+
+
+async def check_book_edition_fields(
+    entry: BibEntry,
+    matched_edition: SourceRecord,
+    llm: LLMClient | None,
+    config: AuditConfig,  # noqa: ARG001 — symmetry with resolve_field_findings; reserved
+    cache: AuditCache | None,
+) -> list[FieldFinding]:
+    """Verify a book's `year`/`publisher` against the *cited* Open Library edition.
+
+    Grounding the canonical values in the matched edition (rather than the pooled artifact, which may
+    carry a newer reprint) means the original edition is no longer flagged against a later one. A
+    genuine publisher typo (e.g. 'Princeton Un iversity Press') still escalates to the LLM and is
+    caught.
+    """
+    records = [matched_edition]
+    checks: list[_Check] = []
+    year_chk = _year_check(entry, records)
+    if year_chk is not None:
+        checks.append(year_chk)
+    if entry.publisher:
+        canonical, sources = _canonical(records, lambda r: r.publisher)
+        checks.append(_book_publisher_check(entry, canonical, sources))
+    return [
+        await _judge_field(entry, c, llm, cache, matched_edition) if c.needs_llm else c.finding()
+        for c in checks
+    ]
+
+
+def consulted_sources(artifact: MatchedArtifact) -> list[str]:
+    """Every source actually behind the matched artifact's records — i.e. exactly what the field
+    checks compared against. Used to report an unverifiable field as "not present in {these
+    sources}", never as the unprovable claim that no authoritative source has it."""
+    return sorted({s for r in artifact.records for s in _rec_sources(r)})
+
+
+def finding_note(f: FieldFinding) -> str:
+    """One-line human summary for the text report (only actionable findings are surfaced)."""
+    src = f" [{', '.join(f.sources)}]" if f.sources else ""
+    tag = "(LLM) " if f.via_llm else ""
+    if f.status == "error":
+        return (
+            f"{tag}field '{f.field}' looks wrong: '{f.bib_value}' vs canonical "
+            f"'{f.canonical_value}'{src} — {f.detail}"
+        )
+    if f.status == "uncertain":
+        return (
+            f"{tag}field '{f.field}' needs review: '{f.bib_value}' vs canonical "
+            f"'{f.canonical_value}'{src} — {f.detail}"
+        )
+    return f"field '{f.field}'='{f.bib_value}' could not be verified — {f.detail}"