@hviana/sema 0.2.9 → 0.4.0

package/src/mind/traverse.ts

@@ -32,6 +32,50 @@ interface StructCache {
 }
 const structCaches = new WeakMap<object, StructCache>();
 
+// ── The shared ancestor-reach memo ──────────────────────────────────────
+//
+// `edgeAncestors` is a pure function of (node, N) over a read-only store —
+// asking never writes — so its result is reusable for as long as the store
+// is not written to.  There used to be TWO memos and they never met: the
+// climb built a private one per call (computeAttention), while
+// `Precomputed.reachMemo` — documented as "one response-scoped memo serves
+// every mechanism that prices commonality" — was reached only by confluence.
+// The climb is by far the biggest consumer.
+//
+// Keyed off `ctx.climbMemo`'s OBJECT IDENTITY, exactly like the struct cache
+// above, which buys the right lifetime for free: a plain respond() has a
+// fresh climbMemo, so the memo is response-scoped; a conversation turn has
+// the conversation's persistent one, so it is conversation-scoped.  That
+// matters — the stable-prefix fold makes each turn's subtree independent of
+// what follows, so 59–70% of a later turn's climb regions are byte-identical
+// repeats of an earlier turn's (measured on a 4-turn session), and every one
+// of them used to re-climb from cold.
+//
+// Budgeted, not unbounded (AGENTS §2.12): past the cap the whole map is
+// dropped and re-derived, costing a cold climb and never a wrong answer.
+const REACH_MEMO_MAX = 100_000;
+const reachCaches = new WeakMap<object, Map<number, AncestorReach>>();
+
+/** The reach memo this response should use — see the note above.
+ *
+ *  A TRACED response always gets a fresh, empty one.  `AncestorReach`'s
+ *  `visited`/`maxDepth`/`saturation` fields are populated only when a trace
+ *  is attached, so an entry deposited by an untraced earlier turn would
+ *  silently black out the reach detail of a later traced one; and the trace's
+ *  reach payload is serialised by ITERATING this map, which must therefore
+ *  hold what THIS climb consulted, not the whole conversation's history.
+ *  Consistent with AGENTS §2.11: a traced response is a different machine —
+ *  never benchmark with a trace attached. */
+export function sharedReachMemo(
+  ctx: MindContext,
+): Map<number, AncestorReach> {
+  if (ctx.trace !== null || ctx.climbMemo === null) return new Map();
+  let m = reachCaches.get(ctx.climbMemo);
+  if (m === undefined) reachCaches.set(ctx.climbMemo, m = new Map());
+  else if (m.size >= REACH_MEMO_MAX) m.clear();
+  return m;
+}
+
 function getStructCache(ctx: MindContext): StructCache | null {
   if (ctx.climbMemo === null) return null;
   let c = structCaches.get(ctx.climbMemo);
@@ -134,7 +178,7 @@ export function edgeAncestors(
   // 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 bound0 = Math.ceil(Math.sqrt(Math.max(2, contextCount)));
+    const bound0 = boundFor(contextCount);
     const reach: AncestorReach = {
       roots: [],
       contextsReached: 0,
@@ -147,6 +191,8 @@ export function edgeAncestors(
             observed: atomReach(ctx, contextCount),
             limit: bound0,
           },
+          visited: 0,
+          maxDepth: 0,
         }
         : {}),
     };
@@ -154,7 +200,7 @@ export function edgeAncestors(
     return reach;
   }
 
-  const bound = Math.ceil(Math.sqrt(contextCount));
+  const bound = boundFor(contextCount);
   const roots: number[] = [];
   const seen = new Set<number>([id]);
   const ctxSeen = new Set<number>();
@@ -201,7 +247,21 @@ export function edgeAncestors(
   // while the context account never decided.
   let lateral = 0;
 
+  // CLIMB READ-OUT (pure instrumentation, same contract as satStop): the
+  // parallel `depths` stack mirrors every push/pop of `stack`, so a node's
+  // ascent distance is known at its pop.  Allocated only when a trace is
+  // requested; the climb itself never reads any of these back.
+  const depths: number[] | null = ctx.trace ? [] : null;
+  let curDepth = 0;
+  let visitedCount = 0;
+  let maxDepth = 0;
+
   const visit = (x: number): boolean => {
+    if (ctx.meter) ctx.meter.ancestorVisits++;
+    if (depths) {
+      visitedCount++;
+      if (curDepth > maxDepth) maxDepth = curDepth;
+    }
     const hasNx = cachedHasNext(ctx, x, structCache);
     const pc = cachedPrevCount(ctx, x, structCache);
     if (hasNx || pc > 0) {
@@ -251,6 +311,7 @@ export function edgeAncestors(
       if (!seen.has(p)) {
         seen.add(p);
         stack.push(p);
+        depths?.push(curDepth + 1);
         fresh++;
       }
     }
@@ -274,7 +335,10 @@ export function edgeAncestors(
 
   const stack: number[] = [];
   const containment = !cachedHasParents(ctx, id, structCache);
-  if (!containment) stack.push(id);
+  if (!containment) {
+    stack.push(id);
+    depths?.push(0);
+  }
 
   // The containment seed is STREAMED in pages of √N: a distinctive window's
   // containers (which converge on one or two contexts, however many chunks
@@ -295,15 +359,19 @@ export function edgeAncestors(
         if (!seen.has(c)) {
           seen.add(c);
           stack.push(c);
+          depths?.push(1);
         }
       }
       if (stack.length === 0) {
-        if (containerOff === 0) stack.push(id); // no containers at all
-        else break;
+        if (containerOff === 0) {
+          stack.push(id); // no containers at all
+          depths?.push(0);
+        } else break;
       }
     }
     while (stack.length > 0) {
       let x = stack.pop()!;
+      if (depths) curDepth = depths.pop()!;
       // TRANSPARENT-CHAIN HOP: a node with no edges in or out and exactly one
       // parent contributes nothing here — no root, no context, no lateral
       // entry — so the run to its first non-transparent ancestor is skipped
@@ -321,6 +389,9 @@ export function edgeAncestors(
         for (let i = 1; i < run.length; i++) seen.add(run[i]);
         if (dup) continue;
         x = top;
+        // The chain's interior hops are part of the terminal's ascent
+        // distance — count them exactly as a node-at-a-time ascent would.
+        if (depths) curDepth += run.length - 1;
       }
       if (!visit(x)) {
         saturated = true;
@@ -334,6 +405,7 @@ export function edgeAncestors(
     contextsReached: ctxSeen.size,
     saturated,
     ...(saturated && satStop ? { saturation: satStop } : {}),
+    ...(depths ? { visited: visitedCount, maxDepth } : {}),
   };
   memo?.set(id, reach);
   return reach;
@@ -368,8 +440,7 @@ export function atomReach(ctx: MindContext, contextCount: number): number {
  *  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)));
+  return atomReach(ctx, contextCount) > boundFor(contextCount);
 }
 
 /** Whether a node LEADS SOMEWHERE — it bears a continuation edge or a halo.
@@ -417,7 +488,17 @@ export function corpusN(ctx: MindContext): number {
  *  materialised list.  {@link hubCap} is the list-side reading of the same
  *  convention. */
 export function hubBound(ctx: MindContext): number {
-  return Math.ceil(Math.sqrt(corpusN(ctx)));
+  return boundFor(corpusN(ctx));
+}
+
+/** √N for an EXPLICIT context count — the ctx-free reading of {@link
+ *  hubBound}, for the callers inside this module that are handed a count
+ *  rather than a context ({@link edgeAncestors}, {@link atomIsHub}).  The
+ *  floor at 2 matches {@link corpusN}'s, so both readings agree for every
+ *  input: the two used to be spelled out inline, once WITH the floor and
+ *  once without, in the same function. */
+function boundFor(contextCount: number): number {
+  return Math.ceil(Math.sqrt(Math.max(2, contextCount)));
 }
 
 /** Cap a candidate list at the hub bound √N (insertion order) — the ONE

package/src/mind/types.ts

@@ -9,6 +9,7 @@ import type { BoundedMap, Store } from "../store.js";
 import type { Space } from "../sema.js";
 import type { Alphabet } from "../alphabet.js";
 import type { MindConfig } from "../config.js";
+import type { Meter } from "../meter.js";
 import type {
   ComputedResult,
   DerivationItem,
@@ -19,7 +20,7 @@ import type {
   Site,
 } from "./graph-search.js";
 import type { Rationale } from "./rationale.js";
-import type { FoldPyramid, Grid, StableFold } from "../geometry.js";
+import type { Grid, StableFold } from "../geometry.js";
 
 /** One {@link MindContext._depositTrees} entry — see that field's doc. */
 export interface DepositCacheEntry {
@@ -27,8 +28,6 @@ export interface DepositCacheEntry {
    *  strictly increasing proper offsets, each a previously-deposited
    *  whole-context length.  Empty for a first-seen (single-turn) input. */
   boundaries: number[];
-  /** Plain-fold pyramid (first-seen inputs only). */
-  pyramid?: FoldPyramid;
   /** Stable-prefix segment folds (grown-context inputs only). */
   stable?: StableFold;
   /** The continuation bytes this ctxInput was paired with in ingestPair, if
@@ -59,6 +58,10 @@ export type Input = string | Uint8Array | Grid | Grid[];
 /** The host capabilities GraphSearch consults during a cover.  MindContext
  *  extends this so the Mind can pass itself as the host. */
 export interface GraphSearchHost {
+  /** Work accumulator, or null/absent when nothing is profiling — see
+   *  src/meter.ts.  Declared here (not only on MindContext) so the graph
+   *  search can report its chart effort without importing mind code. */
+  readonly meter?: Meter | null;
   resolve(bytes: Uint8Array): number | null;
   recogniseSpan?(bytes: Uint8Array): {
     sites: ReadonlyArray<Site>;
@@ -173,6 +176,19 @@ export interface RegionVote {
    *  to "one region" just because it collapsed to one pooled axiom.
    *  Defaults to 1 when absent. */
   absorbed?: number;
+  /** The SEPARATE query places this vote's evidence occupies, when that is
+   *  more than the one contiguous run [start, end].  A cross-region junction
+   *  vote is pooled as a single synthetic region spanning its endpoints and
+   *  the gap between them, so `[start, end]` reads as ONE place — yet the
+   *  vote exists precisely because two non-adjacent regions each voted and
+   *  only their conjunction resolved.  Cluster counting (Attention.clusters)
+   *  asks "how many separate places in the query corroborate this?", and
+   *  answering it from the merged span makes every joint binding look like a
+   *  single local neighbourhood; fusion's dispersion gate then drops it
+   *  unless it also explains most of the whole query, which a binding inside
+   *  a MULTI-topic query structurally cannot.  Absent for an ordinary
+   *  per-region vote, where the merged span already is the truth. */
+  parts?: readonly (readonly [number, number])[];
 }
 
 /** The structural gate that first decided an {@link edgeAncestors} climb was
@@ -205,6 +221,17 @@ export interface AncestorReach {
    *  a non-saturated reach, and absent (even when saturated) when no trace
    *  was requested — instrumentation must not allocate when tracing is off. */
   saturation?: SaturationStop;
+  /** The number of nodes the climb actually PROCESSED (popped and examined
+   *  by its visit step; a transparent chain counts as its one terminal).
+   *  Present only when a trace was requested — same contract as
+   *  {@link saturation}: instrumentation must not allocate when tracing is
+   *  off.  Purely a read-out; the climb never consults it. */
+  visited?: number;
+  /** The maximum structural ascent distance (in parent/containment hops,
+   *  transparent-chain interiors counted) from the start node among the
+   *  processed nodes.  Present only when a trace was requested — see
+   *  {@link visited}. */
+  maxDepth?: number;
 }
 
 /** Saturated-interval information for the noise-drop gate. */
@@ -226,6 +253,12 @@ export type AItem =
 
 export interface MindContext extends GraphSearchHost {
   store: Store;
+  /** The work accumulator for the inference call in flight, or null when
+   *  nothing is profiling — see src/meter.ts.  WRITE-ONLY from the engine's
+   *  point of view: no inference decision may read a counter, or the
+   *  determinism contract (AGENTS §2.1) is gone.  Every call site is
+   *  `ctx.meter?.x++`, so an unprofiled response allocates nothing. */
+  meter: Meter | null;
   space: Space;
   alphabet: Alphabet;
   cfg: MindConfig;
@@ -283,8 +316,9 @@ export interface MindContext extends GraphSearchHost {
    *  folds with the SAME stable-prefix fold query-time perception uses
    *  (structural train/inference agreement, load-bearing for recall),
    *  reusing every already-folded segment via `stable` (see StableFold) —
-   *  O(turn) per deposit instead of O(context).  A first-seen input keeps
-   *  the plain fold and caches its `pyramid` (see FoldPyramid).  Purely a
+   *  O(turn) per deposit instead of O(context).  A first-seen input takes the
+   *  same fold with no boundaries at all, and caches the segments it produced
+   *  so a later turn of the same conversation reuses them.  Purely a
    *  performance cache for the FOLD STATE; the boundaries are semantic but
    *  derived only from the deposit sequence itself (an evicted chain falls
    *  back to plain-fold behavior, exactly the pre-boundary shape). */

package/src/store.ts

@@ -31,6 +31,7 @@
 import { addInto, copy, dot, normalize, Vec } from "./vec.js";
 import { DEFAULT_CONFIG, type StoreConfig } from "./config.js";
 import { identityBar } from "./geometry.js";
+import type { Meter } from "./meter.js";
 
 /** A node id: a dense, non-negative integer assigned in creation order. */
 export type NodeId = number;
@@ -226,6 +227,14 @@ export class BoundedMap<K, V> {
 export interface Store {
   readonly D: number;
 
+  /** The work accumulator for the inference call in flight, or null.  The
+   *  Mind attaches one per profiled response and detaches it after (see
+   *  src/meter.ts).  A store MUST only ever write to it — no read may reach
+   *  a decision, or determinism is gone.  An adapter that adds reads of its
+   *  own should bump the matching counter; one that does not simply reports
+   *  less, never wrongly. */
+  meter: Meter | null;
+
   // ── the DAG (hash-consed) ──────────────────────────────────────────────
   /** Insert a leaf, returning its content id. Idempotent. */
   putLeaf(bytes: Uint8Array, gist: Vec): Promise<NodeId>;
@@ -1010,6 +1019,7 @@ export abstract class AbstractStore implements Store {
   // ── DAG traversal ──────────────────────────────────────────────────────
 
   get(id: NodeId): NodeRec | null {
+    if (this.meter) this.meter.nodeRecords++;
     // Byte leaves are implicit — fabricate from the id.
     if (id < 0) {
       return { id, leaf: new Uint8Array([-(id + 1)]), kids: null };
@@ -1030,7 +1040,20 @@ export abstract class AbstractStore implements Store {
    *  counter is what keeps that degradation observable. */
   danglingReads = 0;
 
+  /** {@link Store.meter} — the per-response work accumulator, or null when
+   *  nothing is profiling.  Every read below bumps it through `?.`, so an
+   *  unprofiled store pays one null check per read and allocates nothing. */
+  meter: Meter | null = null;
+
   bytes(id: NodeId): Uint8Array {
+    if (this.meter) {
+      this.meter.byteReads++;
+      // Charged BEFORE the fast path returns, and from the cache entry when
+      // there is one: the volume a caller pulled through is the cost signal
+      // (an unbounded read is unbounded whether or not it was cached).
+      const c = this._bytesCache.get(id);
+      if (c) this.meter.bytesRead += c.length;
+    }
     // Fast path.
     const hit = this._bytesCache.get(id);
     if (hit) return hit;
@@ -1082,7 +1105,9 @@ export abstract class AbstractStore implements Store {
       cache.set(nid, out);
     }
 
-    return cache.get(id) ?? _ZERO;
+    const out = cache.get(id) ?? _ZERO;
+    if (this.meter) this.meter.bytesRead += out.length;
+    return out;
   }
 
   /** First `maxLen` bytes of a node.  Walks only the leftmost branch,
@@ -1093,14 +1118,27 @@ export abstract class AbstractStore implements Store {
    *  may be shared with the byte cache and with other callers — treat them
    *  as read-only.  Mutating one would corrupt every subsequent read. */
   bytesPrefix(id: NodeId, maxLen: number): Uint8Array {
-    if (maxLen <= 0) return _ZERO;
-
     // A FULL read (the ALL sentinel) routes through bytes(), whose
     // reconstruction enters the byte-budget cache.  Without this, the mind's
     // read() — which always passes ALL — re-walked the DAG and re-concatenated
     // on EVERY repeated read of an uncached branch, bypassing the cache that
     // exists precisely for those reconstructions.
     if (maxLen >= 0x7fffffff) return this.bytes(id);
+    // METERING BOUNDARY: this public entry point is charged ONCE per logical
+    // read; the walk below recurses through `_prefix`, which is not charged.
+    // Counting the recursion instead made a single read of an N-byte branch
+    // report as N reads (one per node descended), so `byteReads` measured
+    // tree size rather than read requests — it read as ~1 byte per read.
+    if (this.meter) this.meter.byteReads++;
+    const out = this._prefix(id, maxLen);
+    if (this.meter) this.meter.bytesRead += out.length;
+    return out;
+  }
+
+  /** {@link bytesPrefix}'s recursive body — uncharged; see the metering
+   *  boundary note there. */
+  private _prefix(id: NodeId, maxLen: number): Uint8Array {
+    if (maxLen <= 0) return _ZERO;
 
     // Full-cache hit: bytes() already reconstructed the whole node.
     const full = this._bytesCache.get(id);
@@ -1125,7 +1163,7 @@ export abstract class AbstractStore implements Store {
     let got = 0;
     for (const k of kids) {
       if (got >= maxLen) break;
-      const child = this.bytesPrefix(k, maxLen - got);
+      const child = this._prefix(k, maxLen - got);
       parts.push(child);
       got += child.length;
     }
@@ -1133,6 +1171,7 @@ export abstract class AbstractStore implements Store {
   }
 
   contentLen(id: NodeId, cap = Infinity): number {
+    if (this.meter) this.meter.lenReads++;
     if (id < 0) return 1; // implicit single-byte leaf
     const hit = this._lenCache.get(id);
     if (hit !== undefined) return hit; // exact — valid under any cap
@@ -1159,6 +1198,7 @@ export abstract class AbstractStore implements Store {
   // ── Content-addressed lookup ───────────────────────────────────────────
 
   findLeaf(bytes: Uint8Array): NodeId | null {
+    if (this.meter) this.meter.leafLookups++;
     if (bytes.length === 1) return -(bytes[0] + 1);
     const key = keyOf(bytes);
     const cached = this._leafKey.get(key);
@@ -1169,6 +1209,7 @@ export abstract class AbstractStore implements Store {
   }
 
   findBranch(kids: NodeId[]): NodeId | null {
+    if (this.meter) this.meter.branchLookups++;
     const key = kids.join(",");
     const cached = this._branchKey.get(key);
     if (cached !== undefined) return cached;
@@ -1189,18 +1230,22 @@ export abstract class AbstractStore implements Store {
   // ── Structural parents ─────────────────────────────────────────────────
 
   parents(id: NodeId): NodeId[] {
+    if (this.meter) this.meter.parentReads++;
     return this._dbGetParents(id);
   }
 
   parentsFirst(id: NodeId, limit: number): NodeId[] {
+    if (this.meter) this.meter.parentReads++;
     return this._dbGetParentsFirst(id, limit);
   }
 
   hasParents(id: NodeId): boolean {
+    if (this.meter) this.meter.parentProbes++;
     return this._dbGetParentsFirst(id, 1).length > 0;
   }
 
   chainRun(id: NodeId): readonly NodeId[] {
+    if (this.meter) this.meter.chainRuns++;
     const hit = this._chainMemo.get(id);
     if (hit !== undefined) return hit;
     const run = this._chainWalk(id, CHAIN_DEPTH_CAP);
@@ -1236,12 +1281,14 @@ export abstract class AbstractStore implements Store {
   }
 
   hasContainers(child: NodeId): boolean {
+    if (this.meter) this.meter.containerProbes++;
     if (this._dbContainExists(child)) return true;
     const buf = this._containBuf.get(child);
     return buf !== undefined && buf.size > 0;
   }
 
   containersSlice(child: NodeId, offset: number, limit: number): NodeId[] {
+    if (this.meter) this.meter.containerReads++;
     const out = this._dbGetContainParentsSlice(child, offset, limit);
     if (out.length >= limit) return out;
     // Buffered adds page in AFTER the stored ones.  A buffered parent that is
@@ -1262,6 +1309,7 @@ export abstract class AbstractStore implements Store {
   }
 
   containers(child: NodeId): NodeId[] {
+    if (this.meter) this.meter.containerReads++;
     const stored = this._dbGetContainParents(child);
     const buf = this._containBuf.get(child);
     if (stored.length === 0) return buf ? [...buf] : [];
@@ -1662,9 +1710,13 @@ export abstract class AbstractStore implements Store {
     const cache = this._resonateCache;
     if (cache) {
       const hit = cache.get(rk);
-      if (hit !== undefined) return hit;
+      if (hit !== undefined) {
+        if (this.meter) this.meter.annCacheHits++;
+        return hit;
+      }
     }
 
+    if (this.meter) this.meter.annQueries++;
     const clusters = this._vecContentClusterCount();
     const results = this._vecContentQuery(
       normalize(copy(v)),
@@ -1682,6 +1734,10 @@ export abstract class AbstractStore implements Store {
       if (out.length >= k) break;
     }
 
+    // Vectors the index actually scored for THIS descent — the counter that
+    // exposes a query whose ANN cost is growing with the corpus.
+    if (this.meter) this.meter.annVectorReads += this._vecContentLastReads();
+
     const rc = this._resonateCache ??= new Map();
     if (rc.size >= RESONATE_CACHE_MAX) rc.clear();
     rc.set(rk, out);
@@ -1924,29 +1980,35 @@ export abstract class AbstractStore implements Store {
   }
 
   next(id: NodeId): NodeId[] {
+    if (this.meter) this.meter.edgeReads++;
     return this._dbGetNextEdges(id);
   }
 
   /** {@link Store.hasNext} — one indexed point probe, never a range read. */
   hasNext(id: NodeId): boolean {
+    if (this.meter) this.meter.edgeProbes++;
     return this._dbEdgeSrcExists(id);
   }
 
   prev(id: NodeId): NodeId[] {
+    if (this.meter) this.meter.prevReads++;
     return this._dbGetPrevEdges(id);
   }
 
   nextFirst(id: NodeId, limit: number): NodeId[] {
+    if (this.meter) this.meter.edgeReads++;
     return this._dbGetNextEdgesFirst(id, limit);
   }
 
   prevFirst(id: NodeId, limit: number): NodeId[] {
+    if (this.meter) this.meter.prevReads++;
     return this._dbGetPrevEdgesFirst(id, limit);
   }
 
   /** {@link Store.prevCount}.  Subclasses with an indexed reverse-edge count
    *  should override; this default materialises (correct, not optimal). */
   prevCount(id: NodeId): number {
+    if (this.meter) this.meter.prevProbes++;
     return this._dbGetPrevEdges(id).length;
   }
 
@@ -1964,11 +2026,13 @@ export abstract class AbstractStore implements Store {
   // ── Halos ──────────────────────────────────────────────────────────────
 
   haloMass(id: NodeId): number {
+    if (this.meter) this.meter.haloProbes++;
     const r = this._dbGetHalo(id);
     return r ? r.mass : 0;
   }
 
   halo(id: NodeId): Vec | null {
+    if (this.meter) this.meter.haloReads++;
     const cached = this._haloNorm.get(id);
     if (cached !== undefined) return copy(cached);
     const r = this._dbGetHalo(id);
@@ -1982,6 +2046,7 @@ export abstract class AbstractStore implements Store {
   /** {@link Store.hasHalo} — MUST mirror {@link halo}'s null condition
    *  exactly (row present AND mass ≥ minHaloMass), minus the decode. */
   hasHalo(id: NodeId): boolean {
+    if (this.meter) this.meter.haloProbes++;
     const r = this._dbGetHalo(id);
     return r !== null && r.mass >= this.minHaloMass;
   }
@@ -2018,9 +2083,13 @@ export abstract class AbstractStore implements Store {
     const cache = this._resonateHaloCache;
     if (cache) {
       const hit = cache.get(rk);
-      if (hit !== undefined) return hit;
+      if (hit !== undefined) {
+        if (this.meter) this.meter.annCacheHits++;
+        return hit;
+      }
     }
 
+    if (this.meter) this.meter.haloQueries++;
     const results = this._vecHaloQuery(
       normalize(copy(v)),
       k * this.overfetch,

package/test/14-scaling.test.mjs

@@ -376,16 +376,26 @@ test("inference: input is processed at a roughly constant KB/s (linear, not quad
 
   await mind.respond(queries[queries.length - 1]); // warm up
 
-  const times = [];
-  for (const q of queries) {
-    const samples = [];
-    for (let r = 0; r < 5; r++) {
+  // INTERLEAVED sampling — round-robin across sizes, not size-at-a-time.
+  // The inputs and the store are deterministic, so the WORK per query is
+  // fixed; only wall clock varies.  Sampling one size to completion before
+  // moving on let a single GC/JIT episode land on one size's ENTIRE sample
+  // block, so even `fastest` (min of 5) came back ~2.7x high for that size
+  // alone — a bimodal reading that made the throughput-band ratio below trip
+  // intermittently (observed on both the 1KB point and, more weakly, before
+  // any of this file's callers changed).  Round-robin spreads every episode
+  // across all sizes, so `fastest` sees at least one clean sample each.
+  // This does not weaken the assertion — it removes the sampling artefact
+  // the assertion was reacting to.
+  const samples = queries.map(() => []);
+  for (let r = 0; r < 5; r++) {
+    for (let i = 0; i < queries.length; i++) {
       const t0 = performance.now();
-      await mind.respond(q);
-      samples.push(performance.now() - t0);
+      await mind.respond(queries[i]);
+      samples[i].push(performance.now() - t0);
     }
-    times.push(fastest(samples));
   }
+  const times = samples.map(fastest);
   await mind.store.close();
 
   const rates = bytes.map((b, i) => (b / 1024) / (times[i] / 1000)); // KB/s

package/test/31-audit.test.mjs

@@ -235,8 +235,11 @@ test("H2: the ALU meaning-memo does not change answers across repeat responds",
 // ═══════════════════════════════════════════════════════════════════════
 
 test("I1: containsSpan rejects a sparse subsequence that isSpanShaped accepts", async () => {
+  // The span-shape family lives in the shared match/project family
+  // (match.ts), not inside a mechanism: pipeline-mechanism.ts and
+  // reasoning.ts both consume it, so a mechanism may not own it.
   const { containsSpan, isSpanShaped } = await import(
-    "../dist/src/mind/mechanisms/extraction.js"
+    "../dist/src/mind/match.js"
   );
   const m = newMind();
   await m.ingest([["what is ice?", "ice is frozen water"]]);

package/test/33-multi-candidate.test.mjs

@@ -142,7 +142,19 @@ test("3 — a near-tie between the winner and runner-up emits narrowDecision", a
     ["steel is hard so steel is strong", "strong"],
     ["water is frigid so water is freezing", "freezing"],
   ]);
-  const { steps } = await trace(m, "steel is frigid so steel is ???");
+  // The near-tie has to be REAL: two candidates whose accounted spans are the
+  // same, separated by a single move.  `steel is hard so steel is` is that —
+  // extraction and recall both explain the whole prefix (grades 21011 and
+  // 21010, margin 1).
+  //
+  // The old fixture, `steel is frigid so steel is ???`, was a near-tie only
+  // while CAST could not fire on it: the counterfactual subject and the seat
+  // it fills sit on opposite sides of one recurring structure, and CAST's
+  // subject gate used to reject any point whose alignment continued PAST the
+  // seat — which that very recurrence guarantees.  With CAST firing, it leaves
+  // only "???" unexplained and wins by 22008; a decisive win is the opposite
+  // of what this test pins, and test 3b already covers it.
+  const { steps } = await trace(m, "steel is hard so steel is");
   const narrow = stepsNamed(steps, "narrowDecision");
   assert.equal(narrow.length, 1, "expected exactly one narrowDecision step");
   assert.ok(/margin \d+ grade-unit/.test(narrow[0].note), narrow[0].note);

package/test/36-already-answered-fusion.test.mjs

@@ -69,9 +69,16 @@ test("fuseAttention: a root whose continuation is already answered in the query
   // topic with no such embedded answer.
   const q = enc("greet reply-greet then red then circle");
   const roots = await m.climbAttention(q, 24);
-  const greet = roots.find((r) => r.start === 0);
-  const redCircle = roots.find((r) => r.start !== 0);
-  assert.ok(greet, "expected the 'greet' root at query offset 0");
+  // Roots are identified by the ANCHOR they climbed to, never by the query
+  // offset of the region that got there: which region wins the climb is a
+  // property of the evidence, and the fold's cuts are content-defined, so an
+  // offset test would be asserting where a cut happened to fall.  (It did:
+  // this once read `r.start === 0`, and passed only while the region reaching
+  // `greet` began at byte 0 — it now begins at 6, on the same anchor.)
+  const anchorOf = (r) => dec(m.store.bytesPrefix(r.anchor, 1e9));
+  const greet = roots.find((r) => anchorOf(r) === "greet");
+  const redCircle = roots.find((r) => anchorOf(r) === "red circle");
+  assert.ok(greet, "expected a root anchored on 'greet'");
   assert.ok(redCircle, "expected the 'red circle' binding root");
 
   const guide = gistOf(m, q);

package/test/46-recognise-multibyte-edge.test.mjs

@@ -2,9 +2,9 @@
 // must recover a trained form whose edge misalignment is MORE than one byte
 // (the shipped ±1 fix only covers a single stray edge byte).
 //
-// bytesToTree's plain fold is RADIX-ALIGNED: a chunk's own boundary is a
-// multiple of the geometry's group width W from the LOCAL start of whatever
-// it was folded from (see geometry.ts's FoldPyramid comment).  A query whose
+// bytesToTree's fold is CONTENT-DEFINED: a chunk's own boundary is a cut the
+// bytes chose (see geometry.ts's contentBoundaries), so it moves with the
+// content rather than with an absolute offset.  A query whose
 // recognised span sits at a different local offset than the trained deposit
 // did — e.g. extra leading whitespace, which canon deliberately preserves
 // verbatim at the edges, only collapsing INTERIOR whitespace — shifts every