@hviana/sema 0.2.3 → 0.2.4

package/dist/src/mind/reasoning.js

@@ -8,6 +8,19 @@ import { resolve } from "./primitives.js";
 import { corpusN } from "./traverse.js";
 import { follow, haloSiblings, project } from "./match.js";
 import { joinWithBridge, pivotInto } from "./resonance.js";
+/** Whether `bytes` is a proper byte-subspan of `query` — already present in
+ *  the question, so voicing it back only restates part of what was asked,
+ *  never answers it.  The exact guard recallByResonance already applies to
+ *  its OWN grounding candidates (tier 1's `restates`, tier 2's subspan
+ *  check, tier 0b's argument-binding subspan check) — every mechanism that
+ *  walks a LEARNT CONTINUATION EDGE past an already-vetted grounding
+ *  (reason()'s own hops below, and CAST's `projectCounterfactual` seat
+ *  substitution — see cast.ts) needs the same guard applied to what the
+ *  walk turns up, since `follow()`/`chooseNext`/`pivotInto` know nothing of
+ *  the query at all — only of what structurally continues what. */
+export function restatesQuery(query, bytes) {
+    return bytes.length < query.length && indexOf(query, bytes, 0) >= 0;
+}
 /** Extend a grounded answer forward across facts (multi-hop reasoning).
  *  Pivots on the longest unconsumed learnt context each answer contains,
  *  then follows the pivot's continuation to the next fact.  Repeats up
@@ -81,7 +94,8 @@ export async function reason(ctx, query, answer, preConsumed, pre) {
             const fwd = await follow(ctx, curId, qv);
             const fwdId = fwd !== null ? resolve(ctx, fwd) : null;
             if (fwd !== null && !bytesEqual(fwd, cur) &&
-                (fwdId === null || !consumed.has(fwdId))) {
+                (fwdId === null || !consumed.has(fwdId)) &&
+                !restatesQuery(query, fwd)) {
                 consumeAll(curId);
                 t ??= ctx.trace?.enter("reason", [
                     rItem(startedFrom, "grounded"),
@@ -98,7 +112,7 @@ export async function reason(ctx, query, answer, preConsumed, pre) {
             break;
         const fc = await follow(ctx, pivot, qv);
         consumeAll(pivot);
-        if (fc === null || bytesEqual(fc, cur))
+        if (fc === null || bytesEqual(fc, cur) || restatesQuery(query, fc))
             break;
         t ??= ctx.trace?.enter("reason", [rItem(startedFrom, "grounded")]);
         ctx.trace?.step("pivotStep", [rItem(cur, "answer"), rNode(ctx, pivot, "pivot")], [rItem(fc, "answer", resolve(ctx, fc) ?? undefined)], "pivot on the shared span this answer contains, then step forward across that fact");
@@ -158,6 +172,48 @@ unclimbed = false) {
         ...rest.map((r) => rNode(ctx, r.anchor, "point", r.vote)),
     ]);
     for (const root of rest) {
+        // DISPERSION: this root's contributing regions are confined to a
+        // single cluster (see Attention.clusters) — one local neighbourhood of
+        // the query, not several separate places.  Raw region count already
+        // failed to discriminate a coincidental match from a genuine further
+        // topic (test/24 gap 3.1 vs test/35's echo); dispersion is a different
+        // question — not how MUCH evidence, but how many separate PLACES in the
+        // query corroborate it — and a coincidental match is structurally
+        // confined to one cluster no matter how strongly it resonates.
+        //
+        // EXCEPTION: crossRegionVotes' own joint conclusions (a query naming
+        // two attributes that were only ever learnt TOGETHER — test/34's own
+        // binding corpus) are inherently ONE fused context and are pooled from
+        // a single synthetic region, so they always read as one cluster even
+        // though they already, by construction, account for both original
+        // mentions.  `breadth` (dominates — the same > half-the-query bar used
+        // everywhere else) still correctly recognises these: a genuine joint
+        // binding explains the MAJORITY of the query's regions on its own,
+        // which a coincidental echo never does (verified: test/35's echo tops
+        // out at 0.40).  So a root is trusted when EITHER measure alone
+        // indicates real signal — excluded only when BOTH are weak.  Cheap and
+        // synchronous — checked before the async already-answered walk below.
+        if (root.clusters < 2 && root.breadth <= 0.5) {
+            ctx.trace?.step("singleCluster", [rNode(ctx, root.anchor, "point", root.vote)], [], "this point's evidence is confined to one local neighbourhood of the query — not trusted as an independent topic");
+            continue;
+        }
+        // ALREADY ANSWERED: this root's own learnt continuation — the same
+        // content-addressed walk reason()'s echo guard already trusts
+        // (`ctx.store.prevCount(qId) > 0`), here applied per-candidate instead
+        // of to the whole query — is VERBATIM present later in the query.  A
+        // query that embeds both an exchange's ask and its own already-given
+        // reply (a conversation's turn plus its own prior answer, concatenated
+        // raw by addTurn — or any caller pasting a transcript into one
+        // respond() call; the check is Mind-bookkeeping-free, so it treats both
+        // identically) has already spoken this root's answer — fusing it in
+        // again would only restate it.  Deliberately NOT a magnitude measure:
+        // it fires on exact content-addressed recurrence, not on how strongly
+        // the root resonates.
+        const cont = await follow(ctx, root.anchor, qv);
+        if (cont !== null && cont.length > 0 && indexOf(query, cont, root.end) >= 0) {
+            ctx.trace?.step("alreadyAnswered", [rNode(ctx, root.anchor, "point", root.vote)], [rItem(cont, "continuation")], "this point's own learnt continuation already appears later in the query — already answered, not fused");
+            continue;
+        }
         const g = await project(ctx, root.anchor, qv);
         if (g === null || g.length === 0)
             continue;

package/dist/src/mind/recognition.js

@@ -7,7 +7,7 @@
 import { rItem } from "./trace.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 { chainReach, leafIdAt, leafIdRun } from "./canonical.js";
 import { isChunk } from "../sema.js";
 /** Decompose a byte stream into every stored form that leads somewhere
  *  (has a continuation edge or a halo).  Two complementary readings:
@@ -23,13 +23,37 @@ import { isChunk } from "../sema.js";
  *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus. */
 export function recognise(ctx, bytes) {
     // 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) {
+    // respondTurn() (where the map persists across calls).  ALWAYS consulted,
+    // regardless of tracing — matching perceive()'s own memo, which carries no
+    // trace gate at all.  This memo is NOT an optional accelerator: recogniseImpl
+    // walks the query's perceived tree via foldTree, whose subtree-resolution
+    // fast path (see primitives.ts) skips invoking `visit` — and therefore
+    // skips EMITTING SITES — for any subtree already cached in
+    // ctx._resolvedSubtrees.  A multi-turn conversation's stable-prefix fold
+    // deliberately shares node OBJECTS across turns, so by the second call on
+    // the exact same bytes, large swaths of the tree are already cached and
+    // foldTree stops short of recursing into them — a second recogniseImpl
+    // call on the SAME bytes is not idempotent; it silently finds FEWER sites
+    // than the first (observed live: 31 sites → 5 on an immediate repeat
+    // call).  Skipping this memo "only while tracing" used to mean every
+    // traced turn re-ran recogniseImpl from scratch at every one of the many
+    // call sites that recognise the same query (cover, reason, articulate...),
+    // each subsequent call silently more incomplete than the last — measurably
+    // changing which mechanism grounds the answer, not just costing time.  The
+    // trace step must still fire on every call regardless (a cache hit is not
+    // silent), so it is emitted here directly instead of only inside
+    // recogniseImpl.
+    if (ctx.recogniseMemo) {
         const key = latin1Key(bytes);
         const hit = ctx.recogniseMemo.get(key);
-        if (hit !== undefined)
+        if (hit !== undefined) {
+            ctx.trace?.step("recognise", [rItem(bytes, "query")], hit.sites.map((s) => rItem(bytes.subarray(s.start, s.end), "form", s.payload, [
+                s.start,
+                s.end,
+            ])), `decompose the query into ${hit.sites.length} learnt form(s) that ` +
+                `lead somewhere (over ${hit.leaves.length} perceived leaves) [cached]`);
             return hit;
+        }
         const fresh = recogniseImpl(ctx, bytes);
         ctx.recogniseMemo.set(key, fresh);
         return fresh;
@@ -71,9 +95,20 @@ function recogniseImpl(ctx, bytes) {
     // silence.  Atoms stay available as leaves (PASS-carried literals) and
     // through exact tier-0 resolution regardless.
     const atomsAreHubs = atomIsHub(ctx, corpusN(ctx));
+    // Distinct probes (structural exact match, canon fallback, edge trims at
+    // several offsets) can legitimately re-derive the SAME (start, end, id)
+    // site from different tree nodes — a wide edge-trim search is exactly
+    // this on purpose (see below).  Duplicate site entries are not wrong
+    // evidence, but they double the weight cover's derivation search gives
+    // that span, distorting its cost model — the same span must count once.
+    const seen = new Set();
     const emit = (start, end, id) => {
         if (id < 0 && atomsAreHubs)
             return;
+        const key = start + "," + end + "," + id;
+        if (seen.has(key))
+            return;
+        seen.add(key);
         if (leadsSomewhere(ctx, id)) {
             sites.push({ start, end, payload: id });
         }
@@ -90,11 +125,96 @@ function recogniseImpl(ctx, bytes) {
         // 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) {
+        // canonicalizer was injected or the store has no canon index.  A raw
+        // leaf (n.kids === null) is single-byte and handled by the byte-atom
+        // path above instead — canon equivalence only applies to composites.
+        else if (n.kids !== null) {
             const cid = canonResolve(ctx, bytes.subarray(start, end));
             if (cid !== null)
                 emit(start, end, cid);
+            // The edge-trim fallbacks below remove 1 byte from a side; the
+            // remainder must still be a composite (>= 2 bytes, the same floor
+            // n.kids !== null enforces above) rather than degenerate into
+            // single-byte-atom territory, which atomIsHub already governs
+            // separately.
+            else if (end - start - 1 >= 2) {
+                // The chunk's own boundary is drawn by content geometry, not by
+                // any notion of "form" — it can include one edge byte the query's
+                // fold happened to attach here that the trained span never had
+                // (e.g. a separator from the preceding chunk).  The core has no
+                // idea what that byte means; it only knows resolve()/canonResolve
+                // are self-verifying (hash-then-verify, same discipline as every
+                // content lookup here), so a blind one-byte-shorter guess on
+                // either edge costs nothing when wrong and is trustworthy when it
+                // hits.  Two extra probes, only on the already-failed miss path.
+                const left = resolve(ctx, bytes.subarray(start + 1, end));
+                if (left !== null)
+                    emit(start + 1, end, left);
+                const right = resolve(ctx, bytes.subarray(start, end - 1));
+                if (right !== null)
+                    emit(start, end - 1, right);
+                // A misalignment wider than one byte (e.g. more than one edge
+                // separator swallowed) is not itself geometry-quantized — the
+                // WRITE side's canonical index (canonicalWindows) interns sliding
+                // W−1/W-length windows over leaf ids at EVERY offset, not just
+                // radix-aligned ones (see canonical.ts) — so the offset that
+                // recovers a trained span can be anything, not a multiple of W.
+                // What IS bounded is how far it's worth looking: chainReach(W)=W²,
+                // the same reach the canonical pass (tryChain) trusts for a chain
+                // rebuilt off the query's own fold.  Every candidate offset is
+                // gated by store.findBranch(leafIds) first — the SAME cheap,
+                // fold-free existence check tryChain already uses — so the extra
+                // resolve() fold (the real cost) is only paid when a branch could
+                // plausibly exist there, not for every offset.  The node itself is
+                // also bounded to chunk-scale (end - start <= W²): widening this at
+                // whole-query/root scale can rediscover a smaller subtree's own
+                // content as a second, overlapping site the structural walk's own
+                // finer recursion already emits correctly on its own — a duplicate
+                // that downstream derivation can stitch into a wrong answer.
+                const W = ctx.space.maxGroup;
+                for (let k = 1; end - start <= W * W && k <= W * W && start + k < end - 1; k++) {
+                    const lIds = leafIdRun(ctx, bytes, start + k, end);
+                    if (lIds !== null && store.findBranch(lIds) !== null) {
+                        const eLeft = resolve(ctx, bytes.subarray(start + k, end));
+                        if (eLeft !== null)
+                            emit(start + k, end, eLeft);
+                    }
+                    const rIds = leafIdRun(ctx, bytes, start, end - k);
+                    if (rIds !== null && store.findBranch(rIds) !== null) {
+                        const eRight = resolve(ctx, bytes.subarray(start, end - k));
+                        if (eRight !== null)
+                            emit(start, end - k, eRight);
+                    }
+                }
+                // A REAL extra word at the left edge (a discourse connective like
+                // "And " prepended to a follow-up turn — not boundary noise, actual
+                // content the injected canonicalizer has no equivalence for) shows
+                // up as a canon-miss too big for the chunk-scale search above: the
+                // turn is its OWN segment (stable-prefix folded independently — see
+                // mind.ts's _growContext), so it can be turn/segment-scale, not
+                // chunk-scale.  Widening the size bound itself reopens the root-
+                // scale false-positive this module already fixed once (test/46);
+                // widening the SEARCH instead — trying every position up to W
+                // chunk-widths from the left edge that the query's OWN fold treats
+                // as a chunk boundary (`starts`, the same set the canonical pass
+                // privileges with full chain reach) — does not: `starts.has(p)` is
+                // fold EVIDENCE the query produced on its own (a leaf-parent chunk
+                // like "And " is visited, and its start added to `starts`, before
+                // this composite ever runs — foldTree is post-order), never a blind
+                // guess.  Bounded to W candidates, each an O(1) set lookup before
+                // paying for the real canonResolve fold — canonResolve, not
+                // resolve()/findBranch, because the gap here is often exactly the
+                // kind of equivalence (case, in the live trace) canon exists for,
+                // not just an exact-content coincidence.
+                for (let k = 1; k <= W; k++) {
+                    const p = start + k * W;
+                    if (p >= end - 1 || !starts.has(p))
+                        continue;
+                    const cid = canonResolve(ctx, bytes.subarray(p, end));
+                    if (cid !== null)
+                        emit(p, end, cid);
+                }
+            }
         }
         if (isChunk(n)) {
             starts.add(start);

package/dist/src/mind/traverse.js

@@ -6,7 +6,6 @@
 // The PROJECTIONS built on these walks (follow, conceptHop, reverseContext,
 // project) live in match.ts — the elementary match-and-project operation.
 import { cosine } from "../vec.js";
-import { consensusFloor } from "../geometry.js";
 import { gistOf, read } from "./primitives.js";
 const structCaches = new WeakMap();
 function getStructCache(ctx) {
@@ -440,20 +439,22 @@ export function chooseNext(ctx, id, guide) {
             bestMass = mass;
         }
     }
-    // A pick among GENUINELY competing continuations still needs to clear the
-    // same genuine-corroboration floor {@link consensusFloor} draws for every
-    // other consumer that turns distinct-context support into a vote (the
-    // climb's recallByResonance/commitVotes) — below it, "most corroborated"
-    // is only the least-thin echo among several, not real evidence.  Gated to
-    // corpus scale large enough that this echo is even possible (the same
-    // scale {@link atomIsHub} already switches on for the identical reason:
-    // at small N every edge IS the evidence there is).  A hub id has no
-    // meaningful "distinct context" reading at all (id < 0 atoms are excluded
-    // from this path already, since chooseNext only ever sees real edges).
-    const N = corpusN(ctx);
-    if (capped.length > 1 && atomIsHub(ctx, N) && bestSupport < consensusFloor(N)) {
-        return undefined;
-    }
+    // NO consensusFloor gate here (tried and reverted — see
+    // test/40-choosenext-scale-guard.test.mjs): that floor is calibrated for
+    // POOLED, IDF-weighted CLIMB VOTES (recallByResonance, commitVotes), where
+    // each corroborating region contributes at most ln N and the floor grows
+    // with N exactly as that per-region ceiling does (HOW_IT_WORKS.md §8.6).
+    // `bestSupport` here is a different kind of quantity — a raw prevCount of
+    // how many training contexts predicted ONE destination, bounded by how
+    // often that specific fact was retold, never by corpus size N.  Gating an
+    // N-invariant count against an N-growing threshold guarantees failure
+    // once N is large enough, discarding genuinely, structurally dominant
+    // edges (observed: a fact corroborated 2-to-1-1-1 refused at N≈325K,
+    // falling back to a noisy concept-hop).  The loop above already IS the
+    // "genuinely competing" test: a tie leaves first-inserted as the pick
+    // (test/30's own pinned behaviour); a strict winner is real evidence
+    // regardless of corpus scale.  Matches HOW_IT_WORKS.md §25's own
+    // chooseNext pseudocode, which has no such floor.
     // Trace is built lazily — the filter + map below only execute when a
     // trace listener is attached, so the common (no-trace) path pays only
     // for the prevCount calls in the loop above, never for extra rItemShort

package/dist/src/mind/types.d.ts

@@ -74,6 +74,23 @@ export interface Attention {
      *  consensus; one that does not is a coincidental single-region echo —
      *  see test/35-attention-confidence.test.mjs. */
     breadth: number;
+    /** DISPERSION: the number of distinct clusters this point's contributing
+     *  regions form, merging any two whose gap is under one river-fold
+     *  quantum W.  Neither breadth NOR raw region count discriminates a
+     *  genuine further topic from a coincidental echo (both were tried and
+     *  falsified — breadth starves a genuine, evenly-split multi-topic query,
+     *  since no root in a real N-way split can exceed half the vote; raw
+     *  count doesn't separate them either, since a short, structurally simple
+     *  echo racks up as many corroborating regions as a real topic does).
+     *  Dispersion asks a different question: not how MUCH evidence, but how
+     *  many separate PLACES in the query corroborate it.  A coincidental
+     *  match — one local phrase resonating with an unrelated stored form —
+     *  is structurally confined to ONE cluster no matter how strong its vote;
+     *  a genuine further topic is named in its own distinctive wording
+     *  somewhere the query's scaffolding does not reach, always a SEPARATE
+     *  cluster from whatever else corroborates it.  See
+     *  test/37-cluster-dispersion-fusion.test.mjs. */
+    clusters: number;
 }
 /** Both read-outs of one consensus climb. */
 export interface AttentionRead {
@@ -226,9 +243,29 @@ export interface MindContext extends GraphSearchHost {
 export declare const ALL = 2147483647;
 /** Splice every chosen span in order — the whole cover as one byte string. */
 export declare function spliceAll(segs: Seg[]): Uint8Array | null;
+/** Whether a chosen span RESTATES the query rather than answering it: its
+ *  SUBSTITUTED bytes (an edge followed from a recognised site, not the
+ *  site's own literal text read back) already occur elsewhere in the query
+ *  — the same principle recall.ts's tiers apply to a whole-query projection
+ *  ("a projection that is a proper byte-subspan of the query restates part
+ *  of the question").  A LITERAL span (the site's own bytes, unchanged) is
+ *  exempt: naming what's already there at its OWN position is not a
+ *  substitution.  A recognised site that is itself an entire PRIOR TURN of
+ *  a multi-turn query is exactly this shape: it carries a genuine learnt
+ *  continuation, but that continuation is something the asker already said
+ *  moments later in the SAME query, not a new answer.  Below one river
+ *  window, byte overlap is chance, not evidence — the same floor
+ *  identityBar and reachThreshold hold every other structural-overlap claim
+ *  to. */
+export declare function segRestatesQuery(s: Seg, query: Uint8Array, queryLen: number, W: number): boolean;
 /** Lift the answer out of the cover for think: the recognised region, free of
- *  the asker's surrounding (unrecognised) framing. */
-export declare function liftAnswer(segs: Seg[], queryLen: number): Uint8Array | null;
+ *  the asker's surrounding (unrecognised) framing — and free of any chosen
+ *  span that only RESTATES content the query already contains (see {@link
+ *  segRestatesQuery}).  A restating span is excluded from both the framing
+ *  (lo/hi) decision and the final concatenation: it is stale, not a second
+ *  answer, but the OTHER spans a derivation chose are independent evidence
+ *  and must not be discarded along with it. */
+export declare function liftAnswer(segs: Seg[], queryLen: number, query: Uint8Array, W: number): Uint8Array | null;
 /** The CHANGED NODES of a freshly-perceived `tree` against the node ids a previous
  *  tracked deposit interned (`prevSeen`). */
 export declare function changedNodes(tree: Sema, ids: Map<Sema, number>, prevSeen: Set<number>): Sema[];

package/dist/src/mind/types.js

@@ -2,7 +2,7 @@
 //
 // GraphSearchHost is defined first (minimal imports) so GraphSearch can import
 // it without pulling in the full MindContext.
-import { concatBytes } from "../bytes.js";
+import { bytesEqual, concatBytes, indexOf } from "../bytes.js";
 import { dominates } from "../geometry.js";
 // ═══════════════════════════════════════════════════════════════════════════
 // FREE FUNCTIONS (pure, no state)
@@ -15,13 +15,44 @@ export function spliceAll(segs) {
         return null;
     return concatBytes(segs.map((s) => s.bytes));
 }
+/** Whether a chosen span RESTATES the query rather than answering it: its
+ *  SUBSTITUTED bytes (an edge followed from a recognised site, not the
+ *  site's own literal text read back) already occur elsewhere in the query
+ *  — the same principle recall.ts's tiers apply to a whole-query projection
+ *  ("a projection that is a proper byte-subspan of the query restates part
+ *  of the question").  A LITERAL span (the site's own bytes, unchanged) is
+ *  exempt: naming what's already there at its OWN position is not a
+ *  substitution.  A recognised site that is itself an entire PRIOR TURN of
+ *  a multi-turn query is exactly this shape: it carries a genuine learnt
+ *  continuation, but that continuation is something the asker already said
+ *  moments later in the SAME query, not a new answer.  Below one river
+ *  window, byte overlap is chance, not evidence — the same floor
+ *  identityBar and reachThreshold hold every other structural-overlap claim
+ *  to. */
+export function segRestatesQuery(s, query, queryLen, W) {
+    if (!s.rec)
+        return false;
+    const literal = s.j - s.i === s.bytes.length &&
+        bytesEqual(s.bytes, query.subarray(s.i, s.j));
+    if (literal)
+        return false;
+    return s.bytes.length >= W && s.bytes.length < queryLen &&
+        indexOf(query, s.bytes, 0) >= 0;
+}
 /** Lift the answer out of the cover for think: the recognised region, free of
- *  the asker's surrounding (unrecognised) framing. */
-export function liftAnswer(segs, queryLen) {
+ *  the asker's surrounding (unrecognised) framing — and free of any chosen
+ *  span that only RESTATES content the query already contains (see {@link
+ *  segRestatesQuery}).  A restating span is excluded from both the framing
+ *  (lo/hi) decision and the final concatenation: it is stale, not a second
+ *  answer, but the OTHER spans a derivation chose are independent evidence
+ *  and must not be discarded along with it. */
+export function liftAnswer(segs, queryLen, query, W) {
+    const restated = segs.map((s) => segRestatesQuery(s, query, queryLen, W));
     const recognised = [];
-    for (let k = 0; k < segs.length; k++)
-        if (segs[k].rec)
+    for (let k = 0; k < segs.length; k++) {
+        if (segs[k].rec && !restated[k])
             recognised.push(k);
+    }
     if (recognised.length === 0)
         return null;
     if (recognised.length === 1) {
@@ -42,13 +73,13 @@ export function liftAnswer(segs, queryLen) {
         if (s.computed && s.i > 0)
             return s.bytes;
         if (dominates(s.j - s.i, queryLen)) {
-            return concatBytes(segs.map((x) => x.bytes));
+            return concatBytes(segs.filter((_, k) => !restated[k]).map((x) => x.bytes));
         }
         return s.bytes;
     }
     const lo = recognised[0];
     const hi = recognised[recognised.length - 1];
-    return concatBytes(segs.slice(lo, hi + 1).map((x) => x.bytes));
+    return concatBytes(segs.slice(lo, hi + 1).filter((_, k) => !restated[lo + k]).map((x) => x.bytes));
 }
 /** The CHANGED NODES of a freshly-perceived `tree` against the node ids a previous
  *  tracked deposit interned (`prevSeen`). */

package/dist/src/store.d.ts

@@ -139,8 +139,17 @@ export interface Store {
      *  question is decided, with per-page work bounded by `limit`. */
     containersSlice(child: NodeId, offset: number, limit: number): NodeId[];
     nodeCount(): number;
-    /** The k nodes whose gist resonates most with v. */
-    resonate(v: Vec, k: number): Promise<Hit[]>;
+    /** The k nodes whose gist resonates most with v.  `exhaustive` widens the
+     *  IVF probe to every cluster (see {@link AbstractStore.efFor}'s doc) —
+     *  for refusal-path-only callers where an approximate top-√C-clusters
+     *  search is not the same discriminator as the caller's own byte-exact
+     *  verification (the substitution bridge's proposal channel): a rarer
+     *  paraphrase can score lower than hundreds of unrelated hits by pure
+     *  fold-geometry structural distance (a middle-of-string mismatch
+     *  perturbs the tree hash far more than a tail mismatch of the same
+     *  byte length) and so never even reach a probed cluster, no matter how
+     *  large k is — k only reorders WITHIN the clusters already probed. */
+    resonate(v: Vec, k: number, exhaustive?: boolean): Promise<Hit[]>;
     /** Mark a node as a RESONANCE TARGET — promote its gist into the content
      *  index so {@link resonate} can find it.  A node's gist is captured at intern
      *  but indexed LAZILY (only targets are indexed; the ~99.5% intermediate DAG
@@ -593,7 +602,7 @@ export declare abstract class AbstractStore implements Store {
      *
      *  Iterative explicit-queue walk: the call stack never sees tree depth. */
     protected indexSubtree(root: NodeId): void;
-    resonate(v: Vec, k: number): Promise<Hit[]>;
+    resonate(v: Vec, k: number, exhaustive?: boolean): Promise<Hit[]>;
     indexedVectorCount(): number;
     lastResonateReads(): number;
     /** How many physical compaction attempts have failed this session.  Zero in

package/dist/src/store.js

@@ -1135,7 +1135,7 @@ export class AbstractStore {
         }
     }
     // ── Soft resonance ─────────────────────────────────────────────────────
-    async resonate(v, k) {
+    async resonate(v, k, exhaustive = false) {
         await this._ensureReady();
         // Synchronous flush of any buffered index writes: the FIRST resonance
         // after a large ingest pays that flush here, so it shows up in respond
@@ -1148,14 +1148,20 @@ export class AbstractStore {
         // same values still hits.  Lazy-init: null after any index write; the
         // first miss after a flush recreates it.  When voteRegions resonates
         // identical perceived sub-regions, only the first call descends the ANN.
-        const rk = vecKey(v) + ":" + k;
+        const rk = vecKey(v) + ":" + k + (exhaustive ? ":x" : "");
         const cache = this._resonateCache;
         if (cache) {
             const hit = cache.get(rk);
             if (hit !== undefined)
                 return hit;
         }
-        const results = this._vecContentQuery(normalize(copy(v)), k * this.overfetch, this.efFor(this._vecContentClusterCount()));
+        const clusters = this._vecContentClusterCount();
+        const results = this._vecContentQuery(normalize(copy(v)), k * this.overfetch, 
+        // Exhaustive: probe every cluster (ef ≥ 4·clusters guarantees the
+        // IVF's own ef→nprobe=ceil(ef/4) mapping reaches all of them) — the
+        // natural ceiling for a search that is ALREADY refusal-path-only and
+        // must not miss a candidate hiding in an unprobed cluster.
+        exhaustive ? 4 * clusters : this.efFor(clusters));
         const out = [];
         for (const r of results) {
             const id = r.id;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "type": "module",
   "main": "dist/src/index.js",