@hviana/sema 0.1.6 → 0.1.8

package/src/mind/primitives.ts

@@ -4,8 +4,7 @@
 //   Read     — node → bytes   (read)
 
 import { Vec } from "../vec.js";
-import { Sema, Space } from "../sema.js";
-import { Alphabet } from "../alphabet.js";
+import { Sema } from "../sema.js";
 import {
   bytesToTree,
   bytesToTreePyramid,
@@ -15,6 +14,8 @@ import {
   hilbertBytes,
   stackGrids,
 } from "../geometry.js";
+import { canonHash } from "../canon.js";
+import { bytesEqual } from "../bytes.js";
 import { ALL } from "./types.js";
 import type { Input, MindContext } from "./types.js";
 
@@ -24,7 +25,7 @@ import type { Input, MindContext } from "./types.js";
  *  collision-free encoding.  Spans on the perception path are query-scale
  *  (windows, regions, candidate spans), so key construction is far cheaper
  *  than the river fold it deduplicates. */
-function latin1Key(bytes: Uint8Array): string {
+export function latin1Key(bytes: Uint8Array): string {
   // Batched String.fromCharCode — avoids the O(n²) cost of repeated += on
   // potentially-large query spans, and stays well under the ~65536 arg limit.
   const n = bytes.length;
@@ -36,12 +37,19 @@ function latin1Key(bytes: Uint8Array): string {
 }
 
 /** Perceive input into a content-defined tree (the river fold).
- *  Deterministic — identical bytes always produce an identical tree. */
+ *  Deterministic — identical bytes always produce an identical tree.
+ *
+ *  `boundaries` is an optional sorted list of proper byte offsets where the
+ *  fold must split so that each prefix segment folds identically to how it
+ *  folded when it was learned (§10.3 stable-prefix contract).  Only the
+ *  CALLER — who assembled the multi-turn context — knows where those
+ *  boundaries are; the geometry never guesses them from the bytes. */
 export function perceive(
   ctx: MindContext,
   input: Input,
   leafAt?: (i: number) => number | null,
   lookup?: (ids: number[]) => number | null,
+  boundaries?: readonly number[],
 ): Sema {
   if (typeof input === "string" || input instanceof Uint8Array) {
     const bytes = typeof input === "string"
@@ -57,11 +65,25 @@ export function perceive(
         const key = latin1Key(bytes);
         const hit = memo.get(key);
         if (hit !== undefined) return hit;
-        const tree = bytesToTree(ctx.space, ctx.alphabet, bytes);
+        const tree = bytesToTree(
+          ctx.space,
+          ctx.alphabet,
+          bytes,
+          undefined,
+          undefined,
+          boundaries,
+        );
         memo.set(key, tree);
         return tree;
       }
-      return bytesToTree(ctx.space, ctx.alphabet, bytes);
+      return bytesToTree(
+        ctx.space,
+        ctx.alphabet,
+        bytes,
+        undefined,
+        undefined,
+        boundaries,
+      );
     }
     return bytesToTree(ctx.space, ctx.alphabet, bytes, leafAt, lookup);
   }
@@ -136,11 +158,25 @@ export function foldTree(
   start: number,
   visit?: (n: Sema, start: number, end: number, node: number | null) => void,
 ): { end: number; node: number | null } {
+  // Fast path: subtree already resolved (from a previous conversation turn
+  // or an earlier recognition pass).  The pyramid reuses prefix subtrees as
+  // identical Sema objects, so this cache turns foldTree into O(suffix)
+  // instead of O(context) for multi-turn recognition.
+  const cached = ctx._resolvedSubtrees?.get(n);
+  if (cached !== undefined) {
+    const end = start + cached.len;
+    visit?.(n, start, end, cached.id);
+    return { end, node: cached.id };
+  }
+
   if (n.kids === null) {
     const b = n.leaf ?? new Uint8Array(0);
     const end = start + b.length;
     const node = ctx.store.findLeaf(b);
     visit?.(n, start, end, node);
+    if (node !== null && ctx._resolvedSubtrees) {
+      ctx._resolvedSubtrees.set(n, { id: node, len: b.length });
+    }
     return { end, node };
   }
   let pos = start;
@@ -154,6 +190,9 @@ export function foldTree(
   }
   const node = known ? ctx.store.findBranch(kids) : null;
   visit?.(n, start, pos, node);
+  if (node !== null && ctx._resolvedSubtrees) {
+    ctx._resolvedSubtrees.set(n, { id: node, len: pos - start });
+  }
   return { end: pos, node };
 }
 
@@ -162,7 +201,70 @@ export function foldTree(
  *  unknown. */
 export function resolve(ctx: MindContext, bytes: Uint8Array): number | null {
   if (bytes.length === 0) return null;
-  return foldTree(ctx, perceive(ctx, bytes), 0).node;
+  const exact = foldTree(ctx, perceive(ctx, bytes), 0).node;
+  if (exact !== null) return exact;
+  return canonResolve(ctx, bytes);
+}
+
+/** Equivalence-class resolution: when the exact content-addressed lookup
+ *  misses, find a stored node whose CANONICAL key equals the span's — the
+ *  store's canon index proposes candidates by key hash, and each is verified
+ *  by re-canonicalizing its bytes (hash-then-verify, like every content
+ *  lookup).  Among verified candidates, one that leads somewhere (has a
+ *  continuation edge) is preferred; ties break to the lowest id — a corpus
+ *  property, not a seed property.  Null when the response carries no
+ *  canonicalizer, the store has no canon index, or nothing verifies. */
+export function canonResolve(
+  ctx: MindContext,
+  bytes: Uint8Array,
+): number | null {
+  const canon = ctx.canon;
+  const store = ctx.store;
+  if (canon === null || !store.canonFind) return null;
+  if (bytes.length < 2) return null;
+  const memo = ctx.canonMemo;
+  const memoKey = memo ? latin1Key(bytes) : "";
+  if (memo) {
+    const hit = memo.get(memoKey);
+    if (hit !== undefined) return hit;
+  }
+  const set = (v: number | null): number | null => {
+    memo?.set(memoKey, v);
+    return v;
+  };
+  const key = canon(bytes);
+  if (key.length === 0) return set(null);
+  // A stored form that IS canonical is not in the index (buildCanonIndex
+  // skips identity rows) — the exact content-addressed lookup of the
+  // canonical bytes finds it directly.
+  if (key.length !== bytes.length || !bytesEqual(key, bytes)) {
+    const direct = foldTree(ctx, perceive(ctx, key), 0).node;
+    if (direct !== null) return set(direct);
+  }
+  const candidates = store.canonFind(canonHash(key));
+  if (candidates.length === 0) return set(null);
+  let best: number | null = null;
+  let bestLeads = false;
+  for (const id of candidates) {
+    const bytesOf = read(ctx, id);
+    const stored = canon(bytesOf);
+    if (stored.length !== key.length || !bytesEqual(stored, key)) continue;
+    // The index stores FLAT content twins; the id the exact path would have
+    // resolved for these bytes is their FOLD — the deposit-shaped node that
+    // carries the edges and halos.  Re-folding the candidate's bytes lands
+    // on exactly the node the canonical-case query would have found.
+    const folded = foldTree(ctx, perceive(ctx, bytesOf), 0).node;
+    const use = folded ?? id;
+    const leads = store.hasNext(use) || store.haloMass(use) > 0;
+    if (
+      best === null || (leads && !bestLeads) ||
+      (leads === bestLeads && use < best)
+    ) {
+      best = use;
+      bestLeads = leads;
+    }
+  }
+  return set(best);
 }
 
 /** Walk a perceived tree in POST-ORDER with byte offsets — children before

package/src/mind/recognition.ts

@@ -7,8 +7,15 @@
 import { rItem } from "./trace.js";
 
 import type { MindContext, Recognition, Segment } from "./types.js";
-import { foldTree, gistOf, perceive, resolve } from "./primitives.js";
-import { leadsSomewhere } from "./traverse.js";
+import {
+  canonResolve,
+  foldTree,
+  gistOf,
+  latin1Key,
+  perceive,
+  resolve,
+} from "./primitives.js";
+import { atomIsHub, corpusN, leadsSomewhere } from "./traverse.js";
 import { chainReach, leafIdAt } from "./canonical.js";
 import { isChunk, type Sema } from "../sema.js";
 import type { Leaf, Site } from "./graph-search.js";
@@ -26,15 +33,15 @@ import type { Leaf, Site } from "./graph-search.js";
  *
  *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus. */
 export function recognise(ctx: MindContext, bytes: Uint8Array): Recognition {
-  // Per-response memo (see MindContext.recogniseMemo): think, articulate and
-  // the pre-consume pass all recognise the same byte objects; each repeat is
-  // O(n·maxGroup²) store probes.  Skipped while tracing so every call still
-  // emits its rationale step.
+  // Content-keyed memo — works for both single-turn respond() and multi-turn
+  // respondTurn() (where the map persists across calls).  Skipped while
+  // tracing so every call still emits its rationale step.
   if (ctx.recogniseMemo && !ctx.trace) {
-    const hit = ctx.recogniseMemo.get(bytes);
+    const key = latin1Key(bytes);
+    const hit = ctx.recogniseMemo.get(key);
     if (hit !== undefined) return hit;
     const fresh = recogniseImpl(ctx, bytes);
-    ctx.recogniseMemo.set(bytes, fresh);
+    ctx.recogniseMemo.set(key, fresh);
     return fresh;
   }
   return recogniseImpl(ctx, bytes);
@@ -64,7 +71,19 @@ function recogniseImpl(ctx: MindContext, bytes: Uint8Array): Recognition {
     return id;
   };
 
+  // Byte atoms (implicit negative-id single-byte leaves) are admitted as
+  // recognised sites only while atoms can still DISCRIMINATE at this corpus
+  // scale (see {@link atomIsHub}).  On a small store a single-letter fact
+  // ("a" → "A") is genuine learnt content and its site is essential; on a
+  // large one every letter of every query would otherwise become a
+  // "recognised form" — the bridge then finds junction connectors between
+  // bare letters, cover follows edges hanging off them, and pure noise
+  // ("qq8f3kz9…") grounds to an arbitrary learnt sentence instead of
+  // silence.  Atoms stay available as leaves (PASS-carried literals) and
+  // through exact tier-0 resolution regardless.
+  const atomsAreHubs = atomIsHub(ctx, corpusN(ctx));
   const emit = (start: number, end: number, id: number) => {
+    if (id < 0 && atomsAreHubs) return;
     if (leadsSomewhere(ctx, id)) {
       sites.push({ start, end, payload: id });
     }
@@ -78,6 +97,15 @@ function recogniseImpl(ctx: MindContext, bytes: Uint8Array): Recognition {
       leaves.push({ start, end, bytes: n.leaf ?? new Uint8Array(0), node });
     }
     if (node !== null) emit(start, end, node);
+    // Canonical fallback: a subtree whose exact content-addressed lookup
+    // missed may still be a stored form under the response's equivalence
+    // (case, width, whitespace — whatever the injected canonicalizer says).
+    // O(subtree bytes) per miss, memoised per response; a no-op when no
+    // canonicalizer was injected or the store has no canon index.
+    else if (end - start >= 2) {
+      const cid = canonResolve(ctx, bytes.subarray(start, end));
+      if (cid !== null) emit(start, end, cid);
+    }
     if (isChunk(n)) {
       starts.add(start);
       // Try every sub-span within this leaf-parent.

package/src/mind/traverse.ts

@@ -115,6 +115,30 @@ export function edgeAncestors(
   const hit = memo?.get(id);
   if (hit !== undefined) return hit;
 
+  // BYTE-ATOM COMMONALITY.  A single-byte leaf (implicit negative id) has no
+  // structural parents BY CONSTRUCTION — atoms are never linked into the kid
+  // or contain tables — so this climb cannot observe its containment at all.
+  // The walk below would see only the atom's own direct edges and report
+  // contextsReached ≈ 1, turning the MOST common content in the store into
+  // the MOST discriminative voter (observed on a 325K-context store: every
+  // recognised single-letter site voted full ln N for the one fact whose
+  // continuation is that letter, and their pooled sum out-voted every
+  // genuine anchor).  An unmeasurable containment must not default to
+  // "maximally rare": it is bounded below by the uniform expectation over
+  // the byte alphabet — N contexts, each at least one chunk of up to W of
+  // the 256 possible atoms, reach ≥ N·W/256 contexts per atom on average
+  // (see {@link atomReach}).  When that floor itself exceeds the hub bound
+  // √N the atom is a hub at this corpus scale and the climb abstains
+  // (saturated) — the atom's own edges remain fully traversable (tier-0
+  // exact recall, chooseNext, project); only its say as a consensus voter
+  // is withdrawn.  On a small store the floor stays ≤ √N and the atom
+  // climbs exactly as before, so single-letter facts keep working.
+  if (id < 0 && atomIsHub(ctx, contextCount)) {
+    const reach = { roots: [], contextsReached: 0, saturated: true };
+    memo?.set(id, reach);
+    return reach;
+  }
+
   const bound = Math.ceil(Math.sqrt(contextCount));
   const roots: number[] = [];
   const seen = new Set<number>([id]);
@@ -257,6 +281,29 @@ export function prevOf(ctx: MindContext, id: number): number[] {
   return ctx.store.prev(id);
 }
 
+/** The uniform-expectation floor on a byte atom's corpus commonality: N
+ *  learnt contexts, each at least one perception chunk of up to W of the 256
+ *  possible byte values, contain a given atom in ≥ N·W/256 contexts on
+ *  average.  An atom's TRUE containment is unmeasurable (atoms carry no
+ *  kid/contain links by construction), so this floor is the honest stand-in:
+ *  derived entirely from the corpus scale N, the perception window W, and
+ *  the alphabet size — never tuned. */
+export function atomReach(ctx: MindContext, contextCount: number): number {
+  return Math.max(
+    1,
+    Math.ceil((contextCount * ctx.space.maxGroup) / 256),
+  );
+}
+
+/** Whether a byte atom is a hub at this corpus scale — its commonality floor
+ *  {@link atomReach} exceeds the hub bound √N.  Below it (small stores) an
+ *  atom votes and is recognised exactly as any stored form; above it the
+ *  alphabet is scaffolding everywhere and abstains. */
+export function atomIsHub(ctx: MindContext, contextCount: number): boolean {
+  return atomReach(ctx, contextCount) >
+    Math.ceil(Math.sqrt(Math.max(2, contextCount)));
+}
+
 /** Whether a node LEADS SOMEWHERE — it bears a continuation edge or a halo.
  *  The admission predicate recognition filters sites with (HOW_IT_WORKS
  *  §15.3): a form that leads nowhere contributes nothing to any derivation.

package/src/mind/types.ts

@@ -144,28 +144,37 @@ export interface MindContext extends GraphSearchHost {
   cfg: MindConfig;
   search: GraphSearch;
   trace: Rationale | null;
-  climbMemo: WeakMap<Uint8Array, Map<string, AttentionRead>> | null;
-  /** Per-response memo of {@link recognise} keyed by the byte-array OBJECT
-   *  (think, articulate, and the post-grounding pre-consume all recognise the
-   *  same query/answer objects).  Valid because the store is read-only while
-   *  a response is in flight; bypassed when a trace is attached so every
-   *  recognise still emits its rationale step.  Null outside respond(). */
-  recogniseMemo: WeakMap<Uint8Array, Recognition> | null;
-  /** Per-response memo of {@link perceive} keyed by the byte-array OBJECT —
-   *  the GENERAL memo the result-level ones (recogniseMemo, climbMemo,
-   *  _gistCache) each partially compensate for: resolve(), gistOf(), and
-   *  every mechanism's re-perception of the same query/answer object hit it
-   *  (a reason hop used to fold the same answer three times).  Valid because
-   *  the store is read-only while a response is in flight and perception is
-   *  a pure function of bytes; only inference-shaped calls (plain Uint8Array,
-   *  no leafAt/lookup capabilities) are memoised, so the deposit path never
-   *  sees it.  Keyed by CONTENT (latin1 of the bytes), not object identity —
-   *  mechanisms materialise the same span in fresh subarrays constantly
-   *  (measured on a trained store: 46% of one response's perceptions were
-   *  byte-identical repeats an identity key missed).  NOT bypassed under
-   *  trace — perception emits no rationale steps, so there is nothing a memo
-   *  hit could swallow.  Null outside respond(). */
+  /** The content canonicalizer for THIS response, or null — injected by the
+   *  modality entry point (respondText passes the text canonicalizer; a
+   *  binary respond passes none).  Resolution uses it as a fallback: when
+   *  the exact content-addressed lookup misses, the span's canonical key is
+   *  probed against the store's canon index (see src/canon.ts).  The core
+   *  never inspects what the equivalence IS. */
+  canon: ((bytes: Uint8Array) => Uint8Array) | null;
+  /** Per-response memo of canonical-fallback resolutions, keyed by the
+   *  span's latin1 content key.  Null outside respond(). */
+  canonMemo: Map<string, number | null> | null;
+  /** Memo of the consensus climb — content-keyed (latin1) so results
+   *  persist across conversation turns where the same byte spans recur.
+   *  Null outside respond(); during respondTurn() the conversation's
+   *  persistent map is swapped in. */
+  climbMemo: Map<string, Map<string, AttentionRead>> | null;
+  /** Memo of {@link recognise} — content-keyed (latin1) so recognised
+   *  forms carry forward across conversation turns.  Bypassed while a
+   *  trace is attached.  Null outside respond(). */
+  recogniseMemo: Map<string, Recognition> | null;
+  /** Memo of {@link perceive} — content-keyed (latin1).  The general
+   *  cache the result-level memos each partially compensate for.  NOT
+   *  bypassed under trace — perception emits no rationale steps.
+   *  Null outside respond(). */
   perceiveMemo: Map<string, Sema> | null;
+  /** Subtree-resolution cache: Sema node → its store id and byte length.
+   *  Populated by {@link foldTree} during inference; checked before
+   *  walking children.  When a conversation's pyramid reuses prefix
+   *  subtrees, this cache lets {@link recognise} skip them entirely —
+   *  O(suffix) instead of O(context).  Mind-lifetime (WeakMap keys are
+   *  the Sema objects the pyramid keeps alive). */
+  _resolvedSubtrees: WeakMap<Sema, { id: number; len: number }> | null;
   _edgeGuide: Vec | null;
   _edgeChoice: Map<number, number>;
   _prevSeen: Set<number> | null;

package/src/store-sqlite.ts

@@ -134,6 +134,18 @@ CREATE TABLE IF NOT EXISTS contain (
   id      INTEGER PRIMARY KEY,
   parents BLOB NOT NULL
 );
+-- CANONICAL-FORM index (Store.canonAdd/canonFind): h is the 32-bit hash of a
+-- node's CANONICAL content key (the modality's canonicalizer output — case-
+-- folded, whitespace-collapsed text, etc.; the store never sees the key
+-- itself, only its hash).  Same hash-then-verify discipline as idx_node_h:
+-- the caller re-canonicalizes each candidate's bytes before trusting it, so
+-- a collision costs a read, never a wrong id.  WITHOUT ROWID on (h, id):
+-- the composite key IS the lookup index and gives free dedup.
+CREATE TABLE IF NOT EXISTS canon (
+  h  INTEGER NOT NULL,
+  id INTEGER NOT NULL,
+  PRIMARY KEY (h, id)
+) WITHOUT ROWID;
 CREATE TABLE IF NOT EXISTS snapshot (
   id INTEGER PRIMARY KEY CHECK (id = 1),
   data BLOB NOT NULL
@@ -241,6 +253,10 @@ export class SQliteStore extends AbstractStore implements Store {
   private _selPrev: any = null;
   private _setMeta: any = null;
   private _getMeta: any = null;
+  private _insCanon: any = null;
+  private _selCanon: any = null;
+  private _cntCanon: any = null;
+  private _selContentFrom: any = null;
   private _delMeta: any = null;
   private _insSnapshot: any = null;
   private _selSnapshot: any = null;
@@ -990,6 +1006,58 @@ export class SQliteStore extends AbstractStore implements Store {
     this._delMeta.run(key);
   }
 
+  // -- Canonical-form index (Store optional capability) --
+
+  canonAdd(h: number, id: number): void {
+    if (!this._insCanon) {
+      this._insCanon = this.sqlite!.prepare(
+        "INSERT OR IGNORE INTO canon (h, id) VALUES (?, ?)",
+      );
+    }
+    // Join the deferred write transaction (committed by flush/commit), so a
+    // bulk index build coalesces instead of paying autocommit per row.
+    this._dbBeginTx();
+    this._insCanon.run(h, id);
+  }
+
+  canonFind(h: number): number[] {
+    if (!this._selCanon) {
+      this._selCanon = this.sqlite!.prepare(
+        "SELECT id FROM canon WHERE h = ?",
+      );
+    }
+    return (this._selCanon.all(h) as Array<{ id: number }>).map((r) => r.id);
+  }
+
+  canonCount(): number {
+    if (!this._cntCanon) {
+      this._cntCanon = this.sqlite!.prepare(
+        "SELECT count(*) AS c FROM canon",
+      );
+    }
+    return (this._cntCanon.get() as { c: number }).c;
+  }
+
+  eachContent(
+    cb: (id: number, bytes: Uint8Array) => void,
+    fromId = 0,
+  ): void {
+    if (!this._selContentFrom) {
+      // Content-bearing nodes are FLAT branches: leaf present, kids an
+      // empty (zero-length) blob — the same population PART 2 of the
+      // diagnostics calls "distinct content spans".
+      this._selContentFrom = this.sqlite!.prepare(
+        "SELECT id, leaf FROM node " +
+          "WHERE id >= ? AND leaf IS NOT NULL " +
+          "AND (kids IS NULL OR length(kids) = 0)",
+      );
+    }
+    for (const row of this._selContentFrom.iterate(fromId)) {
+      const r = row as { id: number; leaf: Uint8Array };
+      cb(r.id, new Uint8Array(r.leaf));
+    }
+  }
+
   // -- Snapshot --
 
   protected _dbSaveSnapshot(bytes: Uint8Array): void {
@@ -1048,6 +1116,10 @@ export class SQliteStore extends AbstractStore implements Store {
     return this.content ? this.content.physicalSize : 0;
   }
 
+  protected _vecContentClusterCount(): number {
+    return this.content ? this.content.clusterCount : 0;
+  }
+
   protected _vecContentCompact(): void {
     this.content!.compact();
   }
@@ -1099,6 +1171,10 @@ export class SQliteStore extends AbstractStore implements Store {
     return this.halos ? this.halos.physicalSize : 0;
   }
 
+  protected _vecHaloClusterCount(): number {
+    return this.halos ? this.halos.clusterCount : 0;
+  }
+
   protected _vecHaloCompact(): void {
     this.halos!.compact();
   }

package/src/store.ts

@@ -417,6 +417,33 @@ export interface Store {
    *  the node has no halo row. */
   haloMass(id: NodeId): number;
 
+  // ── canonical-form index (optional capability) ─────────────────────────
+  // A small hash index from CANONICAL content keys to node ids, enabling
+  // equivalence-class resolution ("WHAT" finds the stored "What") without
+  // the store knowing what the equivalence IS: the canonicalizer lives with
+  // the modality (see src/canon.ts) and is applied by the CALLER — the store
+  // only maps 32-bit key hashes to candidate ids, and the caller verifies
+  // canon(stored bytes) === key before trusting any candidate (the same
+  // hash-then-verify discipline as the node table's own `h` index).
+  // Backends that do not implement the capability leave all three absent;
+  // resolution then simply has no canonical fallback.
+
+  /** Record that node `id`'s canonical key hashes to `h`.  Idempotent. */
+  canonAdd?(h: number, id: NodeId): void;
+  /** All candidate node ids whose canonical key hashes to `h` (collisions
+   *  included — the caller verifies). */
+  canonFind?(h: number): NodeId[];
+  /** Number of (h, id) rows in the canon index — 0 means never built. */
+  canonCount?(): number;
+  /** Visit every content-bearing node (flat branch: `leaf` present, no
+   *  kids) — the population a canonical index is built over.  `fromId`
+   *  restricts the scan to ids ≥ fromId, so an index refresh after further
+   *  training only visits the new rows. */
+  eachContent?(
+    cb: (id: NodeId, bytes: Uint8Array) => void,
+    fromId?: NodeId,
+  ): void;
+
   // ── lifecycle ──────────────────────────────────────────────────────────
   size(): Promise<number>;
   saveSnapshot(bytes: Uint8Array): Promise<void>;
@@ -724,6 +751,7 @@ export abstract class AbstractStore implements Store {
   protected abstract _vecContentSize(): number;
   protected abstract _vecContentLastReads(): number;
   protected abstract _vecContentPhysicalSize(): number;
+  protected abstract _vecContentClusterCount(): number;
   protected abstract _vecContentCompact(): void;
   /** Live content-index entries whose INTERNAL id is > `after`, as
    *  {ext, internal} pairs in internal-id order.  Internal ids are monotone
@@ -759,8 +787,24 @@ export abstract class AbstractStore implements Store {
    *  the tombstone-ratio compaction trigger compares physical size against. */
   protected abstract _vecHaloSize(): number;
   protected abstract _vecHaloPhysicalSize(): number;
+  protected abstract _vecHaloClusterCount(): number;
   protected abstract _vecHaloCompact(): void;
 
+  /** Derived query breadth for a partitioned index of C clusters: probe √C
+   *  of them (the same √-of-the-population convention as the hub bound √N).
+   *  The IVF maps ef → nprobe as ceil(ef/4), so ef = 4·⌈√C⌉ probes exactly
+   *  ⌈√C⌉ clusters.  A FIXED efSearch stops scaling the moment the
+   *  collection outgrows it: at 4,270 clusters the default 64 probed 16
+   *  clusters (0.4%), and an exact stored match of a query routinely sat in
+   *  an unprobed cluster — recall silently degraded as the store grew.  The
+   *  configured efSearch remains the floor for small collections. */
+  protected efFor(clusterCount: number): number {
+    return Math.max(
+      this.efSearch,
+      4 * Math.ceil(Math.sqrt(Math.max(1, clusterCount))),
+    );
+  }
+
   // ── Config ─────────────────────────────────────────────────────────────
 
   protected _D: number;
@@ -1615,7 +1659,7 @@ export abstract class AbstractStore implements Store {
     const results = this._vecContentQuery(
       normalize(copy(v)),
       k * this.overfetch,
-      this.efSearch,
+      this.efFor(this._vecContentClusterCount()),
     );
     const out: Hit[] = [];
     for (const r of results) {
@@ -1966,7 +2010,7 @@ export abstract class AbstractStore implements Store {
     const results = this._vecHaloQuery(
       normalize(copy(v)),
       k * this.overfetch,
-      this.efSearch,
+      this.efFor(this._vecHaloClusterCount()),
     );
     const out: Hit[] = [];
     for (const r of results) {