superlocalmemory 3.8.13 → 4.0.0

package/src/superlocalmemory/mesh/state_sync.py

@@ -0,0 +1,286 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V4 | https://qualixar.com | https://varunpratap.com
+
+"""LWW remote state convergence for the SLM mesh (3c-1).
+
+Convergence guarantee
+---------------------
+Leaderless, pull-based, deterministic Last-Writer-Wins.  Every node that
+exchanges deltas converges on the same ``(value, revision, node_id)`` for
+every key.
+
+This is NOT linearizable consensus.  Concurrent writes can interleave; the
+winner is chosen deterministically by a TOTAL ORDER on ``(revision: int,
+node_id: str)``.  Same revision → higher ``node_id`` wins (lexicographic).
+Because the order is total, every node independently computes the same
+winner given the same set of writes.
+
+Backward compatibility
+----------------------
+``set_state`` in the broker never sets ``origin_node``; rows it writes have
+``origin_node = ''`` (the column default added here).  At merge and
+serialization time ``''`` is interpreted as the LOCAL node_id, so existing
+rows participate correctly in the LWW protocol without any change to
+``broker.py``.
+
+Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from typing import Any
+
+from superlocalmemory.mesh.node_identity import get_node_id
+
+logger = logging.getLogger("superlocalmemory.mesh.state_sync")
+
+# ---------------------------------------------------------------------------
+# Schema migration (additive, idempotent)
+# ---------------------------------------------------------------------------
+
+_ALTER_ORIGIN_NODE = (
+    "ALTER TABLE mesh_state ADD COLUMN origin_node TEXT NOT NULL DEFAULT ''"
+)
+
+
+# ---------------------------------------------------------------------------
+# StateSyncer
+# ---------------------------------------------------------------------------
+
+
+class StateSyncer:
+    """Pull-based LWW convergence helper for the ``mesh_state`` table.
+
+    Designed to be instantiated on-demand (route handler, sync loop); all DB
+    connections are short-lived.  Every operation is fail-soft: errors are
+    logged and the caller never receives an unhandled exception from here.
+    """
+
+    def __init__(self, broker: Any) -> None:
+        self._broker = broker
+        self._db_path: str = str(broker._db_path)
+        # Resolved once; stable for the lifetime of this instance.
+        self._node_id: str = get_node_id(self._db_path)
+        self._ensure_origin_node_column()
+
+    # ------------------------------------------------------------------
+    # Schema bootstrap
+    # ------------------------------------------------------------------
+
+    def _ensure_origin_node_column(self) -> None:
+        """Add ``origin_node`` to ``mesh_state``; no-op if already present."""
+        try:
+            conn = sqlite3.connect(self._db_path, timeout=5.0)
+            try:
+                conn.execute(_ALTER_ORIGIN_NODE)
+                conn.commit()
+            except sqlite3.OperationalError as exc:
+                if "duplicate column" in str(exc).lower():
+                    pass  # Expected on second startup / upgrade
+                else:
+                    logger.error(
+                        "StateSyncer._ensure_origin_node_column: unexpected "
+                        "OperationalError at %s: %s",
+                        self._db_path, exc,
+                    )
+            finally:
+                conn.close()
+        except sqlite3.Error as exc:
+            logger.error(
+                "StateSyncer._ensure_origin_node_column: DB error at %s: %s",
+                self._db_path, exc,
+            )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _effective_node(self, stored_origin: str) -> str:
+        """Resolve ``origin_node=''`` (BC rows) to this node's id at call time."""
+        return stored_origin if stored_origin else self._node_id
+
+    def _open_conn(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path, timeout=5.0)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def local_delta(
+        self,
+        profile_id: str = "default",
+        since_revision: int = 0,
+    ) -> list[dict]:
+        """Return rows with ``revision > since_revision`` for a profile.
+
+        The ``node_id`` field in each entry reflects the *effective* node:
+        the stored ``origin_node`` when non-empty, or the local node_id for
+        BC rows written by the broker (``origin_node = ''``).
+
+        Returns ``[]`` on any DB error (fail-soft).
+        """
+        try:
+            conn = self._open_conn()
+            try:
+                rows = conn.execute(
+                    "SELECT key, value, set_by, updated_at,"
+                    " COALESCE(revision, 0) AS revision,"
+                    " COALESCE(origin_node, '') AS origin_node"
+                    " FROM mesh_state"
+                    " WHERE profile_id = ? AND COALESCE(revision, 0) > ?",
+                    (profile_id, int(since_revision)),
+                ).fetchall()
+                return [
+                    {
+                        "key": row["key"],
+                        "value": row["value"],
+                        "set_by": row["set_by"],
+                        "updated_at": row["updated_at"],
+                        "revision": int(row["revision"]),
+                        "node_id": self._effective_node(row["origin_node"]),
+                    }
+                    for row in rows
+                ]
+            finally:
+                conn.close()
+        except sqlite3.Error as exc:
+            logger.error(
+                "StateSyncer.local_delta: DB error at %s: %s",
+                self._db_path, exc,
+            )
+            return []
+
+    def merge_remote(
+        self,
+        profile_id: str,
+        remote_entries: list[dict],
+    ) -> dict:
+        """Merge remote delta entries using deterministic LWW.
+
+        For each entry ``{key, value, set_by, updated_at, revision, node_id}``:
+
+        * If ``(remote_rev, remote_node) > (local_rev, local_node)`` (total
+          order): UPSERT the local row.  The winning ``revision`` is preserved
+          as-is — never incremented — so re-merging the same delta is a no-op
+          (idempotent convergence).
+        * Otherwise: do nothing.
+
+        Returns ``{"applied": N, "skipped": M}``.  Errors per-entry are
+        logged and counted as skipped; they never propagate to the caller.
+        """
+        applied = 0
+        skipped = 0
+        for entry in remote_entries:
+            # Compute a safe log key BEFORE the try so a non-dict entry can
+            # never make the error handler itself raise (audit P0/P2 — the
+            # handler previously called entry.get() on possibly-non-dict).
+            entry_key = entry.get("key") if isinstance(entry, dict) else repr(entry)
+            try:
+                if self._merge_one(profile_id, entry):
+                    applied += 1
+                else:
+                    skipped += 1
+            except sqlite3.Error as exc:
+                logger.error(
+                    "StateSyncer.merge_remote: DB error on key=%r: %s",
+                    entry_key, exc,
+                )
+                skipped += 1
+            except (KeyError, TypeError, ValueError, AttributeError) as exc:
+                logger.error(
+                    "StateSyncer.merge_remote: malformed entry key=%r: %s",
+                    entry_key, exc,
+                )
+                skipped += 1
+        return {"applied": applied, "skipped": skipped}
+
+    def _merge_one(self, profile_id: str, entry: dict) -> bool:
+        """Apply one remote entry if it wins the LWW comparison.
+
+        Returns ``True`` if the local row was updated; ``False`` if local
+        won or the comparison was a tie (same revision, same node_id).
+
+        CRITICAL: ``revision`` is never incremented here.  Preserving the
+        winning revision is what makes convergence idempotent — a second
+        merge of the same delta computes the identical comparison result and
+        takes no action.
+        """
+        # Audit P0/P2: a non-dict entry must never crash the merge.
+        if not isinstance(entry, dict):
+            return False
+        key = str(entry["key"])
+        # Guard: cast revision to int to prevent string lexicographic miscompare
+        # (e.g. "10" < "9" as strings but 10 > 9 as ints).
+        remote_rev: int = int(entry["revision"])
+        remote_node: str = str(entry.get("node_id", "")).strip()
+        # Audit P1: an empty node_id would be stored as origin_node='' and then
+        # re-exported under THIS node's id, rewriting provenance and corrupting
+        # the tie-break. Refuse an entry without a real origin.
+        if not remote_node:
+            return False
+        # Audit P2: never persist a NULL value as the literal string "None".
+        if entry.get("value") is None:
+            return False
+
+        conn = self._open_conn()
+        # Audit P1 (TOCTOU): the read-compare-write MUST be atomic against a
+        # concurrent broker.set_state on the same key. Without a write lock, a
+        # stale local read lets a lower remote revision overwrite a fresher
+        # local write (losing local-highest-revision). BEGIN IMMEDIATE takes the
+        # write lock for the whole critical section.
+        conn.isolation_level = None  # manual transaction control
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+            row = conn.execute(
+                "SELECT COALESCE(revision, 0) AS revision,"
+                " COALESCE(origin_node, '') AS origin_node"
+                " FROM mesh_state"
+                " WHERE profile_id = ? AND key = ?",
+                (profile_id, key),
+            ).fetchone()
+
+            if row is None:
+                local_rev: int = 0
+                local_node: str = ""  # No row — treat as the absolute minimum
+            else:
+                local_rev = int(row["revision"])
+                local_node = self._effective_node(row["origin_node"])
+
+            # Total order: compare revision (int) first; break ties by node_id (str lex).
+            # A strict > means ties-to-local (same rev, same node) → do nothing (idempotent).
+            remote_wins: bool = (remote_rev, remote_node) > (local_rev, local_node)
+            if not remote_wins:
+                conn.execute("ROLLBACK")
+                return False
+
+            # UPSERT: set origin_node = remote_node so subsequent merges of the
+            # same delta compute the same winner without re-resolving local node_id.
+            conn.execute(
+                "INSERT INTO mesh_state"
+                " (profile_id, key, value, set_by, updated_at, revision, origin_node)"
+                " VALUES (?, ?, ?, ?, ?, ?, ?)"
+                " ON CONFLICT(profile_id, key) DO UPDATE SET"
+                " value     = excluded.value,"
+                " set_by    = excluded.set_by,"
+                " updated_at = excluded.updated_at,"
+                " revision  = excluded.revision,"
+                " origin_node = excluded.origin_node",
+                (
+                    profile_id,
+                    key,
+                    str(entry["value"]),
+                    str(entry["set_by"]),
+                    str(entry["updated_at"]),
+                    remote_rev,
+                    remote_node,
+                ),
+            )
+            conn.execute("COMMIT")
+            return True
+        finally:
+            conn.close()

package/src/superlocalmemory/optimize/config/store.py

@@ -13,10 +13,12 @@ and self._version. get() acquires a read-lock; save() acquires a write-lock.
 
 from __future__ import annotations
 
+import atexit
 import json
 import logging
 import os
 import threading
+import weakref
 from pathlib import Path
 from typing import Any, Callable
 
@@ -29,6 +31,43 @@ logger = logging.getLogger(__name__)
 _DEFAULT_CONFIG_PATH = DynamicStatePath("optimize.json")
 _POLL_INTERVAL_SECONDS: float = 2.0
 
+# ---- watchdog shutdown safety -------------------------------------------
+# Each started watchdog runs in a daemon thread. At interpreter shutdown CPython
+# kills daemon threads abruptly; on macOS, with the ``watchdog`` fsevents C
+# extension also loaded in-process, a daemon thread still executing while the
+# interpreter finalizes can race the teardown and SIGSEGV. We track every store
+# that has a live watchdog and stop+join them from an ``atexit`` hook — atexit
+# callbacks run BEFORE daemon threads are terminated, so no watchdog thread is
+# still alive when CPython finalizes.
+_active_stores: "weakref.WeakSet[ConfigStore]" = weakref.WeakSet()
+_registry_lock = threading.Lock()
+_atexit_registered = False
+
+
+def _register_active_store(store: "ConfigStore") -> None:
+    """Track a store with a running watchdog; install the atexit hook once."""
+    global _atexit_registered
+    with _registry_lock:
+        _active_stores.add(store)
+        if not _atexit_registered:
+            atexit.register(_stop_all_watchdogs)
+            _atexit_registered = True
+
+
+def _stop_all_watchdogs() -> None:
+    """Stop+join every registered watchdog. Idempotent; safe at interpreter exit.
+
+    Also invoked by the test harness at session finish (see tests/conftest.py)
+    so no leaked watchdog thread survives into interpreter finalization.
+    """
+    with _registry_lock:
+        stores = list(_active_stores)
+    for store in stores:
+        try:
+            store.stop_watchdog()
+        except Exception:
+            pass
+
 
 class ConfigStore:
     """Manages optimize.json with hot-reload capability."""
@@ -125,6 +164,10 @@ class ConfigStore:
                 daemon=True,
             )
             self._watchdog_thread.start()
+        # Register outside self._lock — _register_active_store takes the module
+        # registry lock, and the idempotent early-return above already covers a
+        # re-start (the store stays registered from the first start).
+        _register_active_store(self)
 
     def stop_watchdog(self) -> None:
         """Signal the watchdog thread to stop and join it (timeout=5s)."""
@@ -134,6 +177,8 @@ class ConfigStore:
             t.join(timeout=5.0)
         with self._lock:
             self._watchdog_thread = None
+        with _registry_lock:
+            _active_stores.discard(self)
 
     def version(self) -> int:
         with self._lock:

package/src/superlocalmemory/parameterization/cross_project.py

@@ -0,0 +1,12 @@
+"""Cross-project preference aggregation for the parameterization subsystem.
+
+The aggregator implementation lives in
+:mod:`superlocalmemory.learning.cross_project`. It is re-exported here so the
+parameterization namespace — where the pattern extractor consumes it — resolves
+to the same class instead of a missing module.
+"""
+from __future__ import annotations
+
+from superlocalmemory.learning.cross_project import CrossProjectAggregator
+
+__all__ = ["CrossProjectAggregator"]

package/src/superlocalmemory/parameterization/prompt_injector.py

@@ -77,24 +77,26 @@ class PromptInjector:
 
         templates: list[SoftPromptTemplate] = []
         for row in rows:
-            raw_ids = row.get("source_pattern_ids", "[]")
+            # DatabaseManager returns sqlite3.Row which lacks .get() — convert to dict.
+            r = dict(row)
+            raw_ids = r.get("source_pattern_ids", "[]")
             try:
                 source_ids = json.loads(raw_ids) if isinstance(raw_ids, str) else raw_ids
             except (json.JSONDecodeError, TypeError):
                 source_ids = []
 
             templates.append(SoftPromptTemplate(
-                prompt_id=row["prompt_id"],
-                profile_id=row.get("profile_id", profile_id),
-                category=row["category"],
-                content=row["content"],
+                prompt_id=r["prompt_id"],
+                profile_id=r.get("profile_id", profile_id),
+                category=r["category"],
+                content=r["content"],
                 source_pattern_ids=source_ids,
-                confidence=row["confidence"],
-                effectiveness=row.get("effectiveness", 0.5),
-                token_count=row.get("token_count", 0),
-                retention_score=row.get("retention_score", 1.0),
-                active=bool(row.get("active", 1)),
-                version=row.get("version", 1),
+                confidence=r["confidence"],
+                effectiveness=r.get("effectiveness", 0.5),
+                token_count=r.get("token_count", 0),
+                retention_score=r.get("retention_score", 1.0),
+                active=bool(r.get("active", 1)),
+                version=r.get("version", 1),
             ))
 
         # Budget enforcement

package/src/superlocalmemory/parameterization/prompt_lifecycle.py

@@ -45,12 +45,13 @@ class PromptLifecycleManager:
     def __init__(
         self,
         db: DatabaseManager,
-        ebbinghaus: EbbinghausCurve,
         config: ParameterizationConfig,
+        *,
+        ebbinghaus: EbbinghausCurve | None = None,
     ) -> None:
         self._db = db
-        self._ebbinghaus = ebbinghaus
         self._config = config
+        self._ebbinghaus = ebbinghaus
 
     # ------------------------------------------------------------------
     # Effectiveness tracking
@@ -157,6 +158,11 @@ class PromptLifecycleManager:
         s_raw = 2.0 * effectiveness * version
         s_prompt = max(_PROMPT_STRENGTH_FLOOR, s_raw)
 
+        if self._ebbinghaus is None:
+            from superlocalmemory.math.ebbinghaus import EbbinghausCurve
+            from superlocalmemory.core.config import ForgettingConfig
+            self._ebbinghaus = EbbinghausCurve(ForgettingConfig())
+
         retention = self._ebbinghaus.retention(hours, s_prompt)
         return retention
 

package/src/superlocalmemory/parameterization/workflow_miner.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Workflow miner re-export for the parameterization namespace.
+
+The canonical implementation lives in
+:mod:`superlocalmemory.learning.workflows`. This thin module re-exports
+``WorkflowMiner`` so that code in the parameterization subsystem can import
+from the same namespace as the pattern extractor's dependency declaration.
+"""
+
+from __future__ import annotations
+
+from superlocalmemory.learning.workflows import WorkflowMiner
+
+__all__ = ["WorkflowMiner"]

package/src/superlocalmemory/retrieval/ann_index.py

@@ -58,6 +58,11 @@ class ANNIndex:
         """Embedding dimension this index was created for."""
         return self._dim
 
+    def contains(self, fact_id: str) -> bool:
+        """Return True if the index currently holds this fact."""
+        with self._lock:
+            return fact_id in self._id_to_idx
+
     # ------------------------------------------------------------------
     # Mutation
     # ------------------------------------------------------------------

package/src/superlocalmemory/retrieval/bm25_channel.py

@@ -221,11 +221,19 @@ class BM25Channel:
             include_shared=include_shared,
             prefix="af",
         )
+        # Archived facts are not live; never surface them in keyword recall.
+        # Guarded on column presence: the archive column is added by a deferred
+        # migration and may be absent on an unmigrated database.
+        archive_clause = (
+            " AND COALESCE(af.archive_status, 'live') != 'archived'"
+            if self._db._has_archive_status()
+            else ""
+        )
         sql = (
             "SELECT af.fact_id AS fact_id, bm25(atomic_facts_fts) AS rank "
             "FROM atomic_facts_fts "
             "JOIN atomic_facts af ON af.rowid = atomic_facts_fts.rowid "
-            f"WHERE atomic_facts_fts MATCH ? AND {where} "
+            f"WHERE atomic_facts_fts MATCH ? AND {where}{archive_clause} "
             "ORDER BY rank LIMIT ?"
         )
         rows = self._db.execute(sql, (match_expr, *params, int(top_k)))
@@ -248,7 +256,7 @@ class BM25Channel:
                 "SELECT af.fact_id AS fact_id, bm25(fact_expansion_fts) AS rank "
                 "FROM fact_expansion_fts "
                 "JOIN atomic_facts af ON af.fact_id = fact_expansion_fts.fact_id "
-                f"WHERE fact_expansion_fts MATCH ? AND {where} "
+                f"WHERE fact_expansion_fts MATCH ? AND {where}{archive_clause} "
                 "ORDER BY rank LIMIT ?"
             )
             for r in self._db.execute(exp_sql, (match_expr, *params, int(top_k))):
@@ -336,6 +344,45 @@ class BM25Channel:
         scored.sort(key=lambda x: x[1], reverse=True)
         return scored[:top_k]
 
+    def update_fact(self, fact_id: str, new_content: str, profile_id: str) -> None:
+        """Replace a fact's representation in the live index and persist new tokens.
+
+        Removes any existing in-memory entry for the fact_id first so the index
+        holds each fact exactly once after the call. Delegates to remove_fact +
+        add so the two operations stay in sync.
+
+        Args:
+            fact_id: Fact whose content has changed.
+            new_content: Updated text to index.
+            profile_id: Owner profile (used for DB token persistence).
+        """
+        self.remove_fact(fact_id)
+        self.add(fact_id, new_content, profile_id)
+
+    def remove_fact(self, fact_id: str) -> None:
+        """Remove a fact from the live in-memory index.
+
+        Idempotent: a no-op when the fact is not in the index. Does NOT touch
+        the persistent ``bm25_tokens`` DB table — the caller is responsible for
+        that (so a delete path can clean up storage independently).
+
+        Args:
+            fact_id: Fact to evict from the in-memory corpus.
+        """
+        if fact_id not in self._fact_id_set:
+            return
+        try:
+            idx = self._fact_ids.index(fact_id)
+            del self._corpus[idx]
+            del self._fact_ids[idx]
+            raw_texts = getattr(self, "_raw_texts", [])
+            if idx < len(raw_texts):
+                del raw_texts[idx]
+            self._fact_id_set.discard(fact_id)
+            self._dirty = True
+        except (ValueError, IndexError):
+            self._fact_id_set.discard(fact_id)
+
     def clear(self) -> None:
         """Clear the in-memory index (does NOT delete DB tokens)."""
         self._corpus = []

package/src/superlocalmemory/retrieval/engine.py

@@ -27,12 +27,12 @@ from typing import TYPE_CHECKING, Any, Protocol
 
 from superlocalmemory.core.config import ChannelWeights, RetrievalConfig
 from superlocalmemory.retrieval.fusion import FusionResult, weighted_rrf
+from superlocalmemory.retrieval.strategy import QueryStrategy, QueryStrategyClassifier
 from superlocalmemory.retrieval.time_window import (
     in_window,
     infer_window_from_query,
     parse_window,
 )
-from superlocalmemory.retrieval.strategy import QueryStrategy, QueryStrategyClassifier
 from superlocalmemory.storage.models import (
     AtomicFact,
     Mode,
@@ -155,6 +155,7 @@ class RetrievalEngine:
         include_global: bool = False,
         include_shared: bool = False,
         window: str | tuple[str, str] | None = None,
+        as_of: str | None = None,
     ) -> RecallResponse:
         """Full retrieval pipeline: strategy -> channels -> RRF -> rerank.
 
@@ -165,6 +166,11 @@ class RetrievalEngine:
         V3.4.40 (2026-05-09): ``extra_disabled_channels`` allows callers to
         skip specific channels for a single recall (e.g. SpreadingActivation
         for the ``--fast`` CLI flag) without mutating shared config.
+
+        ``as_of``: Optional ISO 8601 datetime string. When set, the bi-temporal
+        validity filter treats facts as seen from that point in time —
+        not-yet-valid and already-expired facts are demoted. Default ``None``
+        leaves all existing behaviour unchanged.
         """
         t0 = time.monotonic()
         # NOTE: extra_disabled_channels is passed as an explicit local argument
@@ -212,6 +218,7 @@ class RetrievalEngine:
             query, profile_id, strat,
             extra_disabled_channels=extra_disabled_channels,
             include_global=include_global, include_shared=include_shared,
+            as_of=as_of,
         )
         _em("run_channels")
         if profile_hits:
@@ -765,6 +772,7 @@ class RetrievalEngine:
         extra_disabled_channels: set[str] | None = None,
         include_global: bool = False,
         include_shared: bool = False,
+        as_of: str | None = None,
     ) -> dict[str, list[tuple[str, float]]]:
         """Run active retrieval channels.
 
@@ -885,7 +893,10 @@ class RetrievalEngine:
         )
         for name, fut in futures.items():
             if fut in pending:
-                logger.warning("Channel %s exceeded %.1fs latency budget", name, channel_timeout_seconds)
+                logger.warning(
+                    "Channel %s exceeded %.1fs latency budget",
+                    name, channel_timeout_seconds,
+                )
                 continue
             try:
                 ch_name, result = fut.result()
@@ -894,11 +905,15 @@ class RetrievalEngine:
             except Exception as exc:
                 logger.warning("Channel %s failed: %s", name, exc)
 
-        # Apply registered post-retrieval filters (forgetting filter, etc.)
+        # Apply registered post-retrieval filters (forgetting filter, etc.).
+        # Pass as_of in context dict when set so the bi-temporal validity filter
+        # can perform point-in-time demotion. None context preserves the existing
+        # behaviour for all callers that don't use time-travel recall.
+        _filter_context = {"as_of": as_of} if as_of is not None else None
         if hasattr(self, '_registry') and self._registry._filters:
             for fn in self._registry._filters:
                 try:
-                    out = fn(out, profile_id, None)
+                    out = fn(out, profile_id, _filter_context)
                 except Exception as exc:
                     logger.warning("Post-retrieval filter failed: %s", exc)
 

package/src/superlocalmemory/retrieval/fusion.py

@@ -74,5 +74,8 @@ def weighted_rrf(
             fused += w / (k + rank)
         results.append(FusionResult(fid, fused, ch_ranks, ch_scores))
 
-    results.sort(key=lambda r: r.fused_score, reverse=True)
+    # Deterministic total order: fused score descending, ties broken by fact_id.
+    # Sorting on score alone left tied results in set-iteration order, which
+    # varies with the process hash seed.
+    results.sort(key=lambda r: (-r.fused_score, r.fact_id))
     return results