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

package/packages/memory-engine-v2/extractor-async/worker.py

@@ -39,7 +39,7 @@ import httpx
 import psycopg
 import psycopg.rows
 
-from confidence import corroborated_confidence
+from confidence import born_salience, corroborated_confidence
 from entity_id import entity_id, normalize_surface_form
 from extraction_schema import (
     ALLOWED_ENT_TYPES,
@@ -149,13 +149,41 @@ if DISTILL_GUIDED_PARAM_STYLE not in ("response_format", "guided_json"):
     )
     DISTILL_GUIDED_PARAM_STYLE = "response_format"
 
+# Optional chat-template kwargs forwarded verbatim on every chat
+# completion (vLLM extension: top-level `chat_template_kwargs`).
+# Needed for thinking-capable teachers: Qwen3.x chat templates default
+# enable_thinking=true, which burns the max_tokens budget on reasoning
+# the distiller never reads. The 2026-06-11 teacher bake-off ran the
+# Qwen3.6 lanes with {"enable_thinking": false}, so the prod swap must
+# send the same switch for its traces to match the benchmarked
+# distribution. Unset (default) sends nothing — the request body stays
+# byte-identical for teachers without template switches (Qwen2.5).
+DISTILL_CHAT_TEMPLATE_KWARGS: dict[str, Any] | None = None
+_raw_ctk = os.environ.get("DISTILL_CHAT_TEMPLATE_KWARGS", "").strip()
+if _raw_ctk:
+    try:
+        _parsed_ctk = json.loads(_raw_ctk)
+        if not isinstance(_parsed_ctk, dict):
+            raise ValueError("must be a JSON object")
+        DISTILL_CHAT_TEMPLATE_KWARGS = _parsed_ctk
+    except ValueError as e:
+        log.warning(f"DISTILL_CHAT_TEMPLATE_KWARGS invalid ({e}) — ignoring")
+
 # JSON output carries structural overhead (braces, quotes, key names)
 # the KV format doesn't, so guided mode gets its own per-event token
 # budget. Truncation is guided mode's ONLY parse-failure mode (the
 # schema enforcer guarantees validity up to the cut), so this errs
 # higher than the KV 300.
+#
+# NOTE the budget is SHARED across the chunk (max_tokens = this × N
+# events per request). A fully-maxed event (8 ent / 6 fct with 140-char
+# statements / 6 rel + JSON overhead) is ~1.1k output tokens, so chunk
+# size and this value must be chosen together against the server's
+# max_model_len. Raised 400→900 after prod showed 15% of 5-event chunks
+# truncating on `length` (2026-06-12); prod now runs EVENTS_PER_LLM_CALL=3
+# so 3×900 output + ~2.1k prompt stays well inside the L40S 8192 ctx.
 LLM_MAX_TOKENS_PER_EVENT_JSON = int(
-    os.environ.get("LLM_MAX_TOKENS_PER_EVENT_JSON", "400")
+    os.environ.get("LLM_MAX_TOKENS_PER_EVENT_JSON", "900")
 )
 
 
@@ -667,6 +695,8 @@ def _build_request_body(user_prompt: str, n: int) -> dict[str, Any]:
             else LLM_MAX_TOKENS_PER_EVENT
         ) * n,
     }
+    if DISTILL_CHAT_TEMPLATE_KWARGS:
+        body["chat_template_kwargs"] = DISTILL_CHAT_TEMPLATE_KWARGS
     if DISTILL_OUTPUT_MODE == "guided_json":
         if DISTILL_GUIDED_PARAM_STYLE == "guided_json":
             body["guided_json"] = EXTRACTION_SCHEMA
@@ -752,6 +782,15 @@ def _content_id(*parts: str) -> str:
     return hashlib.sha256("\x1f".join(parts).encode()).hexdigest()[:32]
 
 
+def _digit_ratio(s: str) -> float:
+    """Fraction of non-whitespace chars that are digits. Used to flag
+    numeric-ID-as-person junk for Fusion Drive born-salience."""
+    stripped = "".join(s.split())
+    if not stripped:
+        return 0.0
+    return sum(c.isdigit() for c in stripped) / len(stripped)
+
+
 def upsert_entities(
     conn: psycopg.Connection,
     arena: str,
@@ -853,12 +892,20 @@ def upsert_entities(
             else:
                 # 3b. No match — insert new.
                 eid = entity_id(arena, etype, name)
+                # Fusion Drive born-salience: a numeric-ID-as-person (classic
+                # 7B junk that slips past noise_filter, e.g. "1716801984") is
+                # born near the floor so the decay pass can evict it on a short
+                # clock instead of the multi-year entity default.
+                _qflags = []
+                if etype == "person" and _digit_ratio(name) > 0.5:
+                    _qflags.append("numeric_id_person")
+                _sal = born_salience(1, _qflags)
                 cur.execute(
                     """
                     INSERT INTO entities (
                       id, arena, entity_type, canonical_name, aliases,
-                      provenance_event_ids, participant_set, disclosure_class
-                    ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s::disclosure_class)
+                      provenance_event_ids, participant_set, disclosure_class, salience
+                    ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s::disclosure_class, %s)
                     ON CONFLICT (id) DO UPDATE SET
                       aliases = (
                         SELECT ARRAY(SELECT DISTINCT UNNEST(entities.aliases || EXCLUDED.aliases))
@@ -866,11 +913,13 @@ def upsert_entities(
                       provenance_event_ids = (
                         SELECT ARRAY(SELECT DISTINCT UNNEST(entities.provenance_event_ids || EXCLUDED.provenance_event_ids))
                       ),
+                      -- re-corroboration can only RAISE salience, never lower it
+                      salience = GREATEST(entities.salience, EXCLUDED.salience),
                       last_seen = NOW()
                     """,
                     (
                         eid, arena, etype, name, aliases,
-                        [event_id], participant_set, disclosure_class,
+                        [event_id], participant_set, disclosure_class, _sal,
                     ),
                 )
             name_to_id[name] = eid
@@ -912,15 +961,24 @@ def upsert_facts(
                 continue
             subj_name = f.get("subject")
             obj_name = f.get("object")
+            # Fusion Drive born-salience: a fact whose subject isn't among the
+            # event's declared entities (ungrounded subject) or that's barely
+            # a sentence is born low so decay can clear it. n_sources=1 here.
+            _fflags = []
+            if subj_name and not name_to_id.get(subj_name):
+                _fflags.append("subject_undeclared")
+            if len(stmt) < 60:
+                _fflags.append("low_signal")
+            _fsal = born_salience(1, _fflags)
             cur.execute(
                 """
                 INSERT INTO facts (
                   id, arena, category, subject_entity_id, predicate,
                   object_entity_id, statement, provenance_event_ids,
-                  stage, confidence, participant_set, disclosure_class
+                  stage, confidence, participant_set, disclosure_class, salience
                 ) VALUES (
                   %s, %s, %s, %s, %s, %s, %s, %s,
-                  'provisional'::extraction_stage, %s, %s, %s::disclosure_class
+                  'provisional'::extraction_stage, %s, %s, %s::disclosure_class, %s
                 )
                 ON CONFLICT (id) DO UPDATE SET
                   provenance_event_ids = (
@@ -928,6 +986,7 @@ def upsert_facts(
                       facts.provenance_event_ids || EXCLUDED.provenance_event_ids
                     ))
                   ),
+                  salience = GREATEST(facts.salience, EXCLUDED.salience),
                   -- Confidence bumps with each additional independent
                   -- source. The cardinality of the merged provenance
                   -- array IS the corroboration count, so the formula
@@ -960,6 +1019,7 @@ def upsert_facts(
                     float(f.get("confidence") or corroborated_confidence(1)),
                     participant_set,
                     disclosure_class,
+                    _fsal,
                 ),
             )
             inserted += 1

package/packages/memory-engine-v2/extractor-sync/server.py

@@ -56,11 +56,15 @@ _pool: AsyncConnectionPool | None = None
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     global _pool
+    # Default (tuple) row factory — _upsert_entities and friends index
+    # fetchone() rows positionally, matching extractor-async's worker.
+    # A dict_row factory here turns row[0] into KeyError: 0 on the
+    # entity-merge path (2026-06-11 prod incident: every extract that
+    # re-saw a known entity 500'd; only never-seen-entity events stored).
     _pool = AsyncConnectionPool(
         conninfo=PG_DSN,
         min_size=8,
         max_size=50,
-        kwargs={"row_factory": psycopg.rows.dict_row},
         open=False,
     )
     await _pool.open()
@@ -89,7 +93,7 @@ class ExtractRequest(BaseModel):
     clientId: str
     userId: str | None = None
     event_type: str = "STORE_MEMORY"
-    source_kind: str  # 'chat' | 'note' | 'doc' | 'event' | 'ticket' | 'commit' | 'system' | 'agent'
+    source_kind: str  # 'chat' | 'note' | 'doc' | 'event' | 'ticket' | 'commit' | 'system' | 'agent' | 'code_reference'
     source_id: str | None = None
     content: str
     attributes: dict[str, Any] = {}

package/packages/memory-engine-v2/extractor-sync/test_paired_extraction.py

@@ -22,8 +22,14 @@ import pytest
 
 
 # Load extractor-sync's server.py as a module so we can call its
-# private helpers directly.
+# private helpers directly. server.py flat-imports its siblings
+# (entity_id) the way the container's WORKDIR layout resolves them, so
+# this directory must be on sys.path — otherwise exec_module raises
+# ImportError and the module-level skip below silently swallows the
+# whole suite whenever pytest runs from the repo root.
 _THIS = Path(__file__).resolve().parent
+if str(_THIS) not in sys.path:
+    sys.path.insert(0, str(_THIS))
 _SPEC = importlib.util.spec_from_file_location("extractor_sync_server",
                                                 _THIS / "server.py")
 assert _SPEC and _SPEC.loader
@@ -206,3 +212,78 @@ def test_extract_event_organizer_object_form() -> None:
     assert len(entities) == 1
     assert entities[0]["canonical_name"] == "X Person"
     assert "x@example.com" in entities[0]["aliases"]
+
+
+# ----------------------------------------------------------------------
+# _upsert_entities — merge path indexes rows positionally
+# ----------------------------------------------------------------------
+#
+# Regression for the 2026-06-11 prod incident: the pool was configured
+# with row_factory=dict_row while _upsert_entities did `row[0]`, so the
+# merge branch (entity already known) raised KeyError: 0 and every
+# extract that re-saw a known entity 500'd. Only never-seen-entity
+# events could store. Two guards:
+#   1. the pool must keep psycopg's default tuple row factory
+#      (matching extractor-async's worker, which also indexes
+#      positionally), and
+#   2. the merge branch must work against tuple rows end-to-end.
+
+import asyncio
+import inspect
+
+
+class _FakeCursor:
+    """Quacks like psycopg.AsyncCursor, returning TUPLE rows — the
+    shape the pool's default row factory produces. If the pool ever
+    grows a custom row_factory again, update this fake to match it or
+    test_pool_keeps_default_tuple_row_factory will flag the drift."""
+
+    def __init__(self, existing_id: str | None) -> None:
+        self.executed: list[tuple[str, object]] = []
+        self._existing_id = existing_id
+
+    async def execute(self, sql: str, params: object = None) -> None:
+        self.executed.append((" ".join(sql.split()), params))
+
+    async def fetchone(self):
+        return (self._existing_id,) if self._existing_id else None
+
+
+def _entity_stub() -> dict:
+    return {
+        "id": "e_new",
+        "arena": "arena1",
+        "entity_type": "person",
+        "canonical_name": "Alice One",
+        "aliases": ["Alice One", "alice@example.com"],
+        "provenance_event_ids": ["evt1"],
+        "participant_set": ["arena1"],
+        "disclosure_class": "private",
+    }
+
+
+def test_pool_keeps_default_tuple_row_factory() -> None:
+    src = inspect.getsource(sync_server.lifespan)
+    assert "row_factory" not in src, (
+        "extractor-sync's pool must use psycopg's default tuple rows: "
+        "_upsert_entities indexes fetchone() results positionally."
+    )
+
+
+def test_upsert_entities_merge_branch_with_tuple_rows() -> None:
+    """Entity already exists → UPDATE branch runs, id taken from row[0]."""
+    cur = _FakeCursor(existing_id="e_existing")
+    asyncio.run(sync_server._upsert_entities(cur, [_entity_stub()]))
+    updates = [(s, p) for s, p in cur.executed if s.startswith("UPDATE entities")]
+    assert len(updates) == 1
+    _, params = updates[0]
+    assert params[-1] == "e_existing"  # WHERE id = %s ← row[0]
+    assert not any(s.startswith("INSERT INTO entities") for s, _ in cur.executed)
+
+
+def test_upsert_entities_insert_branch_when_no_match() -> None:
+    cur = _FakeCursor(existing_id=None)
+    asyncio.run(sync_server._upsert_entities(cur, [_entity_stub()]))
+    inserts = [s for s, _ in cur.executed if s.startswith("INSERT INTO entities")]
+    assert len(inserts) == 1
+    assert not any(s.startswith("UPDATE entities") for s, _ in cur.executed)

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