@pentatonic-ai/ai-agent-sdk 0.10.7 → 0.10.9

package/packages/memory-engine-v2/fusion_drive/adjudicate.py

@@ -0,0 +1,85 @@
+"""Fusion Drive — LLM adjudication via the self-hosted distiller (no egress).
+
+When fusion's deterministic tiers (exact-name, cross-run-shared-provenance,
+exact-triple facts) leave AMBIGUOUS candidates — two entities in the
+0.75–0.92 embedding band, or two facts that look like the same assertion in
+different words — we ask the **in-VPC distiller** (Qwen3.6-27B-FP8, the same
+LLM that extracted this content) to adjudicate. Using the distiller instead
+of a hosted API means the memory content NEVER leaves the VPC: no third-party
+egress, no disclosure_class sign-off, no per-token cost.
+
+This module is pure: the HTTP call is injected (`post_fn`), so verdict parsing
+and prompt construction are unit-tested without a GPU. The caller supplies a
+`post_fn(messages) -> str` that hits the distiller's OpenAI /v1/chat/completions
+(temperature 0, chat_template_kwargs enable_thinking=false — same shape the
+worker uses). If post_fn raises / returns None, adjudication is treated as
+UNSURE (never auto-merge on an LLM failure) — graceful degradation when no
+distiller box is up.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+# Conservative default: anything that isn't a clear "yes" does NOT merge.
+ENTITY_PROMPT = (
+    "You decide whether two extracted entities refer to the SAME real-world "
+    "thing. Be conservative: only say yes if you are confident they are the "
+    "same. Two different people who merely share a first name are NOT the same.\n\n"
+    "Entity A: type={a_type} name={a_name} aliases={a_aliases}\n"
+    "Context A (facts mentioning A): {a_ctx}\n\n"
+    "Entity B: type={b_type} name={b_name} aliases={b_aliases}\n"
+    "Context B (facts mentioning B): {b_ctx}\n\n"
+    'Reply with ONLY a JSON object: {{"same": true|false, "reason": "<short>"}}'
+)
+
+FACT_PROMPT = (
+    "You decide whether two statements assert the SAME fact (same subject, "
+    "same claim), even if worded differently. Be conservative.\n\n"
+    "Statement A: {a}\n"
+    "Statement B: {b}\n\n"
+    'Reply with ONLY a JSON object: {{"same": true|false, "reason": "<short>"}}'
+)
+
+
+def _parse_verdict(raw: str | None) -> dict:
+    """Parse the model's JSON verdict. Anything unparseable / non-affirmative
+    → {'same': False} (fail closed — never merge on doubt)."""
+    if not raw:
+        return {"same": False, "reason": "no response (unsure)"}
+    m = re.search(r"\{.*\}", raw, re.DOTALL)
+    if not m:
+        return {"same": False, "reason": "unparseable verdict"}
+    try:
+        v = json.loads(m.group(0))
+    except ValueError:
+        return {"same": False, "reason": "invalid json verdict"}
+    return {"same": bool(v.get("same") is True), "reason": str(v.get("reason", ""))[:200]}
+
+
+def adjudicate_entities(a: dict, b: dict, post_fn) -> dict:
+    """a/b: {entity_type, canonical_name, aliases, context (list[str] of facts)}.
+    Returns {'same': bool, 'reason': str}. Fail-closed on any error."""
+    msg = ENTITY_PROMPT.format(
+        a_type=a.get("entity_type"), a_name=a.get("canonical_name"),
+        a_aliases=", ".join(a.get("aliases") or []) or "(none)",
+        a_ctx=" | ".join((a.get("context") or [])[:5]) or "(none)",
+        b_type=b.get("entity_type"), b_name=b.get("canonical_name"),
+        b_aliases=", ".join(b.get("aliases") or []) or "(none)",
+        b_ctx=" | ".join((b.get("context") or [])[:5]) or "(none)",
+    )
+    try:
+        raw = post_fn([{"role": "user", "content": msg}])
+    except Exception:
+        return {"same": False, "reason": "adjudicator unreachable (unsure)"}
+    return _parse_verdict(raw)
+
+
+def adjudicate_facts(stmt_a: str, stmt_b: str, post_fn) -> dict:
+    msg = FACT_PROMPT.format(a=stmt_a, b=stmt_b)
+    try:
+        raw = post_fn([{"role": "user", "content": msg}])
+    except Exception:
+        return {"same": False, "reason": "adjudicator unreachable (unsure)"}
+    return _parse_verdict(raw)

package/packages/memory-engine-v2/fusion_drive/canonical.py

@@ -0,0 +1,94 @@
+"""Fusion Drive — scored canonical-node selection (pure functions).
+
+When fusion decides a set of entities are the same real thing, ONE becomes
+the master (canonical) and the rest become its aliases. entity_resolution_v2
+(#82) currently picks "richest-row-wins", which crowns the typo "Phil
+Mossop" over "Philip Mossop" if the typo's row happens to be richer. This
+replaces that with a scored pick whose dominant signal is an authoritative
+directory match — so when an org directory / CRM knows the real name, it
+wins regardless of row richness. See RFC-fusion-drive.md A3.
+
+Pure: all external signals (directory membership, grounding, teacher
+recency) are passed in, so this is fully unit-testable without DB/LLM.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+# Scoring weights. Directory anchoring dominates everything (a known-good
+# authoritative name beats any heuristic); penalties for ID-like / bare /
+# hallucinated names are large enough to sink an otherwise-rich row.
+W_DIRECTORY = 100.0      # name matches an org-directory / CRM contact
+W_GROUNDED = 10.0        # name appears verbatim in a provenance event
+W_TEACHER_RECENCY = 8.0  # extracted by the current (not superseded) teacher
+W_PER_CORROBORATION = 1.0
+CORROBORATION_CAP = 10.0
+P_LOOKS_LIKE_ID = 60.0   # name is mostly digits (numeric-ID-as-person)
+P_HALLUCINATED_EMAIL = 25.0
+P_BARE_SINGLE_TOKEN = 5.0
+
+
+@dataclass
+class CanonicalCandidate:
+    """One entity in a fuse-set, plus the resolved external signals."""
+    entity_id: str
+    canonical_name: str
+    n_provenance: int = 1
+    in_directory: bool = False     # authoritative match (HubSpot contact, etc.)
+    grounded: bool = False         # name verbatim in a provenance event
+    from_current_teacher: bool = False
+    hallucinated_email: bool = False
+    aliases: list[str] = field(default_factory=list)
+
+
+def _digit_ratio(s: str) -> float:
+    stripped = re.sub(r"\s+", "", s)
+    if not stripped:
+        return 1.0
+    return sum(c.isdigit() for c in stripped) / len(stripped)
+
+
+def looks_like_id(name: str) -> bool:
+    """Mostly-digit names are extractor noise (numeric IDs mistyped as
+    people), not real canonical names."""
+    return _digit_ratio(name) > 0.5
+
+
+def is_bare_single_token(name: str) -> bool:
+    return len(name.split()) == 1
+
+
+def canonical_score(c: CanonicalCandidate) -> float:
+    score = 0.0
+    if c.in_directory:
+        score += W_DIRECTORY
+    if c.grounded:
+        score += W_GROUNDED
+    if c.from_current_teacher:
+        score += W_TEACHER_RECENCY
+    score += min(CORROBORATION_CAP, W_PER_CORROBORATION * max(0, c.n_provenance))
+    if looks_like_id(c.canonical_name):
+        score -= P_LOOKS_LIKE_ID
+    if c.hallucinated_email:
+        score -= P_HALLUCINATED_EMAIL
+    if is_bare_single_token(c.canonical_name):
+        score -= P_BARE_SINGLE_TOKEN
+    return round(score, 4)
+
+
+def pick_master(candidates: list[CanonicalCandidate]) -> tuple[CanonicalCandidate, list[CanonicalCandidate]]:
+    """Return (master, losers). Master = highest canonical_score; ties
+    break toward more provenance, then longer name (stable, deterministic).
+    Losers' surface forms become aliases on the master downstream."""
+    if not candidates:
+        raise ValueError("pick_master requires at least one candidate")
+    ranked = sorted(
+        candidates,
+        # Final key is entity_id so a total tie is resolved deterministically
+        # regardless of input order (stable sort alone would leak order).
+        key=lambda c: (canonical_score(c), c.n_provenance, len(c.canonical_name), c.entity_id),
+        reverse=True,
+    )
+    return ranked[0], ranked[1:]

package/packages/memory-engine-v2/fusion_drive/conftest.py

@@ -0,0 +1,8 @@
+"""Put this package dir on sys.path so the flat sibling imports in the
+test modules (`import salience`, `from canonical import ...`) resolve no
+matter which directory pytest is invoked from."""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(__file__))

package/packages/memory-engine-v2/fusion_drive/merge.py

@@ -0,0 +1,178 @@
+"""Fusion Drive — merge & eviction PLAN builders (pure functions).
+
+The risky part of fusion/eviction is mutating prod rows: repointing facts
+and relationships off a deprecated entity, summing relationship weights on
+collision, unioning aliases/provenance, and deleting the right rows with a
+recoverable receipt. We isolate ALL of that decision-making into pure plan
+builders here (no DB), so it's exhaustively unit-testable; the scripts then
+execute the returned plan inside a single transaction.
+
+A plan is a dict of explicit operations. The executor performs them in order
+and is otherwise dumb. Nothing here touches a database or a clock.
+See RFC-fusion-drive.md Parts A4/A5 + B3.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# ── entity fusion plan ───────────────────────────────────────────────
+@dataclass
+class EntityMergePlan:
+    arena: str
+    master_id: str
+    # master row mutations
+    master_aliases: list[str]
+    master_provenance: list[str]
+    # repoints: (table, column, from_id) -> master_id
+    fact_subject_repoints: list[str] = field(default_factory=list)   # fact ids
+    fact_object_repoints: list[str] = field(default_factory=list)
+    rel_endpoint_repoints: list[str] = field(default_factory=list)   # rel ids simply repointed
+    rel_collisions: list[dict] = field(default_factory=list)         # {keep, drop, summed_weight, provenance}
+    deprecated_entity_ids: list[str] = field(default_factory=list)
+    audit_rows: list[dict] = field(default_factory=list)             # entity_merges rows
+
+
+def _union(*lists: list[str]) -> list[str]:
+    seen: dict[str, None] = {}
+    for lst in lists:
+        for x in lst or []:
+            if x not in seen:
+                seen[x] = None
+    return list(seen.keys())
+
+
+def build_entity_merge_plan(
+    *,
+    arena: str,
+    master: dict,
+    losers: list[dict],
+    facts: list[dict],
+    relationships: list[dict],
+    merge_signal: str = "online_resolver",
+) -> EntityMergePlan:
+    """Compute every mutation to fold `losers` into `master`.
+
+    master/losers: {id, canonical_name, aliases, provenance_event_ids}
+    facts: {id, subject_entity_id, object_entity_id} touching any loser
+    relationships: {id, from_entity_id, to_entity_id, relationship_type,
+                    weight, provenance_event_ids} touching any loser
+    """
+    loser_ids = {l["id"] for l in losers}
+    if master["id"] in loser_ids:
+        raise ValueError("master cannot also be a loser")
+
+    # master accretes every loser's surface form + provenance
+    aliases = _union(
+        master.get("aliases", []),
+        [l["canonical_name"] for l in losers],
+        *[l.get("aliases", []) for l in losers],
+    )
+    # don't list the master's own canonical_name as an alias of itself
+    aliases = [a for a in aliases if a != master["canonical_name"]]
+    provenance = _union(
+        master.get("provenance_event_ids", []),
+        *[l.get("provenance_event_ids", []) for l in losers],
+    )
+
+    plan = EntityMergePlan(
+        arena=arena,
+        master_id=master["id"],
+        master_aliases=aliases,
+        master_provenance=provenance,
+        deprecated_entity_ids=sorted(loser_ids),
+    )
+
+    # facts: repoint subject/object off losers onto master
+    for f in facts:
+        if f.get("subject_entity_id") in loser_ids:
+            plan.fact_subject_repoints.append(f["id"])
+        if f.get("object_entity_id") in loser_ids:
+            plan.fact_object_repoints.append(f["id"])
+
+    # relationships: repoint endpoints; a repoint can collide with an
+    # existing rel of the same (from,to,type) → keep one, sum weights,
+    # union provenance, drop the other. Detect collisions on the
+    # post-repoint key.
+    def repointed_key(r: dict) -> tuple:
+        frm = master["id"] if r["from_entity_id"] in loser_ids else r["from_entity_id"]
+        to = master["id"] if r["to_entity_id"] in loser_ids else r["to_entity_id"]
+        return (frm, to, r["relationship_type"])
+
+    by_key: dict[tuple, dict] = {}
+    for r in relationships:
+        touches = r["from_entity_id"] in loser_ids or r["to_entity_id"] in loser_ids
+        key = repointed_key(r)
+        if key in by_key:
+            keep = by_key[key]
+            plan.rel_collisions.append({
+                "keep": keep["id"],
+                "drop": r["id"],
+                "summed_weight": round(keep.get("weight", 1.0) + r.get("weight", 1.0), 4),
+                "provenance": _union(keep.get("provenance_event_ids", []),
+                                     r.get("provenance_event_ids", [])),
+            })
+        else:
+            by_key[key] = r
+            if touches:
+                plan.rel_endpoint_repoints.append(r["id"])
+
+    # audit + rollback receipt, one per deprecated entity
+    for l in losers:
+        plan.audit_rows.append({
+            "arena": arena,
+            "canonical_id": master["id"],
+            "deprecated_id": l["id"],
+            "deprecated_canonical_name": l["canonical_name"],
+            "deprecated_aliases": l.get("aliases", []),
+            "merge_signal": merge_signal,
+            "rollback_payload": l,  # full row, sufficient to recreate
+        })
+    return plan
+
+
+# ── fact fusion plan (exact-triple dupes) ────────────────────────────
+def build_fact_merge_plan(*, arena: str, dup_facts: list[dict]) -> dict | None:
+    """`dup_facts` all share (arena, subject, predicate, object). Master =
+    highest confidence, then longest statement (most informative), then id.
+    Others' provenance is unioned into the master; they are deleted."""
+    if len(dup_facts) < 2:
+        return None
+    ranked = sorted(
+        dup_facts,
+        key=lambda f: (f.get("confidence", 0.0), len(f.get("statement", "")), f["id"]),
+        reverse=True,
+    )
+    master, losers = ranked[0], ranked[1:]
+    provenance = _union(master.get("provenance_event_ids", []),
+                        *[l.get("provenance_event_ids", []) for l in losers])
+    return {
+        "arena": arena,
+        "master_id": master["id"],
+        "master_provenance": provenance,
+        "deprecated_ids": [l["id"] for l in losers],
+        "audit_rows": [{
+            "arena": arena,
+            "canonical_id": master["id"],
+            "deprecated_id": l["id"],
+            "deprecated_statement": l.get("statement", ""),
+            "merge_signal": "exact_triple",
+            "provenance_unioned": len(l.get("provenance_event_ids", [])),
+            "rollback_payload": l,
+        } for l in losers],
+    }
+
+
+# ── eviction plan ────────────────────────────────────────────────────
+def build_eviction_receipt(node_kind: str, row: dict) -> dict:
+    """A node_evictions audit row carrying enough to recreate the deleted
+    node. The executor only deletes nodes the salience pass already
+    classified evictable; this just packages the rollback receipt."""
+    return {
+        "node_kind": node_kind,          # entity | fact | relationship
+        "node_id": row["id"],
+        "arena": row["arena"],
+        "rollback_payload": row,
+    }

package/packages/memory-engine-v2/fusion_drive/salience.py

@@ -0,0 +1,118 @@
+"""Fusion Drive — salience scoring + time decay (pure functions).
+
+Salience is a node's RETENTION PRIORITY (0..1), distinct from a fact's
+`confidence` (which means corroboration/truth and only moves up). Salience
+is seeded at birth from extraction-quality signals, decays with time since
+last activity on a per-category half-life, and is reset/raised by
+re-corroboration or retrieval. Eviction (a later phase) keys on salience.
+
+Everything here is a pure function — no DB, no clock — so the decay pass
+just supplies `now` and the stored fields. See RFC-fusion-drive.md Part B.
+"""
+
+from __future__ import annotations
+
+# ── born salience ────────────────────────────────────────────────────
+# A node is born at BASE, nudged up by corroboration and down by each
+# extraction-quality red flag. Junk (noise name, numeric-ID person,
+# hallucinated email, ungrounded) is born near the floor so it decays
+# below the eviction threshold fast even with no fusion match — this is
+# the "born-low" mechanism that lets decay target pollution rather than
+# just age everything on the same clock.
+BASE_SALIENCE = 0.50
+CORROB_PER_SOURCE = 0.10   # each extra corroborating event
+CORROB_CAP = 0.30          # max uplift from corroboration
+SALIENCE_FLOOR = 0.01
+SALIENCE_CEIL = 1.00
+
+# Quality penalties (subtracted from born salience). Tuned so any single
+# hard-junk signal alone lands a node below the nominal 0.3 decay-sweep
+# threshold; combined signals drive it to the floor.
+QUALITY_PENALTIES = {
+    "noise_name": 0.45,          # noise_filter.is_noise_entity_name hit
+    "numeric_id_person": 0.45,   # person whose name is mostly digits (ID-as-person)
+    "hallucinated_email": 0.40,  # email not present in any provenance event
+    "ungrounded": 0.35,          # name/statement not substring of any source
+    "subject_undeclared": 0.25,  # fact subject not among the event's entities
+    "low_signal": 0.15,          # extracted from <60 chars of content
+}
+
+
+def _clamp(x: float) -> float:
+    return max(SALIENCE_FLOOR, min(SALIENCE_CEIL, x))
+
+
+def born_salience(*, n_sources: int = 1, quality_flags: list[str] | None = None) -> float:
+    """Salience to stamp on a freshly extracted node.
+
+    n_sources: corroborating events (cardinality of provenance).
+    quality_flags: subset of QUALITY_PENALTIES keys that fired for this node.
+    """
+    s = BASE_SALIENCE
+    if n_sources > 1:
+        s += min(CORROB_CAP, CORROB_PER_SOURCE * (n_sources - 1))
+    for flag in quality_flags or []:
+        s -= QUALITY_PENALTIES.get(flag, 0.0)
+    return round(_clamp(s), 4)
+
+
+# ── time decay ───────────────────────────────────────────────────────
+# Half-lives in DAYS, by fact category (entities/relationships use the
+# kind-level defaults). Durable categories (decisions, commitments) are
+# effectively non-decaying; ephemeral ones (mentions, observations) fade
+# in weeks. These are starting constants — Part B open question flags a
+# calibration pass against real arenas.
+FACT_HALF_LIFE_DAYS = {
+    "decision": 3650,
+    "commitment": 3650,
+    "state": 180,
+    "preference": 180,
+    "mention": 30,
+    "observation": 30,
+}
+FACT_HALF_LIFE_DEFAULT = 90
+ENTITY_HALF_LIFE_DAYS = 365
+RELATIONSHIP_HALF_LIFE_DAYS = 180
+
+
+def half_life_days(kind: str, category: str | None = None) -> float:
+    """kind ∈ {'fact','entity','relationship'}. category only used for facts."""
+    if kind == "fact":
+        return FACT_HALF_LIFE_DAYS.get((category or "").lower(), FACT_HALF_LIFE_DEFAULT)
+    if kind == "entity":
+        return ENTITY_HALF_LIFE_DAYS
+    if kind == "relationship":
+        return RELATIONSHIP_HALF_LIFE_DAYS
+    return FACT_HALF_LIFE_DEFAULT
+
+
+def decayed_salience(salience0: float, age_days: float, hl_days: float) -> float:
+    """Exponential half-life decay. age_days is time since the most recent
+    of (last_accessed, last_seen/asserted) — i.e. the clock resets on
+    access or re-corroboration, so used/reconfirmed memories don't fade."""
+    if age_days <= 0 or hl_days <= 0:
+        return round(_clamp(salience0), 4)
+    return round(_clamp(salience0 * (0.5 ** (age_days / hl_days))), 4)
+
+
+# ── eviction predicate (computed in Phase 1, ACTED ON in a later phase) ─
+EVICT_THRESHOLD = 0.05     # salience below this → eviction candidate
+EVICT_MIN_AGE_DAYS = 30    # ...and untouched at least this long
+
+
+def is_evictable(
+    *,
+    current_salience: float,
+    age_days: float,
+    referenced_by_live_node: bool,
+    disclosure_class: str = "private",
+) -> bool:
+    """An entity that is the subject/object of a surviving higher-salience
+    fact is NOT evictable (would orphan the fact). Restricted disclosure is
+    never auto-evicted (needs sign-off). Phase 1 only REPORTS this; the
+    decay pass does not delete until a later flagged phase."""
+    if disclosure_class == "restricted":
+        return False
+    if referenced_by_live_node:
+        return False
+    return current_salience < EVICT_THRESHOLD and age_days >= EVICT_MIN_AGE_DAYS

package/packages/memory-engine-v2/fusion_drive/test_adjudicate.py

@@ -0,0 +1,65 @@
+"""Unit tests for distiller-based adjudication (pure; post_fn injected)."""
+
+from __future__ import annotations
+
+from adjudicate import adjudicate_entities, adjudicate_facts, _parse_verdict
+
+
+class TestParseVerdict:
+    def test_clean_yes(self):
+        assert _parse_verdict('{"same": true, "reason": "same person"}')["same"] is True
+
+    def test_clean_no(self):
+        assert _parse_verdict('{"same": false, "reason": "different"}')["same"] is False
+
+    def test_prose_wrapped_json(self):
+        assert _parse_verdict('Sure: {"same": true, "reason": "x"} done')["same"] is True
+
+    def test_none_is_unsure_false(self):
+        assert _parse_verdict(None)["same"] is False
+
+    def test_unparseable_is_false(self):
+        assert _parse_verdict("yeah probably the same tbh")["same"] is False
+
+    def test_invalid_json_is_false(self):
+        assert _parse_verdict('{"same": tru')["same"] is False
+
+    def test_missing_same_key_is_false(self):
+        assert _parse_verdict('{"reason": "hmm"}')["same"] is False
+
+
+class TestAdjudicateEntities:
+    def test_yes_path(self):
+        post = lambda msgs: '{"same": true, "reason": "same"}'
+        v = adjudicate_entities({"canonical_name": "Phil"}, {"canonical_name": "Philip"}, post)
+        assert v["same"] is True
+
+    def test_post_fn_raises_is_failclosed(self):
+        def boom(msgs):
+            raise RuntimeError("no distiller up")
+        v = adjudicate_entities({"canonical_name": "A"}, {"canonical_name": "B"}, boom)
+        assert v["same"] is False and "unsure" in v["reason"]
+
+    def test_prompt_includes_both_entities(self):
+        captured = {}
+        def post(msgs):
+            captured["content"] = msgs[0]["content"]
+            return '{"same": false}'
+        adjudicate_entities(
+            {"entity_type": "person", "canonical_name": "Katie Cooper", "aliases": ["KC"],
+             "context": ["Katie organised Ramen Day"]},
+            {"entity_type": "person", "canonical_name": "1716801984", "context": []},
+            post,
+        )
+        assert "Katie Cooper" in captured["content"] and "1716801984" in captured["content"]
+
+
+class TestAdjudicateFacts:
+    def test_same_assertion(self):
+        post = lambda msgs: '{"same": true, "reason": "same claim"}'
+        assert adjudicate_facts("joined Acme", "works at Acme", post)["same"] is True
+
+    def test_unreachable_is_failclosed(self):
+        def boom(msgs):
+            raise ConnectionError()
+        assert adjudicate_facts("a", "b", boom)["same"] is False

package/packages/memory-engine-v2/fusion_drive/test_canonical.py

@@ -0,0 +1,76 @@
+"""Unit tests for Fusion Drive scored canonical selection (pure, no DB)."""
+
+from __future__ import annotations
+
+from canonical import CanonicalCandidate, canonical_score, pick_master, looks_like_id
+
+
+class TestLooksLikeId:
+    def test_pure_digits(self):
+        assert looks_like_id("1716801984")
+
+    def test_real_name(self):
+        assert not looks_like_id("Katie Cooper")
+
+    def test_mostly_digits(self):
+        assert looks_like_id("user 90210 33")
+
+
+class TestCanonicalScore:
+    def test_directory_match_dominates(self):
+        directoried = CanonicalCandidate("e1", "Philip Mossop", in_directory=True)
+        rich_typo = CanonicalCandidate("e2", "Phil Mossop", n_provenance=50, grounded=True)
+        assert canonical_score(directoried) > canonical_score(rich_typo)
+
+    def test_numeric_id_person_heavily_penalised(self):
+        idp = CanonicalCandidate("e1", "1716801984", n_provenance=20)
+        real = CanonicalCandidate("e2", "Katie Cooper", n_provenance=1)
+        assert canonical_score(real) > canonical_score(idp)
+
+    def test_current_teacher_beats_superseded_when_otherwise_equal(self):
+        new = CanonicalCandidate("e1", "Acme Corp", from_current_teacher=True)
+        old = CanonicalCandidate("e2", "Acme Corp", from_current_teacher=False)
+        assert canonical_score(new) > canonical_score(old)
+
+    def test_hallucinated_email_penalised(self):
+        clean = CanonicalCandidate("e1", "Sam Patel")
+        halluc = CanonicalCandidate("e2", "Sam Patel", hallucinated_email=True)
+        assert canonical_score(clean) > canonical_score(halluc)
+
+
+class TestPickMaster:
+    def test_the_phil_mossop_typo_case(self):
+        # The exact regression the RFC calls out: directory-known correct
+        # spelling must win over a richer typo row.
+        cands = [
+            CanonicalCandidate("typo", "Phil Mossop", n_provenance=40, grounded=True),
+            CanonicalCandidate("real", "Philip Mossop", n_provenance=3, in_directory=True),
+        ]
+        master, losers = pick_master(cands)
+        assert master.entity_id == "real"
+        assert [l.entity_id for l in losers] == ["typo"]
+
+    def test_numeric_id_loses_to_real_name(self):
+        cands = [
+            CanonicalCandidate("idp", "1716801984", n_provenance=30),
+            CanonicalCandidate("named", "Katie Cooper", n_provenance=2, grounded=True),
+        ]
+        master, _ = pick_master(cands)
+        assert master.entity_id == "named"
+
+    def test_single_candidate_is_its_own_master(self):
+        c = CanonicalCandidate("solo", "Solo Entity")
+        master, losers = pick_master([c])
+        assert master is c and losers == []
+
+    def test_deterministic_tie_break(self):
+        a = CanonicalCandidate("a", "Acme", n_provenance=5)
+        b = CanonicalCandidate("b", "Acme", n_provenance=5)
+        m1, _ = pick_master([a, b])
+        m2, _ = pick_master([b, a])
+        assert m1.entity_id == m2.entity_id  # order-independent
+
+    def test_empty_raises(self):
+        import pytest
+        with pytest.raises(ValueError):
+            pick_master([])