@pentatonic-ai/ai-agent-sdk 0.10.4 → 0.10.6

package/packages/memory-engine-v2/scripts/entity_resolution_v2.py

@@ -0,0 +1,1041 @@
+#!/usr/bin/env python3
+"""Entity-resolution v2: blocking + embedding similarity + LLM
+adjudication. Roadmap BET 1b — DRY-RUN TOOLING.
+
+What v1 (backfill_entity_reconciliation.py) covers: variants that share
+an exact normalized surface form (alias overlap) or were paired by a
+name↔email co-occurrence in an event. What it does NOT cover — and
+this script adds:
+
+  - "Johann_Boedecker"        (underscore separator)
+  - "Bödecker, Johann"        (diacritic + comma inversion)
+  - "Johann"                  (bare first name)
+  - "Johanna Phil"            (near-miss that must NOT merge)
+
+Pipeline (within ONE arena, person entities):
+
+  1. v1 signals first — co_occurrence + alias_overlap proposals are
+     IMPORTED from v1's machinery, unchanged. They outrank everything.
+  2. BLOCKING — candidate generation only, NEVER identity. Punctuation/
+     underscore strip, diacritic fold (NFD + strip combining), token
+     sort, char-trigram buckets. Block keys: first-token, last-token,
+     email local-part, trigram bucket — within (arena, entity_type).
+  3. EMBEDDING similarity within blocks (pluggable backend; the HTTP
+     backend hits an OpenAI-compatible /v1/embeddings endpoint given
+     via --embed-url — never hardcoded, never called from tests).
+     Cosine ≥ 0.92 → high-confidence; 0.75–0.92 → ambiguous band;
+     < 0.75 → drop.
+  4. LLM ADJUDICATION of the ambiguous band (Anthropic API, env
+     ANTHROPIC_API_KEY, model env-pinned, temperature 0). Strict JSON
+     {"same_person": "yes"|"no"|"unsure", "reason": ...}. "unsure"
+     NEVER merges — it lands in the human-review section. --no-llm
+     routes the whole band to human review.
+  5. BARE-FIRST-NAME POLICY — a single-token entity merges only if it
+     has exactly ONE candidate in its blocks AND adjudication == yes.
+  6. Tiered report (JSONL + markdown):
+     co_occurrence > alias_overlap > embedding_llm > heuristic.
+
+SAFETY (the engine is shared multi-tenant infra; the pip-agents arena
+is LEGACY/FROZEN and must be untouchable by construction):
+
+  - --arena is REQUIRED; every SQL statement this script issues is
+    arena-scoped (programmatically asserted — see ARENA_SCOPED_SQL +
+    assert_arena_scoped()).
+  - DRY-RUN BY DEFAULT. Without --apply the session is forced
+    READ ONLY at the Postgres level (SET default_transaction_read_only
+    = on) — structurally incapable of writing.
+  - --apply additionally REQUIRES --i-have-a-snapshot (operator
+    acknowledgment that a pg_dump snapshot exists). Refused otherwise,
+    before any connection is opened.
+
+Usage:
+
+    python3 entity_resolution_v2.py \\
+        --arena <arena-id> \\
+        --pg-dsn postgresql://... \\
+        --embed-url http://<embed-gateway>/v1/embeddings \\
+        [--no-llm]                    # route ambiguous band to human review
+        [--out /tmp/resolution.jsonl] # tiered merge-candidate report
+        [--summary /tmp/resolution.md]
+        [--apply --i-have-a-snapshot] # write (gated; see above)
+
+Exit codes: 0 success; 1 partial apply failure; 2 bad args / refused.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import math
+import os
+import re
+import sys
+import unicodedata
+import urllib.error
+import urllib.request
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+# ----------------------------------------------------------------------
+# Import v1's load/apply/report machinery (same dir; scripts/ is not a
+# package, so load by path). v1 stays the single owner of: entity
+# loading, co-occurrence collection, union-find proposal building,
+# richest-row-wins canonical selection, per-proposal transactional
+# apply, entity_merges audit + rollback_payload.
+# ----------------------------------------------------------------------
+
+_V1_PATH = Path(__file__).resolve().parent / "backfill_entity_reconciliation.py"
+if "backfill_entity_reconciliation" in sys.modules:
+    v1 = sys.modules["backfill_entity_reconciliation"]
+else:
+    _spec = importlib.util.spec_from_file_location(
+        "backfill_entity_reconciliation", _V1_PATH)
+    assert _spec and _spec.loader
+    v1 = importlib.util.module_from_spec(_spec)
+    # Register BEFORE exec: dataclass processing (py3.13+) looks the
+    # defining module up in sys.modules.
+    sys.modules["backfill_entity_reconciliation"] = v1
+    _spec.loader.exec_module(v1)
+
+Entity = v1.Entity
+MergeProposal = v1.MergeProposal
+psycopg = v1.psycopg  # None when the driver isn't installed (tests)
+
+
+# ----------------------------------------------------------------------
+# Thresholds & constants
+# ----------------------------------------------------------------------
+
+HIGH_THRESHOLD = 0.92    # >= : high-confidence candidate
+LOW_THRESHOLD = 0.75     # < : drop. [LOW, HIGH) : ambiguous band → LLM
+DEFAULT_TOP_K_FACTS = 8
+DEFAULT_MAX_BLOCK = 100  # blocks bigger than this are skipped for
+                         # pair generation (candidate gen, not recall-
+                         # critical: v1 signals still cover them)
+ADJUDICATION_SAMPLE_FACTS = 5
+
+LLM_MODEL_ENV = "ENTITY_RESOLUTION_LLM_MODEL"
+LLM_MODEL_DEFAULT = "claude-haiku-4-5"
+ANTHROPIC_URL = "https://api.anthropic.com/v1/messages"
+ANTHROPIC_VERSION = "2023-06-01"
+
+TIER_ORDER = ("co_occurrence", "alias_overlap", "embedding_llm", "heuristic")
+
+# ----------------------------------------------------------------------
+# Every SQL statement THIS script issues. All must be arena-scoped —
+# assert_arena_scoped() enforces it and the unit tests assert it too.
+# (v1's statements are arena-scoped at load + repoint; its by-id
+# entity UPDATE/DELETE statements operate only on ids returned by the
+# arena-scoped loads.)
+# ----------------------------------------------------------------------
+
+FACTS_FOR_ENTITY_SQL = """
+    SELECT statement FROM facts
+    WHERE arena = %s AND (subject_entity_id = %s OR object_entity_id = %s)
+    ORDER BY confidence DESC, asserted_at DESC
+    LIMIT %s
+"""
+
+ENTITY_COUNT_SQL = """
+    SELECT COUNT(*) AS n FROM entities
+    WHERE arena = %s AND entity_type = %s
+"""
+
+# Reads pg_catalog constraint metadata only — no tenant rows — so it
+# is exempt from the arena-scoping rule below.
+ENTITY_MERGES_CHECKDEF_SQL = """
+    SELECT pg_get_constraintdef(oid) AS def
+    FROM pg_constraint
+    WHERE conrelid = 'entity_merges'::regclass AND contype = 'c'
+"""
+
+ARENA_SCOPED_SQL: dict[str, str] = {
+    "facts_for_entity": FACTS_FOR_ENTITY_SQL,
+    "entity_count": ENTITY_COUNT_SQL,
+}
+
+
+def assert_arena_scoped() -> None:
+    """Every tenant-data SQL statement this script issues must contain
+    an arena predicate. Runs at startup; also unit-tested."""
+    for name, sql in ARENA_SCOPED_SQL.items():
+        if "arena = %s" not in sql:
+            raise AssertionError(
+                f"SQL '{name}' is not arena-scoped — refusing to run. "
+                f"Every statement must carry 'arena = %s'."
+            )
+
+
+# ----------------------------------------------------------------------
+# 1. Candidate-generation normalization — NEVER used for identity,
+#    ONLY for blocking. Identity stays with entity_id.py /
+#    v1._normalize_surface.
+# ----------------------------------------------------------------------
+
+_PUNCT_RE = re.compile(r"[^\w\s@]|_", re.UNICODE)
+_WS_RE = re.compile(r"\s+")
+
+
+def fold_diacritics(s: str) -> str:
+    """'Bödecker' → 'Bodecker' (NFD decompose, strip combining marks)."""
+    return "".join(
+        ch for ch in unicodedata.normalize("NFD", s)
+        if not unicodedata.combining(ch)
+    )
+
+
+def block_normalize(s: str) -> str:
+    """Blocking-only normal form: diacritic fold + lowercase +
+    punctuation/underscores → space + collapse whitespace.
+
+    'Johann_Boedecker'  → 'johann boedecker'
+    'Bödecker, Johann'  → 'bodecker johann'
+    """
+    s = fold_diacritics(unicodedata.normalize("NFKC", s or ""))
+    s = _PUNCT_RE.sub(" ", s.lower())
+    return _WS_RE.sub(" ", s).strip()
+
+
+def block_tokens(s: str) -> list[str]:
+    n = block_normalize(s)
+    return n.split(" ") if n else []
+
+
+def token_sort(s: str) -> str:
+    """Order-insensitive form: 'Bödecker, Johann' and
+    'Johann Boedecker' both sort to a stable token sequence."""
+    return " ".join(sorted(block_tokens(s)))
+
+
+def char_trigrams(s: str) -> set[str]:
+    """Trigrams over the token-sorted, space-stripped form. Catches
+    'boedecker' vs 'bodecker' (oe vs folded ö) via shared trigrams."""
+    joined = token_sort(s).replace(" ", "")
+    if len(joined) < 3:
+        return {joined} if joined else set()
+    return {joined[i:i + 3] for i in range(len(joined) - 2)}
+
+
+def _entity_surface_forms(e: Entity) -> list[str]:
+    """canonical + aliases + (for email forms) the local part, which is
+    itself a name-ish surface ('johann.boedecker@…' → 'johann boedecker')."""
+    forms = [e.canonical_name, *e.aliases]
+    extra: list[str] = []
+    for f in forms:
+        if v1._looks_like_email(f):
+            lp = v1._local_part(f)
+            if lp:
+                extra.append(lp)
+    return forms + extra
+
+
+def blocking_keys(e: Entity) -> set[str]:
+    """Block keys for one entity: first-token, last-token (of the
+    token-SORTED form), email local-part, char-trigram buckets."""
+    keys: set[str] = set()
+    for form in _entity_surface_forms(e):
+        if v1._looks_like_email(form):
+            lp = v1._local_part(form)
+            if lp:
+                keys.add("local:" + block_normalize(lp).replace(" ", ""))
+            continue
+        toks = sorted(block_tokens(form))
+        if not toks:
+            continue
+        keys.add("first:" + toks[0])
+        keys.add("last:" + toks[-1])
+        for tri in char_trigrams(form):
+            keys.add("tri:" + tri)
+    return keys
+
+
+def is_bare_name(e: Entity) -> bool:
+    """True when every non-email surface form is a single token
+    ('Johann'). Such entities are subject to the bare-first-name
+    policy (§4 of the module docstring)."""
+    name_forms = [f for f in [e.canonical_name, *e.aliases]
+                  if not v1._looks_like_email(f)]
+    if not name_forms:
+        return False
+    return all(len(block_tokens(f)) <= 1 for f in name_forms)
+
+
+@dataclass
+class CandidatePair:
+    a: Entity
+    b: Entity
+    shared_keys: set[str] = field(default_factory=set)
+    similarity: float | None = None
+    band: str | None = None          # 'high' | 'ambiguous' | 'drop'
+    verdict: str | None = None       # 'yes' | 'no' | 'unsure' | None
+    reason: str | None = None
+
+    @property
+    def key(self) -> frozenset:
+        return frozenset({self.a.id, self.b.id})
+
+
+def generate_candidate_pairs(
+    entities: list[Entity],
+    already_grouped: set[frozenset] | None = None,
+    max_block: int = DEFAULT_MAX_BLOCK,
+) -> list[CandidatePair]:
+    """Blocking: pair every two entities sharing >= 1 block key, within
+    the (already arena-scoped) entity list. Pairs already grouped by a
+    v1 signal are skipped (v1 outranks). Oversized blocks are skipped
+    for pair generation (candidate-gen recall guard, not identity)."""
+    already_grouped = already_grouped or set()
+    blocks: dict[str, list[Entity]] = defaultdict(list)
+    for e in entities:
+        for k in blocking_keys(e):
+            blocks[k].append(e)
+
+    pairs: dict[frozenset, CandidatePair] = {}
+    for k, members in blocks.items():
+        if len(members) < 2 or len(members) > max_block:
+            continue
+        for i in range(len(members)):
+            for j in range(i + 1, len(members)):
+                a, b = members[i], members[j]
+                fk = frozenset({a.id, b.id})
+                if len(fk) < 2 or fk in already_grouped:
+                    continue
+                if fk not in pairs:
+                    pairs[fk] = CandidatePair(a=a, b=b)
+                pairs[fk].shared_keys.add(k)
+    return sorted(pairs.values(), key=lambda p: sorted(p.key))
+
+
+# ----------------------------------------------------------------------
+# 2. Embedding-similarity stage — pluggable backend
+# ----------------------------------------------------------------------
+
+class EmbeddingBackend:
+    """Interface: embed(texts) -> list of vectors."""
+
+    def embed(self, texts: list[str]) -> list[list[float]]:  # pragma: no cover
+        raise NotImplementedError
+
+
+class HttpEmbeddingBackend(EmbeddingBackend):
+    """OpenAI-compatible /v1/embeddings endpoint (the engine's Qwen3
+    embed gateway). Endpoint comes from --embed-url — NEVER hardcoded.
+    NOT called in tests (tests use a fake backend)."""
+
+    def __init__(self, url: str, model: str | None = None,
+                 timeout: float = 30.0, batch_size: int = 32) -> None:
+        if not url:
+            raise ValueError("HttpEmbeddingBackend requires --embed-url")
+        self.url = url
+        self.model = model
+        self.timeout = timeout
+        self.batch_size = batch_size
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        out: list[list[float]] = []
+        for i in range(0, len(texts), self.batch_size):
+            batch = texts[i:i + self.batch_size]
+            body: dict = {"input": batch}
+            if self.model:
+                body["model"] = self.model
+            req = urllib.request.Request(
+                self.url,
+                data=json.dumps(body).encode(),
+                headers={"content-type": "application/json"},
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                payload = json.loads(resp.read())
+            data = sorted(payload["data"], key=lambda d: d.get("index", 0))
+            out.extend([d["embedding"] for d in data])
+        return out
+
+
+class LocalEmbeddingBackend(EmbeddingBackend):
+    """--embed-backend local. STUB: the repo carries no suitable local
+    CPU embedding dependency (requirements are psycopg/httpx/fastapi/
+    qdrant-client only — no sentence-transformers / fastembed / onnx
+    model). Rather than silently pulling a new heavyweight dep into
+    ops tooling, this stays a stub until one is deliberately added."""
+
+    def __init__(self, *_args, **_kwargs) -> None:
+        raise NotImplementedError(
+            "--embed-backend local: no local CPU embedding dependency "
+            "exists in this repo (checked: compat/extractor requirements "
+            "— psycopg, httpx, fastapi, qdrant-client only). Use "
+            "--embed-backend http with --embed-url pointing at the "
+            "engine's Qwen3 embed gateway, or add a small CPU model "
+            "dependency deliberately (e.g. fastembed) in its own PR."
+        )
+
+
+def cosine(a: list[float], b: list[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0.0 or nb == 0.0:
+        return 0.0
+    return dot / (na * nb)
+
+
+def embedding_bundle(e: Entity, fact_statements: list[str]) -> str:
+    """Surface-form bundle + top-K fact statements → one embeddable
+    text per entity."""
+    lines = [f"name: {e.canonical_name}"]
+    if e.aliases:
+        lines.append("aliases: " + "; ".join(e.aliases))
+    for s in fact_statements:
+        lines.append(f"fact: {s}")
+    return "\n".join(lines)
+
+
+def route_band(similarity: float,
+               high: float = HIGH_THRESHOLD,
+               low: float = LOW_THRESHOLD) -> str:
+    """Threshold routing: >= high → 'high'; [low, high) → 'ambiguous';
+    < low → 'drop'."""
+    if similarity >= high:
+        return "high"
+    if similarity >= low:
+        return "ambiguous"
+    return "drop"
+
+
+def load_fact_statements(conn, arena: str, entity_id: str,
+                         top_k: int = DEFAULT_TOP_K_FACTS) -> list[str]:
+    """Top-K fact statements for one entity. Arena-scoped."""
+    with conn.cursor() as cur:
+        cur.execute(FACTS_FOR_ENTITY_SQL,
+                    (arena, entity_id, entity_id, top_k))
+        return [r[0] for r in cur.fetchall()]
+
+
+# ----------------------------------------------------------------------
+# 3. LLM adjudication of the ambiguous band
+# ----------------------------------------------------------------------
+
+ADJUDICATION_PROMPT = """\
+You are adjudicating whether two database entity records refer to the \
+SAME real person. Be conservative: a false merge corrupts the knowledge \
+graph and is far worse than leaving a duplicate.
+
+Entity A:
+  canonical name: {a_name}
+  aliases: {a_aliases}
+  sample facts:
+{a_facts}
+
+Entity B:
+  canonical name: {b_name}
+  aliases: {b_aliases}
+  sample facts:
+{b_facts}
+
+Answer with STRICT JSON only, no prose, exactly this shape:
+{{"same_person": "yes" | "no" | "unsure", "reason": "<one sentence>"}}
+
+Rules:
+- "yes" only if the names are plausibly the same person AND nothing in \
+the facts contradicts it.
+- Different people who merely share a first name (e.g. "Johann" vs \
+"Johanna") are "no".
+- If the evidence is thin or conflicting, answer "unsure".
+"""
+
+
+@dataclass
+class Adjudication:
+    same_person: str   # 'yes' | 'no' | 'unsure'
+    reason: str
+
+
+class Adjudicator:
+    def adjudicate(self, a: Entity, a_facts: list[str],
+                   b: Entity, b_facts: list[str]) -> Adjudication:  # pragma: no cover
+        raise NotImplementedError
+
+
+class NoLLMAdjudicator(Adjudicator):
+    """--no-llm / offline mode: the whole ambiguous band routes to
+    human review ('unsure' never merges)."""
+
+    def adjudicate(self, a, a_facts, b, b_facts) -> Adjudication:
+        return Adjudication("unsure", "LLM adjudication disabled (--no-llm); "
+                                      "routed to human review")
+
+
+class AnthropicAdjudicator(Adjudicator):
+    """Anthropic API via env ANTHROPIC_API_KEY; model env-pinned
+    ($ENTITY_RESOLUTION_LLM_MODEL, default claude-haiku-4-5);
+    temperature 0. Strict-JSON response; any parse failure degrades to
+    'unsure' (never merges)."""
+
+    def __init__(self, api_key: str | None = None,
+                 model: str | None = None, timeout: float = 60.0) -> None:
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "ANTHROPIC_API_KEY not set — use --no-llm to route the "
+                "ambiguous band to human review instead.")
+        self.model = model or os.environ.get(LLM_MODEL_ENV, LLM_MODEL_DEFAULT)
+        self.timeout = timeout
+
+    @staticmethod
+    def _fmt_facts(facts: list[str]) -> str:
+        sample = facts[:ADJUDICATION_SAMPLE_FACTS]
+        if not sample:
+            return "    (no facts recorded)"
+        return "\n".join(f"    - {s}" for s in sample)
+
+    def adjudicate(self, a, a_facts, b, b_facts) -> Adjudication:
+        prompt = ADJUDICATION_PROMPT.format(
+            a_name=a.canonical_name, a_aliases=", ".join(a.aliases) or "(none)",
+            a_facts=self._fmt_facts(a_facts),
+            b_name=b.canonical_name, b_aliases=", ".join(b.aliases) or "(none)",
+            b_facts=self._fmt_facts(b_facts),
+        )
+        body = {
+            "model": self.model,
+            "max_tokens": 200,
+            "temperature": 0,
+            "messages": [{"role": "user", "content": prompt}],
+        }
+        req = urllib.request.Request(
+            ANTHROPIC_URL,
+            data=json.dumps(body).encode(),
+            headers={
+                "x-api-key": self.api_key,
+                "anthropic-version": ANTHROPIC_VERSION,
+                "content-type": "application/json",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                payload = json.loads(resp.read())
+            text = "".join(
+                blk.get("text", "") for blk in payload.get("content", [])
+                if blk.get("type") == "text"
+            )
+            return parse_adjudication(text)
+        except (urllib.error.URLError, TimeoutError, json.JSONDecodeError,
+                KeyError) as e:
+            return Adjudication("unsure", f"adjudication call failed: {e}")
+
+
+def parse_adjudication(text: str) -> Adjudication:
+    """Strict JSON {"same_person": yes|no|unsure, "reason": ...}.
+    Anything malformed → 'unsure' (never merges)."""
+    m = re.search(r"\{.*\}", text, re.DOTALL)
+    if not m:
+        return Adjudication("unsure", f"non-JSON adjudication output: {text[:120]!r}")
+    try:
+        obj = json.loads(m.group(0))
+    except json.JSONDecodeError:
+        return Adjudication("unsure", f"unparseable adjudication JSON: {text[:120]!r}")
+    verdict = obj.get("same_person")
+    if verdict not in ("yes", "no", "unsure"):
+        return Adjudication("unsure", f"invalid same_person value: {verdict!r}")
+    return Adjudication(verdict, str(obj.get("reason", ""))[:500])
+
+
+# ----------------------------------------------------------------------
+# 4. Pair routing: thresholds + adjudication + bare-first-name policy
+# ----------------------------------------------------------------------
+
+@dataclass
+class RoutedPairs:
+    merge: list[CandidatePair] = field(default_factory=list)
+    human_review: list[CandidatePair] = field(default_factory=list)
+    dropped: list[CandidatePair] = field(default_factory=list)
+
+
+def route_pairs(
+    pairs: list[CandidatePair],
+    adjudicator: Adjudicator,
+    facts_by_entity: dict[str, list[str]],
+    high: float = HIGH_THRESHOLD,
+    low: float = LOW_THRESHOLD,
+) -> RoutedPairs:
+    """Each pair must already carry .similarity. Routing:
+
+      - sim < low                          → dropped
+      - bare-name involved                 → ALWAYS adjudicated; merges
+        only on 'yes' AND (enforced later) exactly one candidate
+      - sim >= high, no bare name          → merge (high-confidence)
+      - low <= sim < high                  → adjudicate: yes → merge,
+        no → dropped, unsure → human review
+    """
+    routed = RoutedPairs()
+
+    # Bare-name candidate-count map (policy: exactly one candidate in
+    # block, counted over NON-dropped pairs).
+    bare_candidates: dict[str, int] = defaultdict(int)
+    for p in pairs:
+        assert p.similarity is not None, "route_pairs needs scored pairs"
+        if route_band(p.similarity, high, low) == "drop":
+            continue
+        for e in (p.a, p.b):
+            if is_bare_name(e):
+                bare_candidates[e.id] += 1
+
+    for p in pairs:
+        p.band = route_band(p.similarity, high, low)
+        if p.band == "drop":
+            routed.dropped.append(p)
+            continue
+
+        bare_ids = [e.id for e in (p.a, p.b) if is_bare_name(e)]
+        if bare_ids:
+            # Bare-first-name policy: single-token entities merge only
+            # if exactly one candidate in block AND adjudication = yes.
+            if any(bare_candidates[eid] != 1 for eid in bare_ids):
+                p.verdict = "unsure"
+                p.reason = ("bare-first-name policy: entity has more than "
+                            "one candidate in its blocks; left unmerged")
+                routed.human_review.append(p)
+                continue
+            adj = adjudicator.adjudicate(
+                p.a, facts_by_entity.get(p.a.id, []),
+                p.b, facts_by_entity.get(p.b.id, []))
+            p.verdict, p.reason = adj.same_person, adj.reason
+            if adj.same_person == "yes":
+                routed.merge.append(p)
+            elif adj.same_person == "no":
+                routed.dropped.append(p)
+            else:
+                routed.human_review.append(p)
+            continue
+
+        if p.band == "high":
+            p.verdict = "auto"
+            p.reason = (f"cosine similarity {p.similarity:.3f} >= "
+                        f"high-confidence threshold {high}")
+            routed.merge.append(p)
+            continue
+
+        # ambiguous band → LLM adjudication
+        adj = adjudicator.adjudicate(
+            p.a, facts_by_entity.get(p.a.id, []),
+            p.b, facts_by_entity.get(p.b.id, []))
+        p.verdict, p.reason = adj.same_person, adj.reason
+        if adj.same_person == "yes":
+            routed.merge.append(p)
+        elif adj.same_person == "no":
+            routed.dropped.append(p)
+        else:
+            routed.human_review.append(p)
+
+    return routed
+
+
+def pairs_to_proposals(merge_pairs: list[CandidatePair]) -> list[MergeProposal]:
+    """Union-find accepted pairs into groups; canonical = richest row
+    (same ordering as v1: facts desc, rels desc, provenance desc, id)."""
+    parent: dict[str, str] = {}
+    entities: dict[str, Entity] = {}
+
+    def find(x: str) -> str:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    for p in merge_pairs:
+        for e in (p.a, p.b):
+            parent.setdefault(e.id, e.id)
+            entities[e.id] = e
+        ra, rb = find(p.a.id), find(p.b.id)
+        if ra != rb:
+            parent[ra] = rb
+
+    groups: dict[str, list[Entity]] = defaultdict(list)
+    for eid in parent:
+        groups[find(eid)].append(entities[eid])
+
+    proposals: list[MergeProposal] = []
+    for group in groups.values():
+        if len(group) < 2:
+            continue
+        group_sorted = sorted(
+            group,
+            key=lambda e: (-e.fact_count, -e.rel_count,
+                           -len(e.provenance_event_ids), e.id),
+        )
+        proposals.append(MergeProposal(
+            canonical=group_sorted[0],
+            deprecated=group_sorted[1:],
+            signal="embedding_llm",
+        ))
+    return proposals
+
+
+# ----------------------------------------------------------------------
+# 5. Tiered report (JSONL + markdown)
+# ----------------------------------------------------------------------
+
+def _proposal_record(p: MergeProposal, tier: str,
+                     evidence: list[dict] | None = None) -> dict:
+    return {
+        "type": "merge_proposal",
+        "tier": tier,
+        "signal": p.signal,
+        "canonical": {
+            "id": p.canonical.id,
+            "canonical_name": p.canonical.canonical_name,
+            "fact_count": p.canonical.fact_count,
+            "rel_count": p.canonical.rel_count,
+        },
+        "deprecated": [
+            {
+                "id": d.id,
+                "canonical_name": d.canonical_name,
+                "aliases": d.aliases,
+                "fact_count": d.fact_count,
+                "rel_count": d.rel_count,
+            } for d in p.deprecated
+        ],
+        "evidence": evidence or [],
+    }
+
+
+def _pair_record(p: CandidatePair, record_type: str) -> dict:
+    return {
+        "type": record_type,
+        "a": {"id": p.a.id, "canonical_name": p.a.canonical_name},
+        "b": {"id": p.b.id, "canonical_name": p.b.canonical_name},
+        "similarity": p.similarity,
+        "band": p.band,
+        "verdict": p.verdict,
+        "reason": p.reason,
+        "shared_block_keys": sorted(p.shared_keys)[:10],
+    }
+
+
+def build_report_records(
+    arena: str,
+    v1_proposals: list[MergeProposal],
+    v2_proposals: list[MergeProposal],
+    routed: RoutedPairs,
+    before_count: int,
+    heuristic_proposals: list[MergeProposal] | None = None,
+) -> list[dict]:
+    """Tier order: co_occurrence > alias_overlap > embedding_llm >
+    heuristic. Returns JSONL-able records, header first."""
+    pair_evidence: dict[frozenset, dict] = {
+        p.key: _pair_record(p, "evidence") for p in routed.merge
+    }
+
+    records: list[dict] = []
+    deprecated_total = sum(
+        len(p.deprecated)
+        for p in [*v1_proposals, *v2_proposals, *(heuristic_proposals or [])]
+    )
+    records.append({
+        "type": "header",
+        "arena": arena,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "tiers": list(TIER_ORDER),
+        "entity_count_before": before_count,
+        "entity_count_after_if_applied": before_count - deprecated_total,
+        "other_arenas": "untouched — every SQL statement is arena-scoped "
+                        "(programmatically asserted; dry-run sessions are "
+                        "READ ONLY at the Postgres level)",
+    })
+
+    by_tier: list[tuple[str, list[MergeProposal]]] = [
+        ("co_occurrence", [p for p in v1_proposals if p.signal == "co_occurrence"]),
+        ("alias_overlap", [p for p in v1_proposals if p.signal == "alias_overlap"]),
+        ("embedding_llm", v2_proposals),
+        ("heuristic", heuristic_proposals or []),
+    ]
+    for tier, proposals in by_tier:
+        for p in proposals:
+            ev = []
+            if tier == "embedding_llm":
+                ids = {p.canonical.id, *(d.id for d in p.deprecated)}
+                ev = [rec for key, rec in pair_evidence.items() if key <= ids]
+            records.append(_proposal_record(p, tier, ev))
+
+    for p in routed.human_review:
+        records.append(_pair_record(p, "human_review"))
+    for p in routed.dropped:
+        records.append(_pair_record(p, "dropped"))
+    return records
+
+
+def write_jsonl(records: list[dict], path: str) -> None:
+    with open(path, "w") as f:
+        for r in records:
+            f.write(json.dumps(r) + "\n")
+
+
+def write_markdown_summary(records: list[dict], path: str) -> None:
+    header = records[0]
+    proposals = [r for r in records if r["type"] == "merge_proposal"]
+    review = [r for r in records if r["type"] == "human_review"]
+    dropped = [r for r in records if r["type"] == "dropped"]
+
+    lines = [
+        f"# Entity-resolution v2 — merge-candidate report",
+        "",
+        f"- **Arena:** `{header['arena']}` (one arena at a time; required `--arena`)",
+        f"- **Generated:** {header['generated_at']}",
+        f"- **Entities before:** {header['entity_count_before']}",
+        f"- **Entities after (if every proposal applied):** "
+        f"{header['entity_count_after_if_applied']}",
+        "",
+        "## Proposals by tier",
+        "",
+        "| tier | proposals | rows deprecated |",
+        "|---|---:|---:|",
+    ]
+    for tier in TIER_ORDER:
+        tier_props = [p for p in proposals if p["tier"] == tier]
+        lines.append(f"| {tier} | {len(tier_props)} | "
+                     f"{sum(len(p['deprecated']) for p in tier_props)} |")
+    lines += ["", "## Proposals", ""]
+    for p in proposals:
+        deps = ", ".join(f"`{d['canonical_name']}`" for d in p["deprecated"])
+        lines.append(f"- **[{p['tier']}]** `{p['canonical']['canonical_name']}` "
+                     f"absorbs {deps}")
+        for ev in p.get("evidence", []):
+            sim = f"{ev['similarity']:.3f}" if ev.get("similarity") is not None else "n/a"
+            lines.append(f"  - sim={sim} verdict={ev.get('verdict')} — "
+                         f"{ev.get('reason')}")
+    lines += ["", f"## Human review ({len(review)})", ""]
+    if not review:
+        lines.append("(none)")
+    for r in review:
+        sim = f"{r['similarity']:.3f}" if r.get("similarity") is not None else "n/a"
+        lines.append(f"- `{r['a']['canonical_name']}` ↔ "
+                     f"`{r['b']['canonical_name']}` (sim={sim}) — {r.get('reason')}")
+    lines += ["", f"## Dropped pairs: {len(dropped)}", ""]
+    lines += [
+        "## Other arenas",
+        "",
+        header["other_arenas"],
+        "",
+        "The pip-agents arena (LEGACY/FROZEN) is untouchable by "
+        "construction: no statement in this tool can address it unless "
+        "an operator passes `--arena pip-agents`, which the runbook "
+        "forbids.",
+    ]
+    with open(path, "w") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+# ----------------------------------------------------------------------
+# CLI
+# ----------------------------------------------------------------------
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--arena", required=True,
+                   help="arena id to resolve (REQUIRED; one at a time; "
+                        "every SQL statement is scoped to it)")
+    p.add_argument("--pg-dsn", default=os.environ.get("PG_DSN"),
+                   help="postgres DSN; defaults to $PG_DSN")
+    p.add_argument("--entity-type", default="person",
+                   help="entity type to resolve (default: person)")
+    p.add_argument("--apply", action="store_true",
+                   help="actually write merges; default is dry-run "
+                        "(READ ONLY session). Requires --i-have-a-snapshot.")
+    p.add_argument("--i-have-a-snapshot", action="store_true",
+                   help="operator acknowledgment that a pg_dump snapshot "
+                        "of org-model exists. --apply is refused without it.")
+    p.add_argument("--embed-url", default=None,
+                   help="OpenAI-compatible /v1/embeddings endpoint "
+                        "(the engine's Qwen3 embed gateway). Required for "
+                        "the http backend; never hardcoded.")
+    p.add_argument("--embed-backend", choices=("http", "local"),
+                   default="http",
+                   help="embedding backend (default http; 'local' is a "
+                        "stub — no suitable CPU dep in repo)")
+    p.add_argument("--embed-model", default=None,
+                   help="model name to pass to the embeddings endpoint "
+                        "(optional; gateway default if omitted)")
+    p.add_argument("--no-llm", action="store_true",
+                   help="offline mode: route the whole ambiguous band to "
+                        "human review instead of LLM adjudication")
+    p.add_argument("--high-threshold", type=float, default=HIGH_THRESHOLD)
+    p.add_argument("--low-threshold", type=float, default=LOW_THRESHOLD)
+    p.add_argument("--top-k-facts", type=int, default=DEFAULT_TOP_K_FACTS)
+    p.add_argument("--max-block", type=int, default=DEFAULT_MAX_BLOCK)
+    p.add_argument("--heuristic-merge", action="store_true",
+                   help="also include v1's heuristic tier (off by default)")
+    p.add_argument("--out", default=None,
+                   help="tiered merge-candidate report JSONL path")
+    p.add_argument("--summary", default=None,
+                   help="markdown summary path (default: <out>.md)")
+    p.add_argument("--merged-by", default=None,
+                   help="audit tag (default: resolution-v2-YYYY-MM)")
+    return p.parse_args(argv)
+
+
+def validate_args(args: argparse.Namespace) -> str | None:
+    """Returns an error string, or None when ok. Checked BEFORE any
+    connection is opened — --apply is structurally refused without the
+    snapshot acknowledgment."""
+    if args.apply and not args.i_have_a_snapshot:
+        return ("--apply requires --i-have-a-snapshot (operator "
+                "acknowledgment that a pg_dump snapshot of org-model "
+                "exists — see the memory clean-rebuild runbook). Refusing.")
+    if not args.pg_dsn:
+        return "--pg-dsn (or $PG_DSN) required"
+    if args.embed_backend == "http" and not args.embed_url:
+        return ("--embed-url required for the http embedding backend "
+                "(the endpoint is never hardcoded)")
+    if not (0.0 <= args.low_threshold <= args.high_threshold <= 1.0):
+        return "--low-threshold must be <= --high-threshold, both in [0,1]"
+    return None
+
+
+def _entity_merges_check_allows(conn, value: str) -> bool:
+    """True if the entity_merges merge_signal CHECK constraint admits
+    `value`. v2's 'embedding_llm' needs the draft migration in
+    resolution-queue-design.md applied first."""
+    with conn.cursor() as cur:
+        cur.execute(ENTITY_MERGES_CHECKDEF_SQL)
+        defs = [r[0] for r in cur.fetchall()]
+    return any(value in d for d in defs)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    err = validate_args(args)
+    if err:
+        print(f"error: {err}", file=sys.stderr)
+        return 2
+
+    if psycopg is None:
+        print("error: psycopg is required to run this script "
+              "(pip install 'psycopg[binary]')", file=sys.stderr)
+        return 2
+
+    assert_arena_scoped()
+
+    merged_by = args.merged_by or \
+        f"resolution-v2-{datetime.now(timezone.utc):%Y-%m}"
+
+    # Backends (constructed before connecting so misconfig fails fast).
+    try:
+        if args.embed_backend == "local":
+            backend: EmbeddingBackend = LocalEmbeddingBackend()
+        else:
+            backend = HttpEmbeddingBackend(args.embed_url, args.embed_model)
+        adjudicator: Adjudicator = (
+            NoLLMAdjudicator() if args.no_llm else AnthropicAdjudicator()
+        )
+    except (NotImplementedError, ValueError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    with psycopg.connect(args.pg_dsn, autocommit=False) as conn:
+        if not args.apply:
+            # Structural dry-run: the session cannot write.
+            conn.execute("SET default_transaction_read_only = on")
+        print(f"[resolution-v2] arena={args.arena} type={args.entity_type} "
+              f"apply={args.apply} no_llm={args.no_llm}")
+
+        entities = v1.load_entities(conn, args.arena, args.entity_type)
+        before_count = len(entities)
+        print(f"[resolution-v2] loaded {before_count} {args.entity_type} "
+              f"entities (arena-scoped)")
+
+        # ---- Tier 1+2 (and optional 4): v1's machinery, unchanged ----
+        cooc = v1.collect_cooccurrence_pairs(conn, args.arena) \
+            if args.entity_type == "person" else set()
+        v1_all = v1.build_proposals(entities, cooc, args.heuristic_merge)
+        v1_proposals = [p for p in v1_all
+                        if p.signal in ("co_occurrence", "alias_overlap")]
+        heuristic_proposals = [p for p in v1_all if p.signal == "heuristic"]
+        already = set()
+        for p in v1_all:
+            ids = [p.canonical.id, *(d.id for d in p.deprecated)]
+            for i in range(len(ids)):
+                for j in range(i + 1, len(ids)):
+                    already.add(frozenset({ids[i], ids[j]}))
+        print(f"[resolution-v2] v1 tiers: {len(v1_proposals)} proposals "
+              f"(+{len(heuristic_proposals)} heuristic)")
+
+        # ---- Blocking ------------------------------------------------
+        pairs = generate_candidate_pairs(entities, already, args.max_block)
+        print(f"[resolution-v2] blocking generated {len(pairs)} candidate "
+              f"pairs not covered by v1 signals")
+
+        # ---- Embedding similarity -------------------------------------
+        ids_needed = sorted({e.id for p in pairs for e in (p.a, p.b)})
+        facts_by_entity = {
+            eid: load_fact_statements(conn, args.arena, eid, args.top_k_facts)
+            for eid in ids_needed
+        }
+        ents_by_id = {e.id: e for e in entities}
+        bundles = [embedding_bundle(ents_by_id[eid], facts_by_entity[eid])
+                   for eid in ids_needed]
+        vectors = dict(zip(ids_needed, backend.embed(bundles))) \
+            if bundles else {}
+        for p in pairs:
+            p.similarity = cosine(vectors[p.a.id], vectors[p.b.id])
+
+        # ---- Routing: thresholds + adjudication + bare-name policy ----
+        routed = route_pairs(pairs, adjudicator, facts_by_entity,
+                             args.high_threshold, args.low_threshold)
+        v2_proposals = pairs_to_proposals(routed.merge)
+        print(f"[resolution-v2] embedding+llm tier: "
+              f"{len(v2_proposals)} proposals; "
+              f"{len(routed.human_review)} pairs → human review; "
+              f"{len(routed.dropped)} dropped")
+
+        # ---- Report ----------------------------------------------------
+        records = build_report_records(
+            args.arena, v1_proposals, v2_proposals, routed,
+            before_count, heuristic_proposals)
+        out = args.out or f"/tmp/entity_resolution_v2_{args.arena}.jsonl"
+        write_jsonl(records, out)
+        summary = args.summary or (out.rsplit(".", 1)[0] + ".md")
+        write_markdown_summary(records, summary)
+        print(f"[resolution-v2] report → {out}\n"
+              f"[resolution-v2] summary → {summary}")
+
+        if not args.apply:
+            print("[resolution-v2] dry-run only (session was READ ONLY); "
+                  "pass --apply --i-have-a-snapshot to execute")
+            return 0
+
+        # ---- Apply (gated) ---------------------------------------------
+        to_apply: list[MergeProposal] = [*v1_proposals, *heuristic_proposals]
+        skipped_v2 = 0
+        if v2_proposals:
+            if _entity_merges_check_allows(conn, "embedding_llm"):
+                to_apply.extend(v2_proposals)
+            else:
+                skipped_v2 = len(v2_proposals)
+                print("[resolution-v2] WARNING: entity_merges merge_signal "
+                      "CHECK does not admit 'embedding_llm' — the draft "
+                      "migration in resolution-queue-design.md must be "
+                      "applied first. Skipping the embedding_llm tier "
+                      f"({skipped_v2} proposals) to keep the audit honest.",
+                      file=sys.stderr)
+
+        succeeded, failed, errors = v1.apply_proposals(
+            conn, args.arena, to_apply, merged_by)
+        conn.commit()
+        with conn.cursor() as cur:
+            cur.execute(ENTITY_COUNT_SQL, (args.arena, args.entity_type))
+            after = cur.fetchone()[0]
+        print(f"[resolution-v2] applied: {succeeded} succeeded, "
+              f"{failed} failed; entities {before_count} → {after}")
+        for e in errors[:20]:
+            print(f"  ERR: {e}")
+        return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())