psyclaw 0.27.22 → 0.28.0

package/vendor/ars/scripts/migrate_literature_corpus_to_v3_9_0.py

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""#102 v3.9.0 cross-index triangulation backfill migration tool.
+
+Re-runs the v3.9.0 spec §3.4 + §3.5 OpenAlex + Crossref lookups post-hoc
+on v3.7.3 literature_corpus[] entries that have semantic_scholar_unmatched
+set but openalex_unmatched / crossref_unmatched absent.
+
+Scope: v3.7.3-onward entries only. Pre-v3.7.3 entries (no
+contamination_signals.semantic_scholar_unmatched) require the v3.7.3
+migration tool first — see scripts/migrate_literature_corpus_to_v3_7_3.py.
+This is daisy-chained migration per spec §3.7.
+
+Usage:
+    python migrate_literature_corpus_to_v3_9_0.py [--dry-run] [--verbose] PATH
+
+Concurrency (#138): when both fields are missing for an entry, the OpenAlex and
+Crossref lookups run in parallel via a 2-worker thread pool. This requires
+`concurrent.futures`. The library-layer sequential-fallback contract ("run
+sequentially if parallelism is not available") documented in
+deep-research/agents/bibliography_agent.md is a separate concern — this one-shot
+tool simply requires threading and does not fall back.
+
+Design: docs/design/2026-05-17-ars-v3.9.0-cross-index-triangulation-measurement-spec.md §3.7
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any, Mapping
+
+# Dual-path import: see openalex_client.py comment.
+try:
+    from _passport_yaml import dump_passport, load_passport
+except ImportError:
+    from scripts._passport_yaml import dump_passport, load_passport
+
+
+# Skip-reason keys surface in the migration report.
+_SKIP_MANUAL = "skipped_manual"
+_SKIP_PRE_V3_7_3 = "skipped_pre_v3_7_3"
+_SKIP_COMPLETE = "skipped_complete"
+
+
+def _entry_in_v3_7_3_scope(entry: Mapping[str, Any]) -> bool:
+    """Return True iff the entry has a v3.7.3-era `contamination_signals`
+    object (so v3.9.0 migration can act on it). Return False if
+    `contamination_signals` is absent entirely, or if it's present without
+    `semantic_scholar_unmatched` on a non-manual entry (out of v3.9.0
+    scope — needs `migrate_literature_corpus_to_v3_7_3.py` first per spec
+    §3.7 daisy-chain contract).
+
+    Manual entries are reported as in-scope when they carry a
+    `contamination_signals` object, because they ARE v3.7.3-era (spec §3.2
+    manual exemption gives them only `preprint_post_llm_inflection`, not
+    `semantic_scholar_unmatched`). The caller (`migrate_passport`) skips
+    manual entries separately before invoking the v3.9.0 fill logic; this
+    function's manual-branch is therefore a defensive contract — it
+    accurately reports v3.7.3 scope membership even when the caller's
+    skip order might change later.
+    """
+    sig = entry.get("contamination_signals")
+    if sig is None:
+        return False
+    if entry.get("obtained_via") == "manual":
+        # Manual entries are v3.7.3-era (carry contamination_signals)
+        # but the v3.7.3 §3.2 manual exemption means they have only
+        # preprint_post_llm_inflection, not semantic_scholar_unmatched.
+        # Caller's manual-skip handles the migration filter separately.
+        return True
+    return "semantic_scholar_unmatched" in sig
+
+
+def _is_complete(sig: Mapping[str, Any]) -> bool:
+    """Entry already has both v3.9.0 fields set — nothing to do."""
+    return "openalex_unmatched" in sig and "crossref_unmatched" in sig
+
+
+def migrate_passport(
+    path: Path,
+    *,
+    oa_client: Any,
+    cr_client: Any,
+    dry_run: bool,
+    verbose: bool = False,
+) -> dict[str, int]:
+    """Migrate a single passport file. Returns a report dict.
+
+    `oa_client`: OpenAlexClient (or mock) — must expose
+        doi_lookup_with_title_check(doi, title) and title_search(title).
+    `cr_client`: CrossrefClient (or mock) — same interface.
+
+    Mirrors migrate_literature_corpus_to_v3_7_3.migrate_passport() design:
+    accept injected clients for testability (no subprocess, no env-var mock).
+    """
+    import contamination_signals as cs
+    from openalex_client import OpenAlexUnavailable
+    from crossref_client import CrossrefUnavailable
+
+    doc = load_passport(path)
+    corpus = doc.get("literature_corpus") if doc else None
+    report: dict[str, int] = {
+        "processed": 0,
+        "patched": 0,
+        _SKIP_MANUAL: 0,
+        _SKIP_PRE_V3_7_3: 0,
+        _SKIP_COMPLETE: 0,
+        "degraded_openalex": 0,
+        "degraded_crossref": 0,
+    }
+    if not corpus:
+        return report
+
+    def _log(msg: str) -> None:
+        if verbose:
+            print(f"[{path}] {msg}", file=sys.stderr)
+
+    degradation_log: list[str] = []
+    mutated = False
+
+    for entry in corpus:
+        report["processed"] += 1
+        key = entry.get("citation_key", "<no-citation-key>")
+
+        # --- Skip: manual entry (v3.9.0 spec: exempt, never touch) ---
+        if entry.get("obtained_via") == "manual":
+            report[_SKIP_MANUAL] += 1
+            _log(f"{key}: skip (manual entry)")
+            continue
+
+        # --- Skip: pre-v3.7.3 (no contamination_signals or no SS field) ---
+        if not _entry_in_v3_7_3_scope(entry):
+            report[_SKIP_PRE_V3_7_3] += 1
+            _log(f"{key}: skip (pre-v3.7.3 — run v3.7.3 migration first)")
+            continue
+
+        sig = entry.get("contamination_signals", {})
+
+        # --- Skip: already complete (both fields set) ---
+        if _is_complete(sig):
+            report[_SKIP_COMPLETE] += 1
+            _log(f"{key}: skip (already complete)")
+            continue
+
+        # --- Backfill missing fields ---
+        entry_changed = False
+
+        # Reconcile one resolver's outcome on the orchestrator thread: get_result
+        # either returns the bool/None value or re-raises the resolver's Unavailable
+        # exception. All passport mutation, report bookkeeping, and degradation
+        # logging stay single-threaded here — the worker only performs the network
+        # call. Returns True iff a field was filled.
+        def _reconcile(get_result, sig_key, exc_type, label) -> bool:
+            try:
+                result = get_result()
+            except exc_type as e:
+                degradation_log.append(
+                    f"[CORPUS MIGRATION INCOMPLETE: {label}] {key}: {e}"
+                )
+                report[f"degraded_{label}"] += 1
+                _log(f"{key}: degraded ({label}) — {e}")
+                # #511 Part A reason-provenance: record WHY the field is
+                # absent so a degraded lookup stays distinguishable from
+                # "never computed". Idempotent (re-run with the API still
+                # down changes nothing); dry-run reports without writing.
+                already = (
+                    entry.get("contamination_signal_omissions", {})
+                    .get(sig_key) == cs.OMISSION_API_DEGRADED
+                )
+                if already:
+                    return False
+                if not dry_run:
+                    cs.record_signal_omission(entry, sig_key)
+                _log(f"{key}: record omission {sig_key}=api_degraded")
+                return True
+            # result=None means manual (already handled); API-down would have
+            # raised exc_type above, so None here just means "nothing to write".
+            if result is None:
+                return False
+            if not dry_run:
+                sig[sig_key] = result
+                entry["contamination_signals"] = sig
+                # #511 recovery: the signal is now computed, so any omission
+                # recorded by an earlier degraded run is stale.
+                cs.clear_signal_omission(entry, sig_key)
+            _log(f"{key}: fill {sig_key}={result}")
+            return True
+
+        need_oa = "openalex_unmatched" not in sig
+        need_cr = "crossref_unmatched" not in sig
+        if not need_oa:
+            _log(f"{key}: preserve openalex_unmatched (already set)")
+        if not need_cr:
+            _log(f"{key}: preserve crossref_unmatched (already set)")
+
+        # #138: the OpenAlex and Crossref lookups for this entry are independent
+        # (different hosts, per-instance throttle state, monotonic timing), so when
+        # both are missing dispatch the two network calls in parallel. Only missing
+        # fields are dispatched, so an already-set field never consults its client
+        # (preserves the partial-degradation contract). A single missing field skips
+        # the pool and calls directly — no parallelism to gain from one call.
+        if need_oa and need_cr:
+            with ThreadPoolExecutor(max_workers=2) as pool:
+                oa_future = pool.submit(cs.resolve_openalex_unmatched, entry, oa_client)
+                cr_future = pool.submit(cs.resolve_crossref_unmatched, entry, cr_client)
+            oa_changed = _reconcile(
+                oa_future.result, "openalex_unmatched", OpenAlexUnavailable, "openalex"
+            )
+            cr_changed = _reconcile(
+                cr_future.result, "crossref_unmatched", CrossrefUnavailable, "crossref"
+            )
+            entry_changed = oa_changed or cr_changed
+        elif need_oa:
+            entry_changed = _reconcile(
+                lambda: cs.resolve_openalex_unmatched(entry, oa_client),
+                "openalex_unmatched", OpenAlexUnavailable, "openalex",
+            )
+        elif need_cr:
+            entry_changed = _reconcile(
+                lambda: cs.resolve_crossref_unmatched(entry, cr_client),
+                "crossref_unmatched", CrossrefUnavailable, "crossref",
+            )
+
+        if entry_changed:
+            report["patched"] += 1
+            mutated = True
+
+    if mutated and not dry_run:
+        dump_passport(path, doc)
+
+    # Summary to stdout (mirrors v3.7.3 tool print-on-main pattern but
+    # here we always emit; caller may also call _print_report() below).
+    if degradation_log:
+        for line in degradation_log:
+            print(line, file=sys.stderr)
+
+    return report
+
+
+def _print_report(path: Path, report: dict[str, int], dry_run: bool) -> None:
+    mode = "(DRY RUN) " if dry_run else ""
+    would = "would-add" if dry_run else "patched"
+    print(
+        f"v3.9.0 migration {mode}{path}: "
+        f"processed={report['processed']} "
+        f"{would}={report['patched']} "
+        f"skipped_manual={report[_SKIP_MANUAL]} "
+        f"skipped_pre_v3_7_3={report[_SKIP_PRE_V3_7_3]} "
+        f"skipped_complete={report[_SKIP_COMPLETE]} "
+        f"degraded_openalex={report['degraded_openalex']} "
+        f"degraded_crossref={report['degraded_crossref']} "
+        f"dry_run={dry_run}"
+    )
+
+
+def _build_default_oa_client():
+    """Production OpenAlex client. Lazy-imported so tests that inject
+    mock clients never trigger a network-dependent module load."""
+    from openalex_client import OpenAlexClient
+    return OpenAlexClient()
+
+
+def _build_default_cr_client():
+    """Production Crossref client. Lazy-imported for the same reason."""
+    from crossref_client import CrossrefClient
+    return CrossrefClient()
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Backfill v3.9.0 openalex_unmatched + crossref_unmatched on "
+            "v3.7.3-onward literature_corpus[] entries. "
+            "See docs/design/2026-05-17-ars-v3.9.0-cross-index-triangulation-measurement-spec.md §3.7"
+        )
+    )
+    parser.add_argument("path", type=Path, help="Passport YAML file")
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Show proposed changes, write nothing"
+    )
+    parser.add_argument(
+        "--verbose", action="store_true", help="Per-entry logging to stderr"
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv or sys.argv[1:])
+    oa_client = _build_default_oa_client()
+    cr_client = _build_default_cr_client()
+    report = migrate_passport(
+        args.path,
+        oa_client=oa_client,
+        cr_client=cr_client,
+        dry_run=args.dry_run,
+        verbose=args.verbose,
+    )
+    _print_report(args.path, report, args.dry_run)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/vendor/ars/scripts/model_tiering_manifest.json

@@ -0,0 +1,46 @@
+{
+  "$comment": "Model-tiering classification manifest (#517). One entry per agent file; tier is 'judgment' or 'execution'. Single source of truth for scripts/check_model_tiering.py, which pins this file to the *_agent.md files on disk AND to the classification table in shared/model_tiering.md. Membership frozen 2026-07-11 (issue #517); changing a tier requires editing BOTH this file and the canonical table.",
+  "version": 1,
+  "canonical_doc": "shared/model_tiering.md",
+  "agents": [
+    {"path": "deep-research/agents/socratic_mentor_agent.md", "tier": "judgment"},
+    {"path": "deep-research/agents/research_question_agent.md", "tier": "judgment"},
+    {"path": "deep-research/agents/research_architect_agent.md", "tier": "judgment"},
+    {"path": "deep-research/agents/synthesis_agent.md", "tier": "judgment"},
+    {"path": "deep-research/agents/devils_advocate_agent.md", "tier": "judgment"},
+    {"path": "deep-research/agents/editor_in_chief_agent.md", "tier": "judgment"},
+    {"path": "deep-research/agents/ethics_review_agent.md", "tier": "judgment"},
+    {"path": "deep-research/agents/risk_of_bias_agent.md", "tier": "judgment"},
+    {"path": "deep-research/agents/meta_analysis_agent.md", "tier": "judgment"},
+    {"path": "deep-research/agents/source_verification_agent.md", "tier": "judgment"},
+    {"path": "deep-research/agents/bibliography_agent.md", "tier": "execution"},
+    {"path": "deep-research/agents/timeline_extraction_agent.md", "tier": "execution"},
+    {"path": "deep-research/agents/report_compiler_agent.md", "tier": "execution"},
+    {"path": "deep-research/agents/monitoring_agent.md", "tier": "execution"},
+    {"path": "academic-paper/agents/socratic_mentor_agent.md", "tier": "judgment"},
+    {"path": "academic-paper/agents/argument_builder_agent.md", "tier": "judgment"},
+    {"path": "academic-paper/agents/structure_architect_agent.md", "tier": "judgment"},
+    {"path": "academic-paper/agents/peer_reviewer_agent.md", "tier": "judgment"},
+    {"path": "academic-paper/agents/revision_coach_agent.md", "tier": "judgment"},
+    {"path": "academic-paper/agents/literature_strategist_agent.md", "tier": "judgment"},
+    {"path": "academic-paper/agents/intake_agent.md", "tier": "execution"},
+    {"path": "academic-paper/agents/draft_writer_agent.md", "tier": "execution"},
+    {"path": "academic-paper/agents/abstract_bilingual_agent.md", "tier": "execution"},
+    {"path": "academic-paper/agents/citation_compliance_agent.md", "tier": "execution"},
+    {"path": "academic-paper/agents/visualization_agent.md", "tier": "execution"},
+    {"path": "academic-paper/agents/formatter_agent.md", "tier": "execution"},
+    {"path": "academic-paper-reviewer/agents/eic_agent.md", "tier": "judgment"},
+    {"path": "academic-paper-reviewer/agents/methodology_reviewer_agent.md", "tier": "judgment"},
+    {"path": "academic-paper-reviewer/agents/domain_reviewer_agent.md", "tier": "judgment"},
+    {"path": "academic-paper-reviewer/agents/perspective_reviewer_agent.md", "tier": "judgment"},
+    {"path": "academic-paper-reviewer/agents/devils_advocate_reviewer_agent.md", "tier": "judgment"},
+    {"path": "academic-paper-reviewer/agents/editorial_synthesizer_agent.md", "tier": "judgment"},
+    {"path": "academic-paper-reviewer/agents/field_analyst_agent.md", "tier": "execution"},
+    {"path": "academic-pipeline/agents/pipeline_orchestrator_agent.md", "tier": "judgment"},
+    {"path": "academic-pipeline/agents/claim_ref_alignment_audit_agent.md", "tier": "judgment"},
+    {"path": "academic-pipeline/agents/integrity_verification_agent.md", "tier": "judgment"},
+    {"path": "academic-pipeline/agents/collaboration_depth_agent.md", "tier": "execution"},
+    {"path": "academic-pipeline/agents/state_tracker_agent.md", "tier": "execution"},
+    {"path": "shared/agents/compliance_agent.md", "tier": "judgment"}
+  ]
+}

package/vendor/ars/scripts/openalex_client.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Minimal OpenAlex API client wrapper.
+
+Implements the lookup contract documented at
+`deep-research/references/openalex_api_protocol.md`. DOI-first with
+title cross-check (DOI_MISMATCH pattern), title-similarity fallback,
+429 → budget-exhausted fail-fast or exponential backoff × 3 retries,
+5xx → skip. Mirrors `semantic_scholar_client.py` structure for code
+locality.
+"""
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Mapping
+
+# Dual-path import: sibling-first (so module identity matches when callers
+# import via the sibling path, e.g. tests), namespace-package fallback (for
+# repo-root `import scripts.openalex_client`). See semantic_scholar_client.py
+# for the identity-matching rationale.
+try:
+    from _text_similarity import (
+        _BACKOFF_SECONDS,
+        _MAX_RETRIES,
+        _TITLE_SIMILARITY_THRESHOLD,
+        _similarity,
+        exact_normalized_title,
+        generic_title,
+    )
+except ImportError:
+    from scripts._text_similarity import (
+        _BACKOFF_SECONDS,
+        _MAX_RETRIES,
+        _TITLE_SIMILARITY_THRESHOLD,
+        _similarity,
+        exact_normalized_title,
+        generic_title,
+    )
+
+
+_API_BASE = "https://api.openalex.org"
+_API_HOST = "api.openalex.org"
+_API_KEY_ENV = "OPENALEX_API_KEY"
+_POLITE_EMAIL_ENV = "OPENALEX_POLITE_EMAIL"
+# #651: is_retracted is part of the normal Works response and is retained in
+# the same lookup. No additional request is required.
+_FIELDS = "id,title,authorships,publication_year,doi,primary_location,is_retracted"
+
+_AUTHENTICATED_MIN_INTERVAL = 0.1
+_ANONYMOUS_MIN_INTERVAL = 1.0
+
+
+def _require_api_url(url: str) -> None:
+    parsed = urllib.parse.urlsplit(url)
+    if parsed.scheme != "https" or parsed.netloc != _API_HOST:
+        # Strip the query from the message: it can carry api_key, which
+        # must never land in logs / raised-exception text.
+        redacted = urllib.parse.urlunsplit(
+            (parsed.scheme, parsed.netloc, parsed.path, "", "")
+        )
+        raise OpenAlexUnavailable(f"Refusing non-OpenAlex URL: {redacted}")
+
+
+def _daily_budget_exhausted(headers: Any) -> bool:
+    """True iff a 429 carries `X-RateLimit-Remaining: 0` — OpenAlex's
+    daily-budget exhaustion signal (budget refills at midnight UTC), where
+    an in-process retry seconds later cannot succeed. A 429 without the
+    header, or with budget remaining, is transient burst limiting
+    (>100 req/s) and stays on the retry path."""
+    if headers is None:
+        return False
+    value = headers.get("X-RateLimit-Remaining")
+    if value is None:
+        return False
+    try:
+        return int(value) == 0
+    except (ValueError, TypeError):
+        return False
+
+
+class OpenAlexUnavailable(Exception):
+    """OpenAlex API degraded — caller MUST omit `openalex_unmatched`."""
+
+
+class OpenAlexClient:
+    """Production lookup-by-(doi-with-cross-check-then-title) client.
+
+    Concurrency note: rate-limit pacing is per-instance. Share a single
+    instance across a migration run.
+    """
+
+    def __init__(
+        self, polite_email: str | None = None, api_key: str | None = None,
+    ):
+        # api_key is the OpenAlex-documented auth mechanism (free key, 10×
+        # the keyless daily budget). polite_email predates it: the polite
+        # pool is no longer in OpenAlex's docs but `mailto` is still sent
+        # for backward compatibility when configured. Either credential
+        # selects the authenticated pacing tier.
+        self._api_key = api_key or os.environ.get(_API_KEY_ENV)
+        self._polite_email = polite_email or os.environ.get(_POLITE_EMAIL_ENV)
+        self._min_interval = (
+            _AUTHENTICATED_MIN_INTERVAL
+            if (self._api_key or self._polite_email)
+            else _ANONYMOUS_MIN_INTERVAL
+        )
+        self._last_request_at: float | None = None
+
+    def _throttle(self) -> None:
+        if self._last_request_at is None:
+            return
+        # time.monotonic for elapsed measurement: NTP / manual clock
+        # adjustments can make time.time go backward, producing negative
+        # elapsed and either huge sleep or zero sleep (#128 §6). Aligns
+        # with semantic_scholar_client.py.
+        elapsed = time.monotonic() - self._last_request_at
+        if elapsed < self._min_interval:
+            time.sleep(self._min_interval - elapsed)
+
+    def _get(self, path: str, query: Mapping[str, str]) -> dict[str, Any]:
+        params = dict(query)
+        if self._api_key:
+            params["api_key"] = self._api_key
+        if self._polite_email:
+            params["mailto"] = self._polite_email
+        url = f"{_API_BASE}{path}?{urllib.parse.urlencode(params)}"
+        _require_api_url(url)
+        req = urllib.request.Request(url, headers={"User-Agent": "ARS-v3.9.0"})
+
+        self._throttle()
+        self._last_request_at = time.monotonic()
+
+        for attempt in range(_MAX_RETRIES + 1):
+            try:
+                # URL is fixed-host HTTPS after _require_api_url().
+                with urllib.request.urlopen(req, timeout=30) as resp:  # nosec B310
+                    # Wrap response body read + decode + parse in a narrow
+                    # except so transient socket drops mid-stream, garbled
+                    # bodies, or HTML error pages slipped through with 200
+                    # status surface as OpenAlexUnavailable — honoring the
+                    # v3.9.0 spec §3.7 per-API degradation contract (one
+                    # transient failure must drop only openalex_unmatched,
+                    # not abort the whole backfill).
+                    try:
+                        body = resp.read()
+                        return json.loads(body.decode("utf-8"))
+                    except (
+                        OSError,
+                        http.client.HTTPException,
+                        UnicodeDecodeError,
+                        json.JSONDecodeError,
+                    ) as e:
+                        # http.client.HTTPException covers IncompleteRead
+                        # (truncated body — canonical mid-stream socket drop)
+                        # which inherits HTTPException, not OSError. Codex
+                        # review v3.9.1 R1 P2.
+                        raise OpenAlexUnavailable(
+                            f"OpenAlex response read/parse failed: {e}"
+                        ) from e
+            except urllib.error.HTTPError as e:
+                if e.code == 404:
+                    return {}
+                if e.code == 429:
+                    if _daily_budget_exhausted(e.headers):
+                        raise OpenAlexUnavailable(
+                            "OpenAlex daily budget exhausted "
+                            "(X-RateLimit-Remaining: 0, refills midnight UTC)"
+                        ) from e
+                    if attempt < _MAX_RETRIES:
+                        # Exponential backoff (2s → 4s → 8s) per OpenAlex's
+                        # documented guidance for transient burst 429s.
+                        time.sleep(_BACKOFF_SECONDS * (2 ** attempt))
+                        # Refresh anchor after backoff so the next _throttle()
+                        # paces against actual wake time, not entry time.
+                        # Without this the next call may under-sleep (elapsed
+                        # already counts the backoff) and re-trigger 429.
+                        self._last_request_at = time.monotonic()
+                        continue
+                raise OpenAlexUnavailable(f"OpenAlex HTTP {e.code}: {e.reason}") from e
+            except (urllib.error.URLError, TimeoutError) as e:
+                raise OpenAlexUnavailable(f"OpenAlex network error: {e}") from e
+
+        raise OpenAlexUnavailable("OpenAlex rate limit exhausted after retries")
+
+    def doi_lookup_with_title_check(
+        self, doi: str, expected_title: str,
+    ) -> dict[str, Any] | None:
+        """DOI lookup with mandatory Levenshtein 0.70 title cross-check."""
+        quoted_doi = urllib.parse.quote(doi, safe="")
+        data = self._get(f"/works/doi:{quoted_doi}", {"select": _FIELDS})
+        title = data.get("title") or ""
+        if _similarity(title, expected_title) >= _TITLE_SIMILARITY_THRESHOLD:
+            return data
+        return None  # DOI_MISMATCH
+
+    def title_search(self, title: str, year: int | None = None) -> dict[str, Any] | None:
+        """Title search under the #431 exact-title-or-bust gate.
+
+        A candidate matches iff it clears the 0.70 ratio AND is an exact
+        normalized title match (§0.12.1); a non-exact high-ratio title is never
+        promoted on year/author alone. On the title-fallback path no ID can
+        corroborate, so an exact-but-generic title (§0.12.2) is not promoted.
+        Returns the best exact candidate, or None → resolver reduces the
+        title-keyed miss to `unresolvable`. See crossref_client.title_search."""
+        if generic_title(title):
+            return None
+        data = self._get("/works", {
+            "search": title,
+            "per-page": "5",
+            "select": _FIELDS,
+        })
+        candidates = data.get("results", [])
+        scored = []
+        for cand in candidates:
+            cand_title = cand.get("title") or ""
+            sim = _similarity(cand_title, title)
+            if sim < _TITLE_SIMILARITY_THRESHOLD:
+                continue
+            if not exact_normalized_title(title, cand_title):
+                continue
+            year_match = year is not None and cand.get("publication_year") == year
+            score = sim + (0.05 if year_match else 0.0)
+            scored.append((cand, score))
+        if not scored:
+            return None
+        scored.sort(key=lambda cand_score: (-cand_score[1],))
+        return scored[0][0]