superlocalmemory 4.0.10 → 4.1.2

package/src/superlocalmemory/retrieval/graph_adjacency.py

@@ -0,0 +1,219 @@
+# 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
+
+"""One shape for the graph the entity walk reads, whoever stored it.
+
+WHY THIS EXISTS
+---------------
+The graph was stored twice — in SQLite and, once promoted, in CozoDB — and the
+*walk over it* was written twice with it. The two implementations did not compute
+the same function: the SQLite one multiplies activation by a PageRank factor at
+every hop and the Cozo one had no PageRank at all. Measured on a copy of the
+author's store, 3,567 of 3,667 shared facts came out with different scores, the
+top-20 sets differed, and the projected path therefore failed its shadow
+comparison on **every** query and fell back to SQLite. The projection was correct
+data that nothing could use.
+
+The lesson is not "fix the second walk". It is that a storage backend must supply
+**data, not behaviour**. So this module defines the one shape the walk consumes,
+and each store gets an adapter that produces it. Adding a third store later is
+one adapter and no algorithm; there is no second implementation to keep in step,
+and nothing to shadow-compare, because there is only one answer to compare.
+
+WHY IT IS ARRAYS AND NOT DICTS
+------------------------------
+The walk's cost was never the storage engine or the size of the graph — 7,460
+nodes over 849k edges is small. It was doing 3.4 million relaxations as
+interpreted dictionary lookups (cProfile counted 4,367,932 ``dict.get`` calls in
+one recall). Held as CSR arrays the same relaxation is a handful of vectorised
+passes. See :mod:`superlocalmemory.retrieval.spreading`.
+
+The node space is fact ids. Entity ids are deliberately a separate namespace:
+treating them as graph nodes produces a healthy-looking and semantically wrong
+graph, which is why the projection keeps ``fact_entity`` as an explicit bridge.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Mapping, Protocol, Sequence
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+#: Cap on the PageRank multiplier, matching the walk that defined it.
+PAGERANK_BOOST_CAP = 2.0
+
+
+@dataclass(frozen=True)
+class AdjacencySnapshot:
+    """An immutable view of one profile's fact graph, ready to walk.
+
+    Frozen because the walk must not be able to change the graph underneath a
+    concurrent reader — the channel serialises *loading* behind a lock, and a
+    snapshot handed out after that is safe to read from anywhere.
+    """
+
+    node_ids: tuple[str, ...]
+    node_index: Mapping[str, int]
+    #: CSR over an UNDIRECTED graph: every edge appears in both endpoints' rows
+    #: with the same weight, so "incoming to j" and "outgoing from j" are the
+    #: same list. The walk relies on that to take a segment maximum per row.
+    indptr: np.ndarray
+    indices: np.ndarray
+    weights: np.ndarray
+    entity_to_facts: Mapping[str, tuple[int, ...]]
+    fact_to_entities: tuple[tuple[str, ...], ...]
+    #: Per-node PageRank and community, dense so the walk never branches on
+    #: presence. 0.0 and -1 mean "not measured", which is what the dict-based
+    #: walk expressed as a missing key.
+    pagerank: np.ndarray
+    community: np.ndarray
+    has_metrics: bool
+    #: Provenance, so a surface can say which store answered and an operator can
+    #: tell a fast path from a fallback rather than guessing.
+    source: str = "sqlite"
+    edge_count: int = 0
+    fact_count: int = 0
+    profile_id: str = "default"
+    extras: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def node_count(self) -> int:
+        return len(self.node_ids)
+
+    def index_of(self, fact_id: str) -> int | None:
+        return self.node_index.get(fact_id)
+
+    def peak_propagation_factor(self, decay: float) -> float:
+        """Largest ``decay * weight * pagerank_boost`` any edge can apply.
+
+        At or above 1.0 the walk can amplify along a path, and a bounded
+        iteration is then the only well-defined reading of it — which is what
+        :mod:`spreading` implements, and why it does not matter that the
+        dict-based walk was order-dependent in that regime.
+
+        Measured across four real workspaces: 0.7056 and 0.7100 on the two
+        large ones, 0.8497 on a 24-fact one, and **1.1061 on a five-fact one**,
+        which amplifies. Small graphs concentrate rank by construction, so the
+        amplifying regime is not exotic — it is what every workspace looks like
+        on its first day.
+        """
+        if self.weights.size == 0:
+            return 0.0
+        boost = np.minimum(1.0 + self.pagerank * 2.0, PAGERANK_BOOST_CAP)
+        if not self.has_metrics:
+            return float(decay)
+        return float(np.max(decay * self.weights * boost[self.indices]))
+
+
+def snapshot_from_maps(
+    adjacency: Mapping[str, Sequence[tuple[str, float]]],
+    entity_to_facts: Mapping[str, Iterable[str]],
+    fact_to_entities: Mapping[str, Iterable[str]],
+    graph_metrics: Mapping[str, Mapping[str, Any]] | None,
+    *,
+    source: str,
+    profile_id: str,
+    nodes: Iterable[str] | None = None,
+    fact_count: int = 0,
+) -> AdjacencySnapshot:
+    """Build a snapshot from the dict form both adapters produce.
+
+    Node order is the sorted fact ids, not insertion order. That is what makes a
+    snapshot reproducible: two loads of the same graph produce the same arrays,
+    so a score computed from them is the same number and not a function of which
+    row a database happened to return first.
+
+    ``nodes`` IS THE VISIBLE FACT CORPUS, NOT THE FACTS THAT HAVE EDGES.
+    An earlier version derived the node space from the adjacency keys, which
+    silently excluded every fact with no edge yet — and ingestion is
+    queryable-first, so that is exactly the set a user has just added. Those
+    facts are reachable through their entities and the walk seeds them at 1.0;
+    leaving them out of the node space scored them zero instead. Caught on a real
+    store: four candidates, one of them the highest-scoring result for its query.
+    An edgeless fact is a node with an empty CSR row, which the walk's
+    segment-maximum already reads as zero incoming activation.
+    """
+    node_ids = tuple(sorted(set(nodes) if nodes is not None else set(adjacency)))
+    node_index = {fid: i for i, fid in enumerate(node_ids)}
+    n = len(node_ids)
+
+    indptr = np.zeros(n + 1, dtype=np.int64)
+    flat_indices: list[int] = []
+    flat_weights: list[float] = []
+    for i, fid in enumerate(node_ids):
+        # Sorted within the row for the same reason the rows are sorted.
+        neighbours = sorted(
+            (node_index[nid], float(w))
+            for nid, w in adjacency.get(fid, ())
+            if nid in node_index
+        )
+        for j, w in neighbours:
+            flat_indices.append(j)
+            flat_weights.append(w)
+        indptr[i + 1] = len(flat_indices)
+
+    indices = np.asarray(flat_indices, dtype=np.int64)
+    weights = np.asarray(flat_weights, dtype=np.float64)
+
+    metrics = graph_metrics or {}
+    pagerank = np.zeros(n, dtype=np.float64)
+    community = np.full(n, -1, dtype=np.int64)
+    for fid, i in node_index.items():
+        entry = metrics.get(fid)
+        if not entry:
+            continue
+        pagerank[i] = float(entry.get("pagerank_score", 0.0) or 0.0)
+        comm = entry.get("community_id")
+        if comm is not None:
+            try:
+                community[i] = int(comm)
+            except (TypeError, ValueError):
+                pass
+
+    e2f = {
+        eid: tuple(sorted(node_index[f] for f in facts if f in node_index))
+        for eid, facts in entity_to_facts.items()
+    }
+    f2e = tuple(
+        tuple(fact_to_entities.get(fid, ()) or ()) for fid in node_ids
+    )
+
+    return AdjacencySnapshot(
+        node_ids=node_ids,
+        node_index=node_index,
+        indptr=indptr,
+        indices=indices,
+        weights=weights,
+        entity_to_facts=e2f,
+        fact_to_entities=f2e,
+        pagerank=pagerank,
+        community=community,
+        has_metrics=bool(metrics),
+        source=source,
+        edge_count=int(indices.size // 2),
+        fact_count=fact_count or n,
+        profile_id=profile_id,
+    )
+
+
+class AdjacencySource(Protocol):
+    """A store that can hand over one profile's fact graph.
+
+    Data only. A source that also implemented the walk is the defect this
+    interface exists to prevent.
+    """
+
+    name: str
+
+    def load(
+        self,
+        profile_id: str,
+        *,
+        include_global: bool = False,
+        include_shared: bool = False,
+    ) -> AdjacencySnapshot: ...

package/src/superlocalmemory/retrieval/scope_policy.py

@@ -32,6 +32,26 @@ def authorized_fact_ids(
     unique_ids = list(dict.fromkeys(fact_ids))
     if not unique_ids:
         return set()
+    # Ask for the ids, not the memories. The hydrating call below answers the
+    # same question by decoding a 768-float embedding and two Fisher vectors per
+    # candidate — measured at 374 ms of a 430 ms recall on the author's store,
+    # to authorise 3,659 candidates for a 20-result page. Both build their
+    # predicate from the same two calls, so they cannot disagree; a test asserts
+    # it. Kept as a probe rather than a hard requirement because the lightweight
+    # DB wrappers in maintenance paths do not implement every method.
+    id_only = getattr(db, "visible_fact_ids", None)
+    if callable(id_only):
+        try:
+            allowed = id_only(
+                unique_ids,
+                profile_id,
+                include_global=bool(include_global),
+                include_shared=bool(include_shared),
+            )
+            if isinstance(allowed, (set, frozenset)):
+                return set(allowed)
+        except Exception:
+            pass
     try:
         facts = db.get_facts_by_ids(
             unique_ids,

package/src/superlocalmemory/retrieval/semantic_channel.py

@@ -30,6 +30,12 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+#: How often the Lance projection is checked against the index it replaces: one
+#: in this many searches. A comparison costs a second full search, so checking
+#: every one doubled the channel, and a projection that has genuinely diverged is
+#: caught inside this many queries either way.
+SCALE_SHADOW_SAMPLE_EVERY = 50
+
 # Minimum variance floor to prevent division-by-zero in Fisher distance
 _VARIANCE_FLOOR: float = 1e-6
 
@@ -112,6 +118,8 @@ class SemanticChannel:
         self._scale_vector_backend: Any | None = None
         self._scale_shadow_checks = 0
         self._scale_shadow_mismatches = 0
+        self._scale_shadow_errors = 0
+        self._scale_searches = 0
         # V3.3.19: TurboQuant 3-tier search (stateless, optional)
         self._qas = quantization_aware_search
 
@@ -166,10 +174,37 @@ class SemanticChannel:
             and not include_global
             and not include_shared
         ):
-            projected = self._search_via_lance(
-                query_embedding, q_vec, profile_id, top_k,
-                include_global=include_global, include_shared=include_shared,
-            )
+            self._scale_searches += 1
+            # Shadowing SAMPLES rather than running on every query. Comparing
+            # means running both engines, and they cost the same -- 18.3 ms
+            # against 18.7 ms over 5,324 vectors -- so shadowing every search
+            # doubled this channel for an answer already known to match.
+            # Verified on a copy of the author's store: 18 checks, 0 mismatches.
+            #
+            # What guarantees the projection is not this comparison. It is the
+            # outbox, which commits the intent to project in the same SQLite
+            # transaction as the memory, plus a parity gate holding the
+            # projection to the index it stands in for. A per-query re-run of the
+            # canonical path is a development instrument, and leaving one in
+            # production is how a permanent 2x cost gets mistaken for safety.
+            sampled = (self._scale_searches % SCALE_SHADOW_SAMPLE_EVERY) == 1
+            try:
+                projected = self._search_via_lance(
+                    query_embedding, q_vec, profile_id, top_k,
+                    include_global=include_global, include_shared=include_shared,
+                )
+            except Exception as exc:
+                # The Cozo path this mirrors has always caught its failures; this
+                # one did not, so a Lance error propagated out of recall instead
+                # of degrading to the index that was still sitting there.
+                self._scale_shadow_errors += 1
+                logger.warning("Lance semantic projection failed, using SQLite: %s", exc)
+                return self._search_without_lance(
+                    query_embedding, q_vec, profile_id, top_k,
+                    include_global=include_global, include_shared=include_shared,
+                )
+            if not sampled:
+                return projected
             canonical = self._search_without_lance(
                 query_embedding, q_vec, profile_id, top_k,
                 include_global=include_global, include_shared=include_shared,
@@ -178,7 +213,11 @@ class SemanticChannel:
             if {fid for fid, _ in projected} == {fid for fid, _ in canonical}:
                 return projected
             self._scale_shadow_mismatches += 1
-            logger.warning("Lance semantic projection diverged from SQLite; using SQLite")
+            logger.warning(
+                "Lance semantic projection diverged from SQLite on sampled check "
+                "%d of %d searches; using SQLite",
+                self._scale_shadow_checks, self._scale_searches,
+            )
             return canonical
 
         # --- FAST PATH: sqlite-vec KNN ---
@@ -203,8 +242,11 @@ class SemanticChannel:
 
     def scale_projection_telemetry(self) -> dict[str, int]:
         return {
+            "searches": self._scale_searches,
             "shadow_checks": self._scale_shadow_checks,
             "shadow_mismatches": self._scale_shadow_mismatches,
+            "shadow_errors": self._scale_shadow_errors,
+            "sample_every": SCALE_SHADOW_SAMPLE_EVERY,
         }
 
     def _search_via_lance(

package/src/superlocalmemory/retrieval/spreading.py

@@ -0,0 +1,288 @@
+# 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
+
+"""The spreading-activation walk. One implementation, no storage in it.
+
+A pure function of an :class:`~.graph_adjacency.AdjacencySnapshot`. It opens no
+connection and knows no backend, which is the point: the same walk answers
+whether the graph came out of SQLite or CozoDB, so the two can never disagree and
+there is nothing to shadow-compare.
+
+WHAT IT COMPUTES
+----------------
+Activation starts at 1.0 on every fact linked to a query's entities and spreads
+outward for ``max_hops``, multiplied each hop by ``decay``, by the edge weight,
+and by a PageRank factor on the receiving fact. A fact's score is the best path
+that reaches it — a max, not a sum, so a fact reached twice is not thereby more
+relevant. Two enrichments follow the spread (a community bonus and a
+contradiction penalty), then scores are normalised to [0, 1].
+
+SYNCHRONOUS, AND WHY THAT IS A FIX
+----------------------------------
+Each hop is computed from the previous hop's values only. The dict-based walk
+this replaces read ``activation[fid]`` while iterating the frontier, so a fact
+updated earlier in a hop propagated again within that same hop — meaning the
+walk could reach further than ``max_hops`` allowed, by an amount that depended
+on set iteration order.
+
+That is benign exactly while ``decay * weight * pagerank_boost < 1`` everywhere,
+because then the max-product has a unique fixpoint and order only changes how
+fast it is reached.
+
+**It is not benign in general, and it is not benign here.** The boost is capped
+at 2.0 and ``decay`` is 0.7, so any graph whose peak rank reaches 0.215
+amplifies. Measured across four real workspaces after the ranking was repaired:
+
+    workspace          facts    peak rank   peak factor
+    a large one       12,078     0.003984        0.7056
+    another one        4,038     0.007155        0.7100
+    a small one           24     0.106919        0.8497
+    a very small one       5     0.290068        1.1061   ← amplifies
+
+The last row is the point. A small graph concentrates rank by construction — a
+five-fact workspace on a first day of use is not a corner case, it is every
+workspace's first day — and there the old walk's answer depended on dictionary
+ordering. A bounded synchronous iteration is well-defined in both regimes.
+
+(These numbers replace an earlier note citing a peak of 0.1 and a factor of
+0.84. That reading came from a ranking table whose scores summed to 1.9999 and
+3.3150 on two real stores rather than to 1, so the peak it reported was an
+artefact of the table being wrong, not a property of any graph.)
+:meth:`AdjacencySnapshot.peak_propagation_factor` is how a caller can see which
+regime a store is in.
+
+WHY ARRAYS
+----------
+The relaxation is a max-times sparse product. Held as CSR, one hop is one
+multiply and one segment-maximum over the edge array, in place of a Python loop
+that did 3.4 million dictionary lookups to produce a hundred numbers.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Iterable, Mapping, Sequence
+
+import numpy as np
+
+from superlocalmemory.retrieval.graph_adjacency import (
+    PAGERANK_BOOST_CAP,
+    AdjacencySnapshot,
+)
+
+logger = logging.getLogger(__name__)
+
+#: Community-bonus ceiling and the penalty for a fact outside every seed
+#: community. Carried over unchanged from the walk that introduced them.
+COMMUNITY_BONUS_SCALE = 0.15
+COMMUNITY_BONUS_CAP = 1.3
+COMMUNITY_OUTSIDER_PENALTY = 0.9
+
+
+@dataclass(frozen=True)
+class ActivationResult:
+    """Activation over the snapshot's node space, plus how it was reached."""
+
+    scores: np.ndarray
+    hops_run: int
+    seeded: int
+    normalised_by: float
+
+    def as_mapping(
+        self, snapshot: AdjacencySnapshot, *, threshold: float
+    ) -> dict[str, float]:
+        """The scores at or above ``threshold``, keyed by fact id."""
+        keep = np.flatnonzero(self.scores >= threshold)
+        return {snapshot.node_ids[i]: float(self.scores[i]) for i in keep}
+
+
+def _boost(snapshot: AdjacencySnapshot) -> np.ndarray:
+    """Per-node PageRank multiplier, or ones when no metrics were measured.
+
+    Without metrics the walk deliberately drops the edge weight too. That is not
+    an oversight: weighting without a compensating boost dampens propagation by
+    about 14% and measurably lowered retrieval quality, so the two arrived
+    together and have to leave together.
+    """
+    if not snapshot.has_metrics:
+        return np.ones(snapshot.node_count, dtype=np.float64)
+    return np.minimum(1.0 + snapshot.pagerank * 2.0, PAGERANK_BOOST_CAP)
+
+
+def _segment_max(values: np.ndarray, indptr: np.ndarray, rows: int) -> np.ndarray:
+    """Maximum of ``values`` within each CSR row; 0.0 for an empty row.
+
+    ``np.maximum.reduceat`` returns the element at the start offset for a
+    zero-length segment rather than an identity, so empty rows would inherit
+    whichever neighbour happened to sit at that offset — a silent wrong answer
+    for exactly the isolated facts a graph channel should score at zero.
+    """
+    out = np.zeros(rows, dtype=np.float64)
+    if values.size == 0:
+        return out
+    starts = indptr[:-1]
+    non_empty = starts < indptr[1:]
+    if not non_empty.any():
+        return out
+    reduced = np.maximum.reduceat(values, starts[non_empty])
+    out[non_empty] = reduced
+    return out
+
+
+def activate(
+    snapshot: AdjacencySnapshot,
+    seed_entity_ids: Sequence[str],
+    *,
+    decay: float,
+    threshold: float,
+    max_hops: int,
+) -> ActivationResult:
+    """Spread activation from a query's entities across the fact graph."""
+    n = snapshot.node_count
+    scores = np.zeros(n, dtype=np.float64)
+    if n == 0 or not seed_entity_ids:
+        return ActivationResult(scores, 0, 0, 1.0)
+
+    seeded_nodes: list[int] = []
+    for entity_id in seed_entity_ids:
+        seeded_nodes.extend(snapshot.entity_to_facts.get(entity_id, ()))
+    if seeded_nodes:
+        scores[np.asarray(seeded_nodes, dtype=np.int64)] = 1.0
+
+    visited_entities = set(seed_entity_ids)
+    frontier = np.flatnonzero(scores > 0.0)
+    boost = _boost(snapshot)
+    use_weights = snapshot.has_metrics
+    hops_run = 0
+
+    for hop in range(1, max_hops):
+        hop_decay = decay**hop
+        if hop_decay < threshold:
+            break
+        if frontier.size == 0:
+            break
+        hops_run = hop
+
+        # --- edge propagation, one vectorised pass over the edge array -------
+        # Every edge sits in both endpoints' rows with the same weight, so the
+        # maximum over a row is the maximum over that node's incoming values.
+        contributions = scores[snapshot.indices] * decay
+        if use_weights:
+            contributions = contributions * snapshot.weights
+        incoming = _segment_max(contributions, snapshot.indptr, n)
+        if use_weights:
+            incoming = incoming * boost
+        # A hop only ever raises a score, and only above the threshold.
+        candidate = np.where(incoming >= threshold, incoming, 0.0)
+        improved = candidate > scores
+        next_nodes = np.flatnonzero(improved)
+        scores[improved] = candidate[improved]
+
+        # --- entity hop: facts reached through a newly seen entity ----------
+        # Stateful and cheap, so it stays a loop. It reads the frontier as it
+        # was at the start of this hop, which is the same order of operations
+        # the dict walk used.
+        newly_seen: list[str] = []
+        for node in frontier.tolist():
+            for entity_id in snapshot.fact_to_entities[node]:
+                if entity_id not in visited_entities:
+                    visited_entities.add(entity_id)
+                    newly_seen.append(entity_id)
+        entity_nodes: list[int] = []
+        for entity_id in newly_seen:
+            entity_nodes.extend(snapshot.entity_to_facts.get(entity_id, ()))
+        if entity_nodes:
+            reached = np.asarray(sorted(set(entity_nodes)), dtype=np.int64)
+            lifts = reached[hop_decay > scores[reached]]
+            if lifts.size:
+                scores[lifts] = hop_decay
+                next_nodes = np.union1d(next_nodes, lifts)
+
+        frontier = next_nodes
+
+    return ActivationResult(scores, hops_run, len(seeded_nodes), 1.0)
+
+
+def apply_community_bias(
+    scores: np.ndarray,
+    snapshot: AdjacencySnapshot,
+    seed_entity_ids: Iterable[str],
+    *,
+    penalise_outsiders: bool = True,
+) -> None:
+    """Favour facts sharing a community with the query's seeds. In place.
+
+    A no-op without metrics, which is also when ``community`` is all -1.
+
+    ``penalise_outsiders`` exists because the two callers genuinely differ and
+    the difference is not cosmetic. Search damps a fact belonging to no seed
+    community by 0.9; candidate scoring does not, because it re-scores a set
+    another channel already chose and a graph signal has no business vetoing
+    that channel's find. Collapsing the two into one behaviour would silently
+    change one caller's results, so the asymmetry is a parameter and this
+    paragraph is why.
+    """
+    if not snapshot.has_metrics or scores.size == 0:
+        return
+    seed_nodes: list[int] = []
+    for entity_id in seed_entity_ids:
+        seed_nodes.extend(snapshot.entity_to_facts.get(entity_id, ()))
+    if not seed_nodes:
+        return
+    seed_communities = snapshot.community[np.asarray(seed_nodes, dtype=np.int64)]
+    seed_communities = seed_communities[seed_communities >= 0]
+    if seed_communities.size == 0:
+        return
+    labels, counts = np.unique(seed_communities, return_counts=True)
+    total = float(counts.sum())
+    share = dict(zip(labels.tolist(), (counts / total).tolist()))
+
+    known = snapshot.community >= 0
+    multiplier = np.ones(scores.size, dtype=np.float64)
+    for label, fraction in share.items():
+        in_seed = known & (snapshot.community == label)
+        multiplier[in_seed] = min(
+            1.0 + COMMUNITY_BONUS_SCALE * fraction, COMMUNITY_BONUS_CAP
+        )
+    if penalise_outsiders:
+        outsider = known & ~np.isin(snapshot.community, labels)
+        multiplier[outsider] = COMMUNITY_OUTSIDER_PENALTY
+    scores *= multiplier
+
+
+def normalise(scores: np.ndarray, *, threshold: float) -> float:
+    """Scale scores so the best is 1.0. Returns the divisor used. In place.
+
+    Reported rather than hidden because it is the only reason a fact seeded at
+    exactly 1.0 can come back as something else, which is otherwise a confusing
+    thing to see in a trace.
+    """
+    if scores.size == 0:
+        return 1.0
+    kept = scores[scores >= threshold]
+    if kept.size == 0:
+        return 1.0
+    peak = float(kept.max())
+    if peak > 0.0:
+        scores /= peak
+        return peak
+    return 1.0
+
+
+def ranked(
+    scores: np.ndarray, snapshot: AdjacencySnapshot, *, threshold: float
+) -> list[tuple[str, float]]:
+    """Facts at or above ``threshold``, best first, ties broken on fact id.
+
+    The tie-break is part of the contract, not a detail. An entity-seeded walk
+    puts every directly-linked fact at exactly the same score, so a large group
+    arrives at the cut-off together and which of them survives ``top_k`` is
+    decided entirely by how ties are ordered. Two implementations that agreed on
+    every score but not on this returned different results for the same query.
+    """
+    keep = np.flatnonzero(scores >= threshold)
+    pairs = [(snapshot.node_ids[i], float(scores[i])) for i in keep]
+    pairs.sort(key=lambda item: (-item[1], item[0]))
+    return pairs

package/src/superlocalmemory/server/api.py

@@ -39,6 +39,7 @@ from fastapi.middleware.gzip import GZipMiddleware
 from pydantic import BaseModel
 import uvicorn
 
+from superlocalmemory.core.config import CANONICAL_RECALL_LIMIT
 from superlocalmemory.server.security_middleware import SecurityHeadersMiddleware
 from superlocalmemory.server.routes.helpers import SLM_VERSION
 from superlocalmemory.infra.data_root import DynamicStatePath
@@ -60,7 +61,7 @@ UI_DIR = Path(__file__).resolve().parent.parent / "ui"
 
 class SearchRequest(BaseModel):
     query: str
-    limit: int = 10
+    limit: int = CANONICAL_RECALL_LIMIT
     min_score: float = 0.3
 
 
@@ -246,12 +247,30 @@ def create_app() -> FastAPI:
                 "<p><a href='/docs'>API Documentation</a></p>"
                 "</body></html>"
             )
-        from superlocalmemory.server.asset_versions import render_index
         from superlocalmemory import __version__ as _v
 
-        return render_index(
-            index_path, UI_DIR, substitutions={"__SLM_VERSION__": _v},
-        )
+        # __SLM_VERSION__ was substituted only by the unified daemon, so the
+        # dashboard's upgrade detector did nothing when served from here.
+        # Asset versioning is cosmetic. It must never be why this page 500s.
+        #
+        # The import is deferred (house style, keeps startup lean), which means
+        # it resolves at REQUEST time — so when `pip install -e .` replaced the
+        # installed package underneath a running daemon, this route began
+        # answering "Internal Server Error" on the dashboard while every other
+        # endpoint was fine. A stale hand-written version string is a trifle; a
+        # blank page is not. Fall back to the file as written.
+        try:
+            from superlocalmemory.server.asset_versions import render_index
+
+            return render_index(
+                index_path, UI_DIR, substitutions={"__SLM_VERSION__": _v},
+            )
+        except Exception as exc:  # noqa: BLE001 — serve the page regardless
+            logger.warning(
+                "asset version rewrite unavailable, serving index.html as "
+                "written: %s: %s", type(exc).__name__, exc,
+            )
+            return index_path.read_text().replace("__SLM_VERSION__", _v)
 
     @application.get("/health")
     async def health_check():