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

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_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([])

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

@@ -0,0 +1,112 @@
+"""Unit tests for Fusion Drive merge & eviction plan builders (pure, no DB)."""
+
+from __future__ import annotations
+
+import pytest
+from merge import build_entity_merge_plan, build_fact_merge_plan, build_eviction_receipt
+
+
+def _ent(id, name, aliases=None, prov=None):
+    return {"id": id, "canonical_name": name, "aliases": aliases or [], "provenance_event_ids": prov or []}
+
+
+class TestEntityMergePlan:
+    def test_aliases_and_provenance_union(self):
+        master = _ent("m", "Philip Mossop", aliases=["P. Mossop"], prov=["e1"])
+        loser = _ent("l", "Phil Mossop", aliases=["phil"], prov=["e2", "e1"])
+        plan = build_entity_merge_plan(arena="a", master=master, losers=[loser], facts=[], relationships=[])
+        # loser's canonical + aliases fold into master aliases; master's own name excluded
+        assert "Phil Mossop" in plan.master_aliases
+        assert "phil" in plan.master_aliases
+        assert "Philip Mossop" not in plan.master_aliases
+        # provenance deduped union
+        assert sorted(plan.master_provenance) == ["e1", "e2"]
+        assert plan.deprecated_entity_ids == ["l"]
+
+    def test_fact_subject_and_object_repoints(self):
+        master, loser = _ent("m", "Acme"), _ent("l", "ACME Inc")
+        facts = [
+            {"id": "f1", "subject_entity_id": "l", "object_entity_id": None},
+            {"id": "f2", "subject_entity_id": "x", "object_entity_id": "l"},
+            {"id": "f3", "subject_entity_id": "x", "object_entity_id": "y"},  # untouched
+        ]
+        plan = build_entity_merge_plan(arena="a", master=master, losers=[loser], facts=facts, relationships=[])
+        assert plan.fact_subject_repoints == ["f1"]
+        assert plan.fact_object_repoints == ["f2"]
+
+    def test_relationship_repoint_without_collision(self):
+        master, loser = _ent("m", "Bob"), _ent("l", "Bobby")
+        rels = [{"id": "r1", "from_entity_id": "l", "to_entity_id": "z",
+                 "relationship_type": "works_for", "weight": 2.0, "provenance_event_ids": ["e1"]}]
+        plan = build_entity_merge_plan(arena="a", master=master, losers=[loser], facts=[], relationships=rels)
+        assert plan.rel_endpoint_repoints == ["r1"]
+        assert plan.rel_collisions == []
+
+    def test_relationship_collision_sums_weight_and_unions_provenance(self):
+        # master already has (m -> z, works_for); loser has (l -> z, works_for).
+        # Repointing l->m collides; keep one, sum weights, union provenance, drop other.
+        master, loser = _ent("m", "Bob"), _ent("l", "Bobby")
+        rels = [
+            {"id": "r_master", "from_entity_id": "m", "to_entity_id": "z",
+             "relationship_type": "works_for", "weight": 3.0, "provenance_event_ids": ["e1"]},
+            {"id": "r_loser", "from_entity_id": "l", "to_entity_id": "z",
+             "relationship_type": "works_for", "weight": 2.0, "provenance_event_ids": ["e2"]},
+        ]
+        plan = build_entity_merge_plan(arena="a", master=master, losers=[loser], facts=[], relationships=rels)
+        assert len(plan.rel_collisions) == 1
+        c = plan.rel_collisions[0]
+        assert c["keep"] == "r_master" and c["drop"] == "r_loser"
+        assert c["summed_weight"] == 5.0
+        assert sorted(c["provenance"]) == ["e1", "e2"]
+
+    def test_audit_rows_carry_rollback_payload(self):
+        master, loser = _ent("m", "Real"), _ent("l", "Dupe", prov=["e9"])
+        plan = build_entity_merge_plan(arena="a", master=master, losers=[loser], facts=[], relationships=[])
+        assert len(plan.audit_rows) == 1
+        row = plan.audit_rows[0]
+        assert row["canonical_id"] == "m" and row["deprecated_id"] == "l"
+        assert row["rollback_payload"] == loser  # full row preserved
+
+    def test_master_cannot_be_loser(self):
+        m = _ent("m", "X")
+        with pytest.raises(ValueError):
+            build_entity_merge_plan(arena="a", master=m, losers=[m], facts=[], relationships=[])
+
+    def test_multi_loser_merge(self):
+        master = _ent("m", "Katie Cooper", prov=["e1"])
+        losers = [_ent("l1", "1716801984", prov=["e2"]), _ent("l2", "K. Cooper", prov=["e3"])]
+        plan = build_entity_merge_plan(arena="a", master=master, losers=losers, facts=[], relationships=[])
+        assert plan.deprecated_entity_ids == ["l1", "l2"]
+        assert sorted(plan.master_provenance) == ["e1", "e2", "e3"]
+        assert len(plan.audit_rows) == 2
+
+
+class TestFactMergePlan:
+    def test_picks_highest_confidence_master(self):
+        dups = [
+            {"id": "f1", "confidence": 0.5, "statement": "short", "provenance_event_ids": ["e1"]},
+            {"id": "f2", "confidence": 0.9, "statement": "the better one", "provenance_event_ids": ["e2"]},
+        ]
+        plan = build_fact_merge_plan(arena="a", dup_facts=dups)
+        assert plan["master_id"] == "f2"
+        assert plan["deprecated_ids"] == ["f1"]
+        assert sorted(plan["master_provenance"]) == ["e1", "e2"]
+
+    def test_single_fact_no_merge(self):
+        assert build_fact_merge_plan(arena="a", dup_facts=[{"id": "f1"}]) is None
+
+    def test_tie_breaks_on_statement_length(self):
+        dups = [
+            {"id": "f1", "confidence": 0.7, "statement": "x", "provenance_event_ids": []},
+            {"id": "f2", "confidence": 0.7, "statement": "longer statement", "provenance_event_ids": []},
+        ]
+        plan = build_fact_merge_plan(arena="a", dup_facts=dups)
+        assert plan["master_id"] == "f2"
+
+
+class TestEvictionReceipt:
+    def test_carries_full_row(self):
+        row = {"id": "e1", "arena": "a", "canonical_name": "Ghost"}
+        r = build_eviction_receipt("entity", row)
+        assert r["node_kind"] == "entity" and r["node_id"] == "e1"
+        assert r["rollback_payload"] == row