psyclaw 0.27.23 → 0.28.1

package/vendor/ars/scripts/verification_cache.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""Persistent verification cache for the bibliographic resolvers (Delta 2).
+
+A local SQLite-backed cache so the same paper cited across multiple drafts
+does not re-hit Crossref / OpenAlex / Semantic Scholar / arXiv every run.
+
+Cache key: (citation_key, resolver_name, query_form).
+  - resolver_name ∈ {crossref, openalex, semantic_scholar, arxiv}
+  - query_form is the canonical-form DOI / arXiv ID / title-query string the
+    resolver was keyed on (the caller passes whichever it used).
+Cache value: the resolver's structured response (any JSON-serializable dict)
+plus a verification_timestamp.
+
+TTL: entries older than 90 days are treated as a miss. The 90-day window is a
+guess pending empirical tuning (spec OQ-1, deferred).
+
+Concurrency: SQLite WAL mode (single-writer-many-readers). The audit pipeline
+is single-process; multi-user shared cache is out of scope (spec Delta 2).
+
+Spec: docs/design/2026-05-21-v3.10-182-promote-citation-gate-spec.md §2 Delta 2.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from contextlib import closing
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+# Spec OQ-1: 90-day window is a guess, deferred for empirical tuning.
+# Also documented user-facing in docs/DATA_FLOWS.md and docs/SETUP.md —
+# update both when tuning.
+_TTL_DAYS = 90
+
+# #541 staleness advisory (Ren et al. arXiv:2607.13104 §6.2.3 "scheduled review
+# and attenuation"): entries older than this many days are still HITS (the TTL
+# above is the only miss boundary) but carry an advisory flag so stale evidence
+# is visible exactly where it is used. 0 disables the advisory. Advisory-only —
+# never a gate input.
+_STALE_ADVISORY_ENV = "ARS_CACHE_STALE_ADVISORY_DAYS"
+# Default also documented in docs/DATA_FLOWS.md — update both when tuning.
+_STALE_ADVISORY_DEFAULT_DAYS = 30
+
+
+def stale_advisory_days() -> int:
+    """The #541 advisory threshold in days (env-overridable; 0 disables).
+
+    A malformed or negative override falls back to the default rather than
+    erroring: the advisory is a convenience layer and must never break a run.
+    """
+    raw = os.environ.get(_STALE_ADVISORY_ENV)
+    if raw is None:
+        return _STALE_ADVISORY_DEFAULT_DAYS
+    try:
+        value = int(raw)
+    except ValueError:
+        return _STALE_ADVISORY_DEFAULT_DAYS
+    if value < 0:
+        return _STALE_ADVISORY_DEFAULT_DAYS
+    return value
+
+_DEFAULT_PATH = Path.home() / ".cache" / "ars" / "verification.db"
+_ENV_PATH = "ARS_VERIFICATION_CACHE_PATH"
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS verification_cache (
+    citation_key           TEXT NOT NULL,
+    resolver_name          TEXT NOT NULL,
+    query_form             TEXT NOT NULL,
+    response_json          TEXT NOT NULL,
+    verification_timestamp TEXT NOT NULL,
+    PRIMARY KEY (citation_key, resolver_name, query_form)
+)
+"""
+
+
+def _parse_ts(verification_timestamp: str) -> datetime | None:
+    """Parse a stored ISO timestamp defensively (#541): naive timestamps
+    (written by older/other tools) are read as UTC; malformed strings return
+    None (callers treat the row as a miss / skip it — never abort)."""
+    try:
+        stored = datetime.fromisoformat(verification_timestamp)
+    except (ValueError, TypeError):
+        return None
+    if stored.tzinfo is None:
+        stored = stored.replace(tzinfo=timezone.utc)
+    return stored
+
+
+def _resolve_path(path: str | None) -> Path:
+    """Explicit arg wins over the env override, which wins over the default."""
+    if path is not None:
+        return Path(path)
+    env = os.environ.get(_ENV_PATH)
+    if env:
+        return Path(env)
+    return _DEFAULT_PATH
+
+
+class VerificationCache:
+    """SQLite-backed (citation_key, resolver_name, query_form) → response cache.
+
+    Single-process use. Each method opens a short-lived connection so the
+    cache holds no long-lived file handle across pipeline stages.
+    """
+
+    def __init__(self, path: str | None = None) -> None:
+        self.path = str(_resolve_path(path))
+        Path(self.path).parent.mkdir(parents=True, exist_ok=True)
+        # `closing(...) as conn, conn` — the outer ctx closes the handle, the
+        # inner (the connection itself) commits/rolls back. Honors the
+        # short-lived-connection contract (no leaked handle across stages).
+        with closing(self._connect()) as conn, conn:
+            conn.execute(_SCHEMA)
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.path)
+        # WAL: single-writer-many-readers safety (spec Delta 2). Persistent
+        # journal-mode pragma — set on every connection (cheap; no-op when
+        # already WAL).
+        conn.execute("PRAGMA journal_mode=WAL")
+        return conn
+
+    def get(
+        self, citation_key: str, resolver_name: str, query_form: str,
+    ) -> dict[str, Any] | None:
+        """Return the cached response, or None on miss / expired entry.
+
+        An entry whose verification_timestamp is older than the TTL is a
+        miss (the caller then makes the live call and re-populates).
+        """
+        with closing(self._connect()) as conn:
+            row = conn.execute(
+                "SELECT response_json, verification_timestamp "
+                "FROM verification_cache "
+                "WHERE citation_key = ? AND resolver_name = ? AND query_form = ?",
+                (citation_key, resolver_name, query_form),
+            ).fetchone()
+        if row is None:
+            return None
+        response_json, ts = row
+        if self._is_expired(ts):
+            return None
+        # #331: a corrupted payload (not decodable) or a non-dict value (e.g.
+        # written by an older/other tool) is a miss, not a hard error — the
+        # documented contract is "malformed cache payload = miss". Returning None
+        # forces a clean live recompute instead of aborting verification with a
+        # JSONDecodeError or handing the caller a shape it cannot read.
+        try:
+            value = json.loads(response_json)
+        except (json.JSONDecodeError, TypeError):
+            return None
+        if not isinstance(value, dict):
+            return None
+        return value
+
+    def put(
+        self,
+        citation_key: str,
+        resolver_name: str,
+        query_form: str,
+        response: dict[str, Any],
+    ) -> None:
+        """Store (or overwrite) the resolver response, stamping it now (UTC)."""
+        now = datetime.now(timezone.utc).isoformat()
+        with closing(self._connect()) as conn, conn:
+            conn.execute(
+                "INSERT OR REPLACE INTO verification_cache "
+                "(citation_key, resolver_name, query_form, response_json, "
+                " verification_timestamp) VALUES (?, ?, ?, ?, ?)",
+                (
+                    citation_key,
+                    resolver_name,
+                    query_form,
+                    json.dumps(response),
+                    now,
+                ),
+            )
+
+    def invalidate(self, citation_key: str) -> None:
+        """Drop every cached entry (all resolvers, all query forms) for a
+        citation. Backs the /ars-cache-invalidate command. No-op when the
+        citation has no cached rows."""
+        with closing(self._connect()) as conn, conn:
+            conn.execute(
+                "DELETE FROM verification_cache WHERE citation_key = ?",
+                (citation_key,),
+            )
+
+    def entry_age_days(self, citation_key: str) -> float | None:
+        """Age in days of the OLDEST live (non-expired) cached row for a
+        citation, across resolvers and query forms — deliberately the most
+        conservative citation-level signal (#541): an unexpired row for an
+        obsolete query form can flag a citation whose latest verification is
+        fresh. That false-positive direction is accepted (advisory-only; a
+        stale warning that prompts one unnecessary look is cheaper than a
+        missed stale source). None when the citation has no live rows.
+        Malformed timestamps are skipped; naive timestamps are read as UTC;
+        clock-skewed future timestamps clamp to age 0.
+        """
+        with closing(self._connect()) as conn:
+            rows = conn.execute(
+                "SELECT verification_timestamp FROM verification_cache "
+                "WHERE citation_key = ?",
+                (citation_key,),
+            ).fetchall()
+        ages = []
+        now = datetime.now(timezone.utc)
+        for (ts,) in rows:
+            if self._is_expired(ts):
+                continue
+            stored = _parse_ts(ts)
+            if stored is None:
+                continue
+            ages.append(max(0.0, (now - stored).total_seconds() / 86400.0))
+        return max(ages) if ages else None
+
+    def row_age_days(
+        self, citation_key: str, resolver_name: str, query_form: str,
+    ) -> float | None:
+        """Age in days of ONE live cached row (#541 per-row form — backs the
+        stale-revalidate bypass, which must judge exactly the row it would
+        serve). None on miss / expired / malformed timestamp. Future
+        timestamps clamp to 0."""
+        with closing(self._connect()) as conn:
+            row = conn.execute(
+                "SELECT verification_timestamp FROM verification_cache "
+                "WHERE citation_key = ? AND resolver_name = ? AND query_form = ?",
+                (citation_key, resolver_name, query_form),
+            ).fetchone()
+        if row is None or self._is_expired(row[0]):
+            return None
+        stored = _parse_ts(row[0])
+        if stored is None:
+            return None
+        return max(
+            0.0, (datetime.now(timezone.utc) - stored).total_seconds() / 86400.0
+        )
+
+    def stale_report(
+        self, citation_keys: list[str],
+    ) -> dict[str, dict[str, Any]]:
+        """Per-citation #541 staleness report for the integrity gate.
+
+        Returns {citation_key: {"cache_age_days": float,
+        "cache_stale_advisory": bool}} for keys that have at least one live
+        cached row; keys with no live rows are omitted (nothing cache-served =
+        nothing to warn about). `cache_stale_advisory` is True iff the
+        threshold is enabled (>0) and the oldest live row exceeds it.
+        Advisory-only: callers MUST NOT gate on this report.
+        """
+        threshold = stale_advisory_days()
+        report: dict[str, dict[str, Any]] = {}
+        for key in citation_keys:
+            age = self.entry_age_days(key)
+            if age is None:
+                continue
+            rounded = round(age, 1)
+            # The flag is computed from the SAME rounded value the report
+            # emits, so the emitted pair is always self-consistent (a raw age
+            # of threshold+epsilon that rounds down to the threshold does not
+            # flag).
+            report[key] = {
+                "cache_age_days": rounded,
+                "cache_stale_advisory": bool(threshold and rounded > threshold),
+            }
+        return report
+
+    @staticmethod
+    def _is_expired(verification_timestamp: str) -> bool:
+        stored = _parse_ts(verification_timestamp)
+        if stored is None:
+            return True  # malformed timestamp = expired = miss, never an abort
+        return datetime.now(timezone.utc) - stored > timedelta(days=_TTL_DAYS)

package/vendor/ars/scripts/verification_gate/__init__.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""verification_gate — citation existence verification API (Delta 5).
+
+Public functions:
+  - verify_citation(entry, clients, *, ref_slug, anchor=None, cache=None)
+        -> CitationVerificationOutcome
+  - verify_passport(passport, clients, *, ref_slug_by_key, anchors=None,
+        cache=None) -> list[outcome]
+
+Composes the four resolvers (crossref / openalex / semantic_scholar / arxiv),
+maps each resolver's execution to a {status, queried_by} outcome, derives the
+3-class lookup_verified via the Delta 4 reducer (narrowed-false, C-V6(a)),
+reads anchor_present from the v3.7.3 anchor marker, and stamps
+verification_timestamp. Both ref_slug and anchor are prose-sourced inputs joined
+upstream by citation_key — NEVER read off the corpus entry, whose schema forbids
+them (#332). Does NOT duplicate the v3.8 audit pipeline — it composes
+the same lower-layer resolvers and writes the unified summary schema (Delta 4).
+
+The returned dict validates against
+shared/contracts/passport/citation_verification_summary.schema.json.
+
+Spec: docs/design/2026-05-21-v3.10-182-promote-citation-gate-spec.md §2 Delta 5.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Mapping
+
+try:
+    from citation_verification_summary import (
+        STATUS_MATCHED,
+        STATUS_SKIPPED,
+        STATUS_UNMATCHED,
+        STATUS_UNREACHABLE,
+        reduce_lookup_verified,
+    )
+    from crossref_client import CrossrefUnavailable
+    from openalex_client import OpenAlexUnavailable
+    from arxiv_client import ArxivUnavailable
+    from contamination_signals import (
+        SemanticScholarUnavailable,
+        _resolve_arxiv_id_then_title,
+        _resolve_doi_then_title,
+        queried_by_for,
+        resolve_arxiv_detailed,
+        resolve_doi_then_title_detailed,
+        resolve_s2_detailed,
+    )
+    from verification_cache import stale_advisory_days
+except ImportError:  # pragma: no cover - dual-path import
+    from scripts.citation_verification_summary import (
+        STATUS_MATCHED,
+        STATUS_SKIPPED,
+        STATUS_UNMATCHED,
+        STATUS_UNREACHABLE,
+        reduce_lookup_verified,
+    )
+    from scripts.crossref_client import CrossrefUnavailable
+    from scripts.openalex_client import OpenAlexUnavailable
+    from scripts.arxiv_client import ArxivUnavailable
+    from scripts.contamination_signals import (
+        SemanticScholarUnavailable,
+        _resolve_arxiv_id_then_title,
+        _resolve_doi_then_title,
+        queried_by_for,
+        resolve_arxiv_detailed,
+        resolve_doi_then_title_detailed,
+        resolve_s2_detailed,
+    )
+    from scripts.verification_cache import stale_advisory_days
+
+_ANCHOR_PRESENT_KINDS = frozenset({"quote", "page", "section", "paragraph"})
+
+# #541 omitted-argument sentinel: omission = default cache-through (a
+# VerificationCache at the default/env path) + revalidation derived from
+# ARS_CACHE_REVALIDATE; an EXPLICIT cache=None is the live opt-out.
+_UNSET = object()
+
+
+def _default_cache():
+    try:
+        from verification_cache import VerificationCache
+    except ImportError:  # pragma: no cover - dual-path import
+        from scripts.verification_cache import VerificationCache
+    return VerificationCache()
+
+
+def _resolve_cache_args(cache, revalidate_stale):
+    import os
+    if cache is _UNSET:
+        cache = _default_cache()
+    if revalidate_stale is _UNSET:
+        revalidate_stale = os.environ.get("ARS_CACHE_REVALIDATE") == "1"
+    return cache, revalidate_stale
+
+
+def _is_valid_ref_slug(ref_slug: Any) -> bool:
+    """A ref_slug is valid iff it is a non-empty string: the summary schema
+    requires ref_slug as a string, and an empty slug joins to no
+    <!--ref:slug--> prose marker. Single definition so verify_citation (the
+    emission point) and verify_passport (the join layer) agree on "bad slug"
+    (#332)."""
+    return isinstance(ref_slug, str) and bool(ref_slug)
+
+
+def _outcome(status: str, queried_by: str | None,
+             response_summary: str | None = None) -> dict[str, Any]:
+    return {"status": status, "queried_by": queried_by,
+            "response_summary": response_summary}
+
+
+def _ran_outcome(unmatched: bool, queried_by: str | None) -> dict[str, Any]:
+    """Map a ran-resolver result (matched/unmatched) to an outcome dict."""
+    return _outcome(STATUS_UNMATCHED if unmatched else STATUS_MATCHED, queried_by)
+
+
+def _run_doi_then_title(
+    entry, client, unavailable_exc, *, resolver_name=None, cache=None,
+    bypass_stale=False,
+) -> tuple[dict[str, Any], bool]:
+    """Run a doi-then-title resolver, mapping execution to a status outcome.
+    Used by crossref / openalex (same flow + DOI key, different exception).
+    The manual exemption is short-circuited upstream in verify_citation.
+    Returns (outcome, served_from_cache) — #541 cache-through routes via the
+    detailed contamination_signals wrapper (same cache keys, interoperable
+    rows); cache=None is byte-equivalent to the historical live path."""
+    try:
+        if cache is not None:
+            unmatched, _mb, queried_by, from_cache = (
+                resolve_doi_then_title_detailed(
+                    entry, client, resolver_name=resolver_name, cache=cache,
+                    bypass_stale=bypass_stale))
+        else:
+            unmatched, _mb, queried_by = _resolve_doi_then_title(entry, client)
+            from_cache = False
+    except unavailable_exc:
+        return _outcome(STATUS_UNREACHABLE, None), False
+    return _ran_outcome(unmatched, queried_by), from_cache
+
+
+def _run_semantic_scholar(
+    entry, client, *, cache=None, bypass_stale=False,
+) -> tuple[dict[str, Any], bool]:
+    """S2's lookup(entry) is a single entry-keyed call (DOI-first then title
+    internally). queried_by follows the has-an-id rule (C-V6(a)). The manual
+    exemption is short-circuited upstream in verify_citation."""
+    queried_by = queried_by_for(entry, id_field="doi")
+    try:
+        if cache is not None:
+            unmatched, _mb, queried_by, from_cache = resolve_s2_detailed(
+                entry, client, cache=cache, bypass_stale=bypass_stale)
+            return _ran_outcome(unmatched, queried_by), from_cache
+        matched = bool(client.lookup(entry).get("matched", False))
+    except SemanticScholarUnavailable:
+        return _outcome(STATUS_UNREACHABLE, None), False
+    return _ran_outcome(not matched, queried_by), False
+
+
+def _run_arxiv(
+    entry, client, *, cache=None, bypass_stale=False,
+) -> tuple[dict[str, Any], bool]:
+    """arXiv resolver is applicable only when the citation has an arXiv ID;
+    otherwise it is skipped (not unmatched) per Delta 1 / spec line 119. The
+    manual exemption is short-circuited upstream in verify_citation."""
+    if not entry.get("arxiv_id"):
+        # non-arXiv citation → not applicable
+        return _outcome(STATUS_SKIPPED, None), False
+    try:
+        if cache is not None:
+            unmatched, _mb, queried_by, from_cache = resolve_arxiv_detailed(
+                entry, client, cache=cache, bypass_stale=bypass_stale)
+        else:
+            unmatched, _mb, queried_by = _resolve_arxiv_id_then_title(
+                entry, client)
+            from_cache = False
+    except ArxivUnavailable:
+        return _outcome(STATUS_UNREACHABLE, None), False
+    return _ran_outcome(unmatched, queried_by), from_cache
+
+
+def _anchor_present(anchor: Any) -> bool:
+    """True iff the v3.7.3 anchor marker has kind ∈ {quote,page,section,paragraph}
+    (not none). `anchor` is the already-parsed {kind, value} marker sourced from
+    writer prose and joined by ref_slug upstream — NEVER read off the corpus
+    entry (the literature_corpus_entry schema has no anchor field; reading it
+    there would be a permanent silent False)."""
+    if not isinstance(anchor, Mapping):
+        return False
+    return anchor.get("kind") in _ANCHOR_PRESENT_KINDS
+
+
+def verify_citation(
+    entry: Mapping[str, Any],
+    clients: Mapping[str, Any],
+    *,
+    ref_slug: str,
+    anchor: Mapping[str, Any] | None = None,
+    cache=_UNSET,
+    revalidate_stale=_UNSET,
+) -> dict[str, Any]:
+    """Verify one citation's existence across the four resolvers.
+
+    `entry` carries citation_key, title, authors, year, source_pointer, optional
+    doi / arxiv_id, obtained_via. `clients` is a mapping {crossref, openalex,
+    semantic_scholar, arxiv} of resolver clients (injected so callers control
+    network / cache).
+
+    `ref_slug` is the writer-prose `<!--ref:slug-->` marker this citation renders
+    under, supplied by the caller — never read off the corpus entry (same
+    provenance rule as `anchor`; the entry schema forbids the field, #332).
+
+    `anchor` is the v3.7.3 anchor marker ({kind, value}) for this citation's
+    ref_slug, already parsed from writer prose and joined upstream (None when no
+    anchor marker exists for the ref_slug). It is a SEPARATE input, not an entry
+    field — the anchor lives in prose, not in literature_corpus (spec Delta 4:
+    the summary is a join across three sources).
+
+    `cache` (#541, closes the Delta-2 follow-up): an optional VerificationCache
+    threaded through the four resolvers (same cache keys as the
+    contamination-signals layer — interoperable rows). OMITTING the argument gives the
+    default cache-through (VerificationCache at the default/env path) with
+    revalidation derived from ARS_CACHE_REVALIDATE; passing cache=None
+    EXPLICITLY is the live opt-out, byte-equivalent to the historical path. When any resolver outcome was
+    served from cache, the summary additionally carries `cache_age_days`
+    (citation-level oldest-live-row age, rounded to 0.1) and
+    `cache_stale_advisory` (that rounded value > ARS_CACHE_STALE_ADVISORY_DAYS,
+    0 disables) — advisory metadata, never a gate input. `revalidate_stale`
+    (#541 `ARS_CACHE_REVALIDATE`): a would-be hit whose own row age exceeds
+    the threshold is recomputed live and re-cached instead of served.
+
+    Returns a dict validating against citation_verification_summary.schema.json:
+    {citation_key, ref_slug, lookup_verified, anchor_present,
+     verification_timestamp, resolver_outcomes} (+ the two #541 fields when
+    cache-served).
+    """
+    cache, revalidate_stale = _resolve_cache_args(cache, revalidate_stale)
+    if not _is_valid_ref_slug(ref_slug):
+        # ref_slug is the prose-join key stamped verbatim into the summary, which
+        # the schema requires as a non-empty string. This is the single emission
+        # point (verify_passport routes through here), so the contract is enforced
+        # once: a non-string fails the schema's type:string, and an empty string
+        # joins to no <!--ref:slug--> marker. Either is a caller (prose-join) error
+        # — refuse rather than emit a contract-invalid / join-broken summary (#332).
+        raise ValueError(
+            f"ref_slug must be a non-empty string (the writer-prose join key), "
+            f"got {ref_slug!r}; corpus entries do not carry ref_slug (#332)"
+        )
+    if entry.get("obtained_via") == "manual":
+        # v3.7.3 manual exemption: no resolver runs — all four skipped (checked
+        # once here rather than re-checked inside each resolver helper).
+        resolver_outcomes = {
+            r: _outcome(STATUS_SKIPPED, None)
+            for r in ("crossref", "openalex", "semantic_scholar", "arxiv")
+        }
+        any_from_cache = False
+    else:
+        ran = {
+            "crossref": _run_doi_then_title(
+                entry, clients["crossref"], CrossrefUnavailable,
+                resolver_name="crossref", cache=cache,
+                bypass_stale=revalidate_stale),
+            "openalex": _run_doi_then_title(
+                entry, clients["openalex"], OpenAlexUnavailable,
+                resolver_name="openalex", cache=cache,
+                bypass_stale=revalidate_stale),
+            "semantic_scholar": _run_semantic_scholar(
+                entry, clients["semantic_scholar"], cache=cache,
+                bypass_stale=revalidate_stale),
+            "arxiv": _run_arxiv(
+                entry, clients["arxiv"], cache=cache,
+                bypass_stale=revalidate_stale),
+        }
+        resolver_outcomes = {name: oc for name, (oc, _fc) in ran.items()}
+        any_from_cache = any(fc for _oc, fc in ran.values())
+    summary = {
+        "citation_key": entry.get("citation_key"),
+        "ref_slug": ref_slug,
+        "lookup_verified": reduce_lookup_verified(resolver_outcomes),
+        "anchor_present": _anchor_present(anchor),
+        "verification_timestamp": datetime.now(timezone.utc).isoformat(),
+        "resolver_outcomes": resolver_outcomes,
+    }
+    if cache is not None and any_from_cache:
+        age = cache.entry_age_days(entry.get("citation_key"))
+        if age is not None:
+            rounded = round(age, 1)
+            threshold = stale_advisory_days()
+            summary["cache_age_days"] = rounded
+            summary["cache_stale_advisory"] = bool(
+                threshold and rounded > threshold)
+    return summary
+
+
+def verify_passport(
+    passport: Mapping[str, Any],
+    clients: Mapping[str, Any],
+    *,
+    ref_slug_by_key: Mapping[str, str],
+    anchors: Mapping[str, Mapping[str, Any]] | None = None,
+    cache=_UNSET,
+    revalidate_stale=_UNSET,
+) -> list[dict[str, Any]]:
+    """Batch helper: run verify_citation over every entry in the passport's
+    literature_corpus[].
+
+    `ref_slug_by_key` is the {citation_key: ref_slug} join map: corpus entries are
+    keyed by citation_key, writer prose is keyed by ref_slug, and the join across
+    them is the caller's (Stage 4→5 pipeline's) responsibility — the corpus entry
+    never carries ref_slug itself (#332). An entry whose citation_key has no joined
+    ref_slug raises ValueError rather than emitting a contract-invalid summary;
+    the per-entry summary contract requires a non-null string ref_slug, so a
+    missing join is a caller error, not a silently-defaulted field.
+
+    `anchors` is the {ref_slug: anchor-marker} join map parsed from writer prose
+    (the v3.7.3 <!--anchor:kind:value--> markers); each entry's anchor is looked
+    up by its (joined) ref_slug (absent → anchor_present False). Threading both
+    joins here keeps verify_citation a pure per-citation unit.
+
+    ref_slug_by_key is 1:1 (one summary row per corpus entry); per-prose-occurrence
+    verification (one entry under several ref slugs) is a different API shape, out
+    of scope here.
+    """
+    cache, revalidate_stale = _resolve_cache_args(cache, revalidate_stale)
+    corpus = passport.get("literature_corpus") or []
+    anchors = anchors or {}
+    outcomes: list[dict[str, Any]] = []
+    for entry in corpus:
+        citation_key = entry.get("citation_key")
+        ref_slug = ref_slug_by_key.get(citation_key)
+        if not _is_valid_ref_slug(ref_slug):
+            # Missing join (None) OR a present-but-empty/non-string slug — both
+            # fail the per-summary contract. Caught here (not just in
+            # verify_citation) so the error names the offending citation_key,
+            # which the per-citation layer doesn't have (#332).
+            raise ValueError(
+                f"no valid ref_slug joined for citation_key {citation_key!r} "
+                f"(got {ref_slug!r}): the citation_key→ref_slug prose join must "
+                "cover every corpus entry with a non-empty string "
+                "(corpus entries do not carry ref_slug; #332)"
+            )
+        outcomes.append(verify_citation(
+            entry, clients, ref_slug=ref_slug,
+            anchor=anchors.get(ref_slug), cache=cache,
+            revalidate_stale=revalidate_stale))
+    return outcomes