@hviana/sema 0.2.9 → 0.4.0

package/dist/src/mind/reasoning.js

@@ -5,7 +5,7 @@
 import { rItem, rNode } from "./trace.js";
 import { bytesEqual, indexOf } from "../bytes.js";
 import { resolve } from "./primitives.js";
-import { corpusN } from "./traverse.js";
+import { hubBound } 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
@@ -45,19 +45,19 @@ export async function reason(ctx, query, answer, preConsumed, pre) {
     // convention every fan-out decision uses (first √N in the relation's own
     // read order); a pivot suppressed only by a beyond-cap neighbour may now
     // fire — the same visibility trade chooseNext documents.
-    const hubBound = Math.ceil(Math.sqrt(corpusN(ctx)));
+    const bound = hubBound(ctx);
     const consumeNode = (id) => {
         if (id === null)
             return;
         consumed.add(id);
-        for (const p of ctx.store.prevFirst(id, hubBound))
+        for (const p of ctx.store.prevFirst(id, bound))
             consumed.add(p);
     };
     const consumeAll = (id) => {
         if (id === null)
             return;
         consumeNode(id);
-        for (const n of ctx.store.nextFirst(id, hubBound))
+        for (const n of ctx.store.nextFirst(id, bound))
             consumed.add(n);
     };
     // Pre-consume whatever the grounding stage already spoke for.  The halo
@@ -90,7 +90,7 @@ export async function reason(ctx, query, answer, preConsumed, pre) {
         // absorbing it would repeat content the grounding stage already spoke
         // for, so a consumed fixpoint falls through to the pivot step instead.
         if (curId !== null &&
-            ctx.store.nextFirst(curId, hubBound).some((n) => !consumed.has(n))) {
+            ctx.store.nextFirst(curId, bound).some((n) => !consumed.has(n))) {
             const fwd = await follow(ctx, curId, qv);
             const fwdId = fwd !== null ? resolve(ctx, fwd) : null;
             if (fwd !== null && !bytesEqual(fwd, cur) &&
@@ -133,7 +133,13 @@ export async function fuseAttention(ctx, query, primary, pre,
  *  primary's own source; that assumption is exactly backwards when
  *  primary is unclimbed.  Absent or false preserves the original
  *  behaviour exactly. */
-unclimbed = false) {
+unclimbed = false, 
+/** The query spans `primary`'s own grounding stands on — used ONLY to place
+ *  primary in the fused reading order (see below).  Resolved by the caller,
+ *  which is the layer that knows how a given grounding records its evidence;
+ *  fuseAttention just reads a position from it.  Empty or absent preserves
+ *  the original behaviour exactly. */
+primarySpans = []) {
     // When the answer is structurally drawn from the query itself
     // (extraction), it already spans all the query's pieces — fusion
     // would only add noise from unrelated stored contexts.  The gate is
@@ -162,8 +168,34 @@ unclimbed = false) {
     if (forest.length === 0 || (forest.length <= 1 && !lonePromotes)) {
         return primary;
     }
+    // WHERE THE QUERY ASKED FOR IT.  The sort below orders the fused pieces by
+    // query position, which is the whole point of the `start` field: a
+    // multi-topic answer should read in the order the question posed its
+    // topics.  Every ROOT carries its own start.  `primary` did not — it was
+    // given forest[0].start, the FIRST attention root's position, which is
+    // primary's own source only when primary happens to come from that root.
+    // When it does not, primary is sorted to a position it never occupied.
+    //
+    // Observed live: "What is the capital of France? And what is 2 + 2?"
+    // answered "4The capital city of France is Paris." — the ALU result, whose
+    // evidence is the "2 + 2" span near the END of the query, inherited the
+    // France root's start of 0 and sorted ahead of the France answer.  Both
+    // pieces were right; only the order was.
+    //
+    // primary's own position is the earliest query byte its grounding stands
+    // on.  `accounted` is the cost-ladder read of that and is authoritative
+    // when non-empty; when it is empty the grounding is a pure COMPUTATION,
+    // whose evidence is its computed span — the same cost-ladder-vs-coverage
+    // distinction think() already draws for the fusion remainder ("`accounted`
+    // alone undercounts this ... cover prices its computed spans at near-zero
+    // and deliberately leaves them out"), read here for position instead of
+    // for coverage.  With neither, nothing is known and the old behaviour
+    // (forest[0].start) stands.
+    const primaryStart = primarySpans.length > 0
+        ? primarySpans.reduce((m, [s]) => Math.min(m, s), Infinity)
+        : forest[0].start;
     const pieces = [
-        { start: forest[0].start, bytes: primary },
+        { start: primaryStart, bytes: primary },
     ];
     const qv = pre.guide; // once, not per root
     const rest = lonePromotes ? forest : forest.slice(1);
@@ -237,4 +269,4 @@ unclimbed = false) {
 }
 // (resonance.js is already a static dependency above — `bridge` — so the old
 // dynamic import of pivotInto guarded against a cycle that does not exist.)
-import { containsSpan } from "./mechanisms/extraction.js";
+import { containsSpan } from "./match.js";

package/dist/src/mind/recognition.js

@@ -47,6 +47,8 @@ export function recognise(ctx, bytes) {
         const key = latin1Key(bytes);
         const hit = ctx.recogniseMemo.get(key);
         if (hit !== undefined) {
+            if (ctx.meter)
+                ctx.meter.recogniseHits++;
             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,
@@ -61,11 +63,20 @@ export function recognise(ctx, bytes) {
     return recogniseImpl(ctx, bytes);
 }
 function recogniseImpl(ctx, bytes) {
+    if (ctx.meter) {
+        ctx.meter.recognitions++;
+        ctx.meter.recognisedBytes += bytes.length;
+    }
     const store = ctx.store;
     const sites = [];
     const leaves = [];
     const splits = new Set();
     const starts = new Set();
+    // The same cuts in ASCENDING order.  The post-order walk below visits
+    // leaf-parents left to right, so appending as they are added keeps this
+    // sorted with no comparison — which is what lets the composite search find
+    // its candidates by binary search instead of rescanning the whole set.
+    const startList = [];
     if (bytes.length === 0)
         return { sites, leaves, splits, starts };
     // Span-resolve memo for THIS call: the structural pass (sub-runs inside
@@ -105,6 +116,33 @@ function recogniseImpl(ctx, bytes) {
     const emit = (start, end, id) => {
         if (id < 0 && atomsAreHubs)
             return;
+        // A SITE MUST SPAN ONE RIVER WINDOW.  Below W, byte overlap is chance,
+        // not evidence — the principle identityBar already states ("below one
+        // river window, byte overlap is chance") and the bridge's attestedQ
+        // already applies ("spans shorter than W carry no window of their own").
+        // No new constant.
+        //
+        // This REPLACES the false premise it used to share with fuse() and
+        // tryChain: those gates asked "does this offset sit on a fold boundary?"
+        // and read the answer from `starts`, which is exactly {0, W, 2W, …}
+        // because riverFold groups fixed-arity — arithmetic, not evidence.
+        //
+        // Measured on the 17.9M-node store, over the sites of 7 probes (1 good,
+        // 11 junk by hand-labelling, corrected for whole-query forms):
+        //     len >= W        rejects "hi"(2) "of"(2) "is"(2) "di"(2) "the"(3),
+        //                     admits  "Eiffel Tower"(12) and both whole-query forms
+        //     len >= W-1      admits "the" — W-1 is the write side's straddle
+        //                     neighbour for RETRIEVAL, never a claim about units
+        //     §2.7 saturation admits 11/11 junk: edgeAncestors on a site node
+        //                     reaches 1..48 contexts, so dominates(ctx, N) needs
+        //                     ctx > 162805 and never fires; every site reads DISC
+        //     rarity          does not separate: "hi" has 1 container, "the" 572
+        //
+        // A span covering the WHOLE query is exempt: then it is not a fragment of
+        // something longer, it is the question ("hi" asked on its own).
+        if (atomsAreHubs && end - start < ctx.space.maxGroup &&
+            !(start === 0 && end === bytes.length))
+            return;
         const key = start + "," + end + "," + id;
         if (seen.has(key))
             return;
@@ -115,6 +153,7 @@ function recogniseImpl(ctx, bytes) {
     };
     // ── structural: the query's own perceived tree ──────────────────────
     starts.add(0);
+    startList.push(0);
     foldTree(ctx, perceive(ctx, bytes), 0, (n, start, end, node) => {
         if (n.kids === null) {
             leaves.push({ start, end, bytes: n.leaf ?? new Uint8Array(0), node });
@@ -190,26 +229,50 @@ function recogniseImpl(ctx, bytes) {
                 // "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;
+                // turn is its OWN segment, 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 does not, because every candidate is a cut the query's
+                // OWN fold drew (`starts`, the same set the canonical pass privileges
+                // with full chain reach) — fold EVIDENCE, never a blind guess.
+                //
+                // The candidates are the fold's own segment starts inside this span, in
+                // order.  They used to be probed at `start + k*W`, which assumed cuts
+                // land on multiples of W; content-defined cuts do not, so that stride
+                // tested offsets no segment ever began at and this search silently
+                // never fired (test/44 pins it).  Still bounded to W candidates, each
+                // one O(1) from the sorted cut list before paying for a 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 an exact-content coincidence.
+                // A deposit's ROOT is a whole-stream node, and a stream's ends are not
+                // content cuts — so an embedded occurrence of a trained form reproduces
+                // its SEGMENTS (which are offset-free) but never its root.  What is
+                // being looked for is therefore a suffix of this span that happens to be
+                // a whole trained form, and its left edge can only be a cut the fold
+                // itself drew.  Candidates are taken from the RIGHT, nearest the end
+                // first: the form ends where this node ends, so its start is near it.
+                // Left-to-right was wrong — in test/44 the target's start is the 6th cut
+                // from the end but the 12th from the beginning.
+                //
+                // `starts` is still filling (this runs inside the post-order walk), but
+                // post-order guarantees every chunk BELOW this span is already in it —
+                // exactly the set wanted.  Bounded to chainReach(W) candidates, the same
+                // reach the canonical pass trusts, so cost stays O(reach · span).
+                let hi = startList.length; // first index past the last usable cut
+                let lo = 0;
+                while (lo < hi) {
+                    const mid = (lo + hi) >> 1;
+                    if (startList[mid] < end - 1)
+                        lo = mid + 1;
+                    else
+                        hi = mid;
+                }
+                const reach = chainReach(W);
+                for (let k = 0; k < reach; k++) {
+                    const p = startList[lo - 1 - k];
+                    if (p === undefined || p <= start)
+                        break;
                     const cid = canonResolve(ctx, bytes.subarray(p, end));
                     if (cid !== null)
                         emit(p, end, cid);
@@ -218,6 +281,8 @@ function recogniseImpl(ctx, bytes) {
         }
         if (isChunk(n)) {
             starts.add(start);
+            if (startList[startList.length - 1] !== start)
+                startList.push(start);
             // Try every sub-span within this leaf-parent.
             const leafOffsets = [];
             let off = start;
@@ -290,6 +355,14 @@ function recogniseImpl(ctx, bytes) {
     // hub-scale atoms, chained at an offset nothing in the query's own fold
     // selected).  Chains that start ON a boundary carry the fold's own
     // evidence instead and are exempt.
+    //
+    // NOTE (2026-07-24): that last sentence is FALSE — `starts` is exactly
+    // {0, W, 2W, …} (riverFold groups fixed-arity), so the exemption is
+    // arithmetic, not evidence.  Removing it wholesale was measured and
+    // REVERTED: it also drops legitimate multi-byte chains (the 12-byte
+    // "Eiffel Tower" site vanished with it).  The premise is wrong but the
+    // trust it stood in for is real; a replacement signal is still open work.
+    // See bench/README.md.
     const tryChain = (p, maxIds, boundary) => {
         const first = leafFrom(p);
         if (!first)

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

@@ -1,5 +1,16 @@
 import { Vec } from "../vec.js";
 import type { AncestorReach, MindContext } from "./types.js";
+/** 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 declare function sharedReachMemo(ctx: MindContext): Map<number, AncestorReach>;
 /** Climb the structural DAG from a node to its edge-bearing ancestor contexts.
  *  Ascent stops at hub nodes (parents > √N) — their reach is non-discriminative.
  *  When the start node has no structural parents, climbs from containment parents

package/dist/src/mind/traverse.js

@@ -8,6 +8,49 @@
 import { cosine } from "../vec.js";
 import { gistOf, read } from "./primitives.js";
 const structCaches = new WeakMap();
+// ── 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();
+/** 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) {
+    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) {
     if (ctx.climbMemo === null)
         return null;
@@ -89,7 +132,7 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
     // 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 = {
             roots: [],
             contextsReached: 0,
@@ -102,13 +145,15 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
                         observed: atomReach(ctx, contextCount),
                         limit: bound0,
                     },
+                    visited: 0,
+                    maxDepth: 0,
                 }
                 : {}),
         };
         memo?.set(id, reach);
         return reach;
     }
-    const bound = Math.ceil(Math.sqrt(contextCount));
+    const bound = boundFor(contextCount);
     const roots = [];
     const seen = new Set([id]);
     const ctxSeen = new Set();
@@ -151,7 +196,22 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
     // ~20K distinct nodes per climb family, >95% unique — not memoisable)
     // 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 = ctx.trace ? [] : null;
+    let curDepth = 0;
+    let visitedCount = 0;
+    let maxDepth = 0;
     const visit = (x) => {
+        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) {
@@ -203,6 +263,7 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
             if (!seen.has(p)) {
                 seen.add(p);
                 stack.push(p);
+                depths?.push(curDepth + 1);
                 fresh++;
             }
         }
@@ -225,8 +286,10 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
     };
     const stack = [];
     const containment = !cachedHasParents(ctx, id, structCache);
-    if (!containment)
+    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
     // of one deposit repeat it) are walked IN FULL — exact — while a common
@@ -247,17 +310,22 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
                 if (!seen.has(c)) {
                     seen.add(c);
                     stack.push(c);
+                    depths?.push(1);
                 }
             }
             if (stack.length === 0) {
-                if (containerOff === 0)
+                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
@@ -277,6 +345,10 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
                 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;
@@ -289,6 +361,7 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
         contextsReached: ctxSeen.size,
         saturated,
         ...(saturated && satStop ? { saturation: satStop } : {}),
+        ...(depths ? { visited: visitedCount, maxDepth } : {}),
     };
     memo?.set(id, reach);
     return reach;
@@ -316,8 +389,7 @@ export function atomReach(ctx, contextCount) {
  *  atom votes and is recognised exactly as any stored form; above it the
  *  alphabet is scaffolding everywhere and abstains. */
 export function atomIsHub(ctx, contextCount) {
-    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.
  *  The admission predicate recognition filters sites with (HOW_IT_WORKS
@@ -358,7 +430,16 @@ export function corpusN(ctx) {
  *  materialised list.  {@link hubCap} is the list-side reading of the same
  *  convention. */
 export function hubBound(ctx) {
-    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) {
+    return Math.ceil(Math.sqrt(Math.max(2, contextCount)));
 }
 /** Cap a candidate list at the hub bound √N (insertion order) — the ONE
  *  fan-out convention every walk and disambiguation uses (see HOW_IT_WORKS

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

@@ -4,17 +4,16 @@ 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 { GraphSearch, Leaf, Seg, 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 {
     /** Turn boundaries accumulated over this content's deposit chain —
      *  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
@@ -29,6 +28,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>;
@@ -132,6 +135,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
  *  saturated (an abstention, not a discriminative conclusion) — pure
@@ -156,6 +172,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. */
 export interface SaturationInfo {
@@ -179,6 +206,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;
@@ -239,8 +272,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/dist/src/store.d.ts

@@ -1,5 +1,6 @@
 import { Vec } from "./vec.js";
 import { type StoreConfig } from "./config.js";
+import type { Meter } from "./meter.js";
 /** A node id: a dense, non-negative integer assigned in creation order. */
 export type NodeId = number;
 /** A node in the graph. Exactly one of `leaf` / `kids` is set. */
@@ -62,6 +63,13 @@ export declare 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;
     /** Insert a leaf, returning its content id. Idempotent. */
     putLeaf(bytes: Uint8Array, gist: Vec): Promise<NodeId>;
     /** Insert a branch over child ids, returning its content id. Idempotent. */
@@ -508,6 +516,10 @@ export declare abstract class AbstractStore implements Store {
      *  outlive their records — the read degrades safely to empty bytes, this
      *  counter is what keeps that degradation observable. */
     danglingReads: number;
+    /** {@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;
     bytes(id: NodeId): Uint8Array;
     /** First `maxLen` bytes of a node.  Walks only the leftmost branch,
      *  stopping at `maxLen` — so a 1 MB document root costs the same as a
@@ -517,6 +529,9 @@ export declare 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;
+    /** {@link bytesPrefix}'s recursive body — uncharged; see the metering
+     *  boundary note there. */
+    private _prefix;
     contentLen(id: NodeId, cap?: number): number;
     findLeaf(bytes: Uint8Array): NodeId | null;
     findBranch(kids: NodeId[]): NodeId | null;