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

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

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

@@ -0,0 +1,93 @@
+"""Unit tests for Fusion Drive salience scoring + decay (pure, no DB)."""
+
+from __future__ import annotations
+
+import salience as S
+
+
+class TestBornSalience:
+    def test_base_for_single_uncorroborated_clean_node(self):
+        assert S.born_salience(n_sources=1) == S.BASE_SALIENCE
+
+    def test_corroboration_raises_but_caps(self):
+        assert S.born_salience(n_sources=2) > S.BASE_SALIENCE
+        capped = S.born_salience(n_sources=100)
+        assert capped == round(S.BASE_SALIENCE + S.CORROB_CAP, 4)
+
+    def test_junk_is_born_below_decay_sweep_threshold(self):
+        # Any single hard-junk flag must sink it under the 0.3 sweep line
+        # so decay targets pollution without needing a fusion match.
+        for flag in ("noise_name", "numeric_id_person", "hallucinated_email"):
+            assert S.born_salience(n_sources=1, quality_flags=[flag]) < 0.3, flag
+
+    def test_combined_flags_drive_to_floor(self):
+        s = S.born_salience(
+            n_sources=1, quality_flags=["numeric_id_person", "hallucinated_email", "ungrounded"]
+        )
+        assert s == S.SALIENCE_FLOOR
+
+    def test_corroboration_cannot_rescue_hard_junk(self):
+        # A heavily-corroborated numeric-ID person is still junk-leaning.
+        s = S.born_salience(n_sources=5, quality_flags=["numeric_id_person"])
+        assert s < S.BASE_SALIENCE
+
+    def test_never_exceeds_ceiling_or_below_floor(self):
+        assert S.born_salience(n_sources=1000) <= S.SALIENCE_CEIL
+        assert S.born_salience(n_sources=1, quality_flags=["noise_name"] * 10) == S.SALIENCE_FLOOR
+
+
+class TestHalfLife:
+    def test_durable_categories_barely_decay(self):
+        assert S.half_life_days("fact", "decision") >= 3650
+        assert S.half_life_days("fact", "commitment") >= 3650
+
+    def test_ephemeral_categories_fade_fast(self):
+        assert S.half_life_days("fact", "mention") <= 30
+        assert S.half_life_days("fact", "observation") <= 30
+
+    def test_unknown_category_uses_default(self):
+        assert S.half_life_days("fact", "made_up") == S.FACT_HALF_LIFE_DEFAULT
+
+    def test_entity_and_relationship_kinds(self):
+        assert S.half_life_days("entity") == S.ENTITY_HALF_LIFE_DAYS
+        assert S.half_life_days("relationship") == S.RELATIONSHIP_HALF_LIFE_DAYS
+
+
+class TestDecay:
+    def test_one_half_life_halves_salience(self):
+        assert S.decayed_salience(0.8, age_days=30, hl_days=30) == round(0.4, 4)
+
+    def test_two_half_lives_quarters(self):
+        assert S.decayed_salience(0.8, age_days=60, hl_days=30) == round(0.2, 4)
+
+    def test_no_age_no_decay(self):
+        assert S.decayed_salience(0.6, age_days=0, hl_days=30) == 0.6
+
+    def test_durable_fact_after_a_year_barely_moves(self):
+        hl = S.half_life_days("fact", "decision")
+        assert S.decayed_salience(0.7, age_days=365, hl_days=hl) > 0.65
+
+    def test_mention_after_three_months_is_near_floor(self):
+        hl = S.half_life_days("fact", "mention")  # 30d
+        assert S.decayed_salience(0.5, age_days=90, hl_days=hl) < 0.1
+
+
+class TestEvictable:
+    def test_low_salience_old_unreferenced_is_evictable(self):
+        assert S.is_evictable(current_salience=0.02, age_days=60, referenced_by_live_node=False)
+
+    def test_referenced_node_survives(self):
+        assert not S.is_evictable(current_salience=0.0, age_days=999, referenced_by_live_node=True)
+
+    def test_restricted_never_auto_evicted(self):
+        assert not S.is_evictable(
+            current_salience=0.0, age_days=999, referenced_by_live_node=False,
+            disclosure_class="restricted",
+        )
+
+    def test_recent_low_salience_not_yet_evictable(self):
+        # Below threshold but too young — grace window protects it.
+        assert not S.is_evictable(current_salience=0.01, age_days=5, referenced_by_live_node=False)
+
+    def test_healthy_salience_never_evictable(self):
+        assert not S.is_evictable(current_salience=0.5, age_days=9999, referenced_by_live_node=False)

package/packages/memory-engine-v2/org-model/migrations/004_source_kind_code_reference.sql

@@ -0,0 +1,12 @@
+-- 004: accept 'code_reference' source events (SDK corpus ingest).
+--
+-- The SDK corpus module (packages/memory/src/corpus/) emits events with
+-- source_kind='code_reference' (code-signature ingest, adapters.js).
+-- The enum predates that feature, so those events bounced with
+-- InvalidTextRepresentation and could never be stored — observed in
+-- prod 2026-06-11 as persistent /extract 500s + producer retry loops.
+--
+-- ALTER TYPE ... ADD VALUE cannot run inside a transaction block;
+-- apply with autocommit (psql's default per-statement behaviour).
+-- Applied manually to prod (pme2-org-model) on 2026-06-11.
+ALTER TYPE source_kind ADD VALUE IF NOT EXISTS 'code_reference';

package/packages/memory-engine-v2/org-model/migrations/005_fk_indexes.sql

@@ -0,0 +1,20 @@
+-- 005: index every column that references events(id).
+--
+-- events has four referencing constraints:
+--   distillation_queue.event_id   ON DELETE CASCADE
+--   vector_provenance.event_id    ON DELETE CASCADE
+--   distillation_traces.event_id  ON DELETE CASCADE
+--   events.forgets (self)         ON DELETE SET NULL
+--
+-- Postgres does NOT auto-index FK referencing columns. Without these,
+-- every DELETE on events seq-scans each referencing table per deleted
+-- row to enforce the constraint — the 2026-06-11 arena-scoped nuke of
+-- ~70k events ran for HOURS until the missing indexes were created
+-- on-box. (distillation_queue.event_id already had idx_distillation_
+-- event_id from 003; listed here for completeness via IF NOT EXISTS.)
+--
+-- All idempotent; applied manually to prod (pme2-org-model) 2026-06-12.
+CREATE INDEX IF NOT EXISTS idx_distillation_event_id ON distillation_queue(event_id);
+CREATE INDEX IF NOT EXISTS idx_traces_event_id ON distillation_traces(event_id);
+CREATE INDEX IF NOT EXISTS idx_vector_provenance_event_id ON vector_provenance(event_id);
+CREATE INDEX IF NOT EXISTS idx_events_forgets ON events(forgets);

package/packages/memory-engine-v2/org-model/migrations/006_fusion_drive.sql

@@ -0,0 +1,80 @@
+-- 006: Fusion Drive foundations — salience + audit/ledger tables.
+--
+-- See RFC-fusion-drive.md. This migration is Phase 1 (scoring only, NO
+-- eviction): it adds the columns the decay pass scores against and the
+-- audit/ledger tables fusion + decay write to. Nothing in this migration
+-- deletes or evicts; the decay pass ships dry-run first.
+--
+-- KEY DESIGN CALL: salience is SEPARATE from confidence. `confidence`
+-- means "how corroborated/true is this fact" and must only ever move up
+-- with corroboration — decaying it would lie about truth. `salience` is
+-- "retention priority" and is what decays with time + rises with access.
+-- Eviction (a later phase) keys on salience, never on confidence.
+--
+-- All idempotent (IF NOT EXISTS) — safe to re-run.
+
+-- Retention scoring columns. Default 0.5 (neutral); the decay pass and
+-- the extractor's born-salience seeding set real values. last_accessed
+-- is bumped by /search when a node is returned (keeps used memories
+-- alive); NULL means never retrieved.
+ALTER TABLE entities       ADD COLUMN IF NOT EXISTS salience REAL NOT NULL DEFAULT 0.5;
+ALTER TABLE entities       ADD COLUMN IF NOT EXISTS last_accessed TIMESTAMPTZ;
+ALTER TABLE facts          ADD COLUMN IF NOT EXISTS salience REAL NOT NULL DEFAULT 0.5;
+ALTER TABLE facts          ADD COLUMN IF NOT EXISTS last_accessed TIMESTAMPTZ;
+ALTER TABLE relationships  ADD COLUMN IF NOT EXISTS salience REAL NOT NULL DEFAULT 0.5;
+ALTER TABLE relationships  ADD COLUMN IF NOT EXISTS last_accessed TIMESTAMPTZ;
+
+-- Partial indexes for the decay sweep: it scans low-salience nodes only.
+CREATE INDEX IF NOT EXISTS idx_entities_salience      ON entities(arena, salience)      WHERE salience < 0.3;
+CREATE INDEX IF NOT EXISTS idx_facts_salience         ON facts(arena, salience)         WHERE salience < 0.3;
+CREATE INDEX IF NOT EXISTS idx_relationships_salience ON relationships(arena, salience) WHERE salience < 0.3;
+
+-- fact_merges — mirror of entity_merges (002) for fact fusion. Same
+-- receipt + rollback substrate: the losing fact row is deleted on merge,
+-- this records what absorbed it and enough to recreate it.
+CREATE TABLE IF NOT EXISTS fact_merges (
+  id                      TEXT PRIMARY KEY,
+  arena                   TEXT NOT NULL,
+  canonical_id            TEXT NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
+  deprecated_id           TEXT NOT NULL,                 -- no FK; row is deleted
+  deprecated_statement    TEXT NOT NULL,                 -- preserve for forensics
+  merge_signal            TEXT NOT NULL CHECK (
+    merge_signal IN ('exact_triple', 'statement_embedding', 'llm_adjudication')
+  ),
+  provenance_unioned      INTEGER NOT NULL DEFAULT 0,
+  rollback_payload        JSONB NOT NULL,
+  merged_at               TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_fact_merges_canonical ON fact_merges(canonical_id);
+
+-- Run ledgers — observability for the Fusion Drive passes. Each pass
+-- (fusion or decay) writes one row: what it scanned, what it changed,
+-- and whether it was a dry-run.
+CREATE TABLE IF NOT EXISTS fusion_drive_runs (
+  id              TEXT PRIMARY KEY,
+  arena           TEXT NOT NULL,
+  pass_kind       TEXT NOT NULL CHECK (pass_kind IN ('fusion', 'decay')),
+  mode            TEXT NOT NULL CHECK (mode IN ('dry_run', 'apply')),
+  scanned         INTEGER NOT NULL DEFAULT 0,
+  changed         INTEGER NOT NULL DEFAULT 0,   -- merged (fusion) / evicted (decay)
+  detail          JSONB NOT NULL DEFAULT '{}'::jsonb,
+  started_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  finished_at     TIMESTAMPTZ
+);
+CREATE INDEX IF NOT EXISTS idx_fusion_drive_runs_arena ON fusion_drive_runs(arena, started_at DESC);
+
+-- node_evictions — rollback receipts for decay eviction. The decay pass
+-- only deletes nodes its salience math already classified evictable
+-- (low salience, aged past the grace floor, unreferenced, non-restricted);
+-- this records the full deleted row so an eviction can be undone. Mirrors
+-- the merge-audit pattern (002 / fact_merges).
+CREATE TABLE IF NOT EXISTS node_evictions (
+  id               TEXT PRIMARY KEY,
+  arena            TEXT NOT NULL,
+  node_kind        TEXT NOT NULL CHECK (node_kind IN ('entity', 'fact', 'relationship')),
+  node_id          TEXT NOT NULL,
+  salience_at_evict REAL,
+  rollback_payload JSONB NOT NULL,
+  evicted_at       TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_node_evictions_arena ON node_evictions(arena, evicted_at DESC);

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

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Fusion Drive — born-salience backfill for EXISTING rows.
+
+Migration 006 defaults every pre-existing entity/fact to salience 0.5,
+including accumulated 7B-era junk (e.g. the 87k pip-agents events). At 0.5 a
+junk entity would take ~3+ years to decay under the entity half-life — so the
+"junk self-evicts" cure is inert for existing data until their salience is
+re-seeded from the same quality flags the worker now stamps at insert.
+
+This pass recomputes born-salience for existing entities + facts in an arena
+and writes it back, so the decay pass can act on historical pollution. It only
+LOWERS salience where the quality flags fire (never raises a node above what
+it already has — re-corroboration, not this pass, raises salience). Reads the
+same digit-ratio / subject-undeclared signals the worker uses; deeper signals
+(ungrounded vs source content) are a follow-up.
+
+Arena-scoped (required), dry-run default, --apply to write.
+
+Usage:
+  fusion_drive_born_salience_backfill.py --arena 'X'          # report
+  fusion_drive_born_salience_backfill.py --arena 'X' --apply  # write salience
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "fusion_drive"))
+import salience as S  # noqa: E402
+
+try:
+    import psycopg
+    from psycopg.rows import dict_row
+except ModuleNotFoundError:
+    print("psycopg required", file=sys.stderr)
+    raise
+
+
+def _digit_ratio(s: str) -> float:
+    stripped = "".join((s or "").split())
+    return sum(c.isdigit() for c in stripped) / len(stripped) if stripped else 0.0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--arena", required=True)
+    ap.add_argument("--pg-dsn", default=os.environ.get("PG_DSN"))
+    ap.add_argument("--apply", action="store_true")
+    args = ap.parse_args()
+    if not args.pg_dsn:
+        print("PG_DSN required", file=sys.stderr)
+        return 2
+
+    ent_lowered = fact_lowered = ent_scanned = fact_scanned = 0
+    with psycopg.connect(args.pg_dsn, row_factory=dict_row) as conn:
+        with conn.cursor() as cur:
+            # entities: numeric-ID-as-person born low
+            cur.execute(
+                "SELECT id, entity_type, canonical_name, salience, provenance_event_ids "
+                "FROM entities WHERE arena = %s", (args.arena,))
+            for e in cur.fetchall():
+                ent_scanned += 1
+                flags = []
+                if e["entity_type"] == "person" and _digit_ratio(e["canonical_name"]) > 0.5:
+                    flags.append("numeric_id_person")
+                if not flags:
+                    continue
+                new_sal = S.born_salience(n_sources=len(e["provenance_event_ids"] or []) or 1,
+                                          quality_flags=flags)
+                if new_sal < e["salience"]:
+                    ent_lowered += 1
+                    if args.apply:
+                        with conn.cursor() as w:
+                            w.execute("UPDATE entities SET salience = %s WHERE id = %s",
+                                      (new_sal, e["id"]))
+
+            # facts: subject-undeclared / low-signal born low
+            cur.execute(
+                "SELECT id, subject_entity_id, statement, salience, provenance_event_ids "
+                "FROM facts WHERE arena = %s", (args.arena,))
+            for f in cur.fetchall():
+                fact_scanned += 1
+                flags = []
+                if f["subject_entity_id"] is None:
+                    flags.append("subject_undeclared")
+                if len((f["statement"] or "")) < 60:
+                    flags.append("low_signal")
+                if not flags:
+                    continue
+                new_sal = S.born_salience(n_sources=len(f["provenance_event_ids"] or []) or 1,
+                                          quality_flags=flags)
+                if new_sal < f["salience"]:
+                    fact_lowered += 1
+                    if args.apply:
+                        with conn.cursor() as w:
+                            w.execute("UPDATE facts SET salience = %s WHERE id = %s",
+                                      (new_sal, f["id"]))
+        if args.apply:
+            conn.commit()
+
+    mode = "APPLY" if args.apply else "DRY-RUN"
+    print(f"[fusion-drive:born-salience-backfill] {mode} arena={args.arena}")
+    print(f"  entities: scanned={ent_scanned} lowered={ent_lowered}")
+    print(f"  facts:    scanned={fact_scanned} lowered={fact_lowered}")
+    if not args.apply:
+        print("  (dry-run — run --apply to write. Lowers junk salience only; never raises.)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())