@hviana/sema 0.8.0 → 0.8.2

package/dist/src/mind/pipeline.js

@@ -93,13 +93,13 @@ export async function think(ctx, query, mechs) {
     // ── Pre-computation ──────────────────────────────────────────────────
     const mechanisms = mechs ?? defaultMechanisms;
     const meter = ctx.meter;
-    // recognition is a shared analysis (§2.14 contract 5): it does the query's
+    // recognition is a shared analysis (meter.md contract 5): it does the query's
     // own store work (perceive → foldTree → resolve), which used to land in
     // `think` and in nothing narrower — the meter's one accounting surface must
     // charge it to itself, exactly as attention/weave/resonance are charged.
-    // SYNCHRONOUS phase: recognition is on the sync side of §2.10's seam, so it
-    // is timed with `timeSync` — wrapping it in a promise would make a profiled
-    // response await where an unprofiled one does not.
+    // SYNCHRONOUS phase: recognition is on the sync side of meter.md's seam, so
+    // it is timed with `timeSync` — wrapping it in a promise would make a
+    // profiled response await where an unprofiled one does not.
     const rec = meter
         ? meter.timeSync("recognise", () => recognise(ctx, query))
         : recognise(ctx, query);
@@ -113,15 +113,15 @@ export async function think(ctx, query, mechs) {
             ctx.trace?.step("evalComputation", [rItem(query.subarray(u.i, u.j), "expression", undefined, [u.i, u.j])], [rItem(u.bytes, "result", resolve(ctx, u.bytes) ?? undefined)], "evaluate the recognised operation to its authoritative result");
         }
     }
-    // Phase 2: the shared pre-computation container.  Eager fields only
-    // (recognition, computed spans, guide) — every expensive analysis
-    // (consensus climb, weave, span-shape classification) is a lazily-cached
-    // method on Precomputed, first-touched by whichever mechanism's floor
-    // survives its cheap gates and the worthRunning check.  A query no
-    // mechanism climbs for (e.g. one an extension decided) never climbs.
-    // NOT phased: the constructor itself is trivial (it only derives `k`), so a
-    // phase here would add a zero-work entry to every profiled report — the meter
-    // attributes WORK (§2.14); the trace already represents structure.
+    // Phase 2: the shared pre-computation container. Eager fields only
+    // (recognition, computed spans, guide) — every expensive analysis (consensus
+    // climb, weave, span-shape classification) is a lazily-cached method on
+    // Precomputed, first-touched by whichever mechanism's floor survives its
+    // cheap gates and the worthRunning check. A query no mechanism climbs for
+    // (e.g. one an extension decided) never climbs. NOT phased: the constructor
+    // itself is trivial (it only derives `k`), so a phase here would add a
+    // zero-work entry to every profiled report — the meter attributes WORK
+    // (meter.md); the trace already represents structure.
     const pre = new Precomputed(ctx, query, rec, computed, ctx._edgeGuide);
     const grade = (w) => Math.floor(w / STEP);
     const unaccounted = (spans) => unexplainedSpans(query.length, spans)
@@ -166,16 +166,17 @@ export async function think(ctx, query, mechs) {
             best = c;
     };
     const worthRunning = (floor) => best === null || grade(floor) < grade(best.weight);
-    // REGIME PREDICTION (R8) — observational only.  Once the FIRST mechanism has
-    // had its turn (cover, which §2.6 places first and floors at 0), the market's
-    // outcome is already determined by the one cost ladder: the consensus climb
-    // runs exactly when `worthRunning(2 * STEP)` is true — CAST (floor 2·STEP) is
-    // the cheapest mechanism that first-touches it, so an incumbent at or below
-    // grade 2 prunes CAST and, with it, confluence (3·STEP) and extraction
-    // (CONCEPT+STEP) (retrieval); anything above — or no incumbent — runs the
-    // full market and the climb (composition).  The predicate is `worthRunning`,
-    // the same function the loop itself uses — nothing is computed here that the
-    // engine had not already computed, and nothing is read back by inference.
+    // REGIME PREDICTION (R8) — observational only. Once the FIRST mechanism has
+    // had its turn (cover, which mechanism-market.md places first and floors at
+    // 0), the market's outcome is already determined by the one cost ladder: the
+    // consensus climb runs exactly when `worthRunning(2 * STEP)` is true — CAST
+    // (floor 2·STEP) is the cheapest mechanism that first-touches it, so an
+    // incumbent at or below grade 2 prunes CAST and, with it, confluence (3·STEP)
+    // and extraction (CONCEPT+STEP) (retrieval); anything above — or no incumbent
+    // — runs the full market and the climb (composition). The predicate is
+    // `worthRunning`, the same function the loop itself uses — nothing is
+    // computed here that the engine had not already computed, and nothing is read
+    // back by inference.
     //
     // EMITTED BEFORE THE SECOND MECHANISM'S FLOOR, never after some mechanism's
     // run: a "prediction" published after the fact could assert "the climb will
@@ -354,9 +355,32 @@ export async function think(ctx, query, mechs) {
     const voiced = (provenance === "cast" || provenance === "join")
         ? [...castUsed].flatMap((id) => ctx.store.nextFirst(id, hubBound(ctx)).map((n) => read(ctx, n)))
         : [];
+    // REPORTABLE, NOT SILENT.  A declared-complete grounding ends the derivation
+    // here, and that decision is part of the derivation's shape: the reader of a
+    // rationale must be able to see that the chain stopped because the mechanism
+    // claimed the query WAS the context, not because nothing followed.  The step
+    // carries the claim, not a re-description of the answer — the extension is
+    // skipped, so there is no output item to show.
+    if (decided.complete) {
+        ctx.trace?.step("completeGrounding", [rItem(answer, provenance)], [], "grounding declared complete — the query IS the context, so " +
+            "post-grounding extension is skipped");
+    }
+    // THE REASONER JUDGES ITS OWN EXTENSIONS BY THE PIPELINE'S REMAINDER, not by
+    // the ladder's `accounted` — and by the SAME reading the fuse gate below uses,
+    // with the same W floor.  `accounted` is a COST quantity (measured: a query
+    // fully explained by one computed span plus bridged connectors reports
+    // `accounted: []` while nothing is unexplained), and a remainder under one
+    // river-fold quantum is bridging punctuation, never a second topic — so it
+    // licenses no extension and blocks none.
+    const explained = [
+        ...decided.accounted,
+        ...pre.computed.map((u) => [u.i, u.j]),
+    ];
+    const uncovered = unexplainedSpans(query.length, explained)
+        .filter(([a, b]) => b - a >= ctx.space.maxGroup);
     const reasoned = decided.complete ? answer : meter
-        ? await meter.time("reason", () => reason(ctx, query, answer, preConsumed, pre, voiced))
-        : await reason(ctx, query, answer, preConsumed, pre, voiced);
+        ? await meter.time("reason", () => reason(ctx, query, answer, preConsumed, pre, voiced, uncovered))
+        : await reason(ctx, query, answer, preConsumed, pre, voiced, uncovered);
     // Fuse only when the query has a genuine REMAINDER no mechanism's
     // structural evidence touched at all.  `decided.accounted` alone
     // undercounts this: it is a COST-LADDER quantity (cover.ts prices its
@@ -373,10 +397,6 @@ export async function think(ctx, query, mechs) {
     // observed: a single space between two fully-computed arithmetic spans
     // ("2+2 3+3") registered as "unaccounted" and pulled in an unrelated
     // corpus fact, corrupting "4 6" into "4 63".
-    const explained = [
-        ...decided.accounted,
-        ...pre.computed.map((u) => [u.i, u.j]),
-    ];
     const remainder = unaccounted(explained);
     // Whether the winning candidate's entire recognised substance is
     // COMPUTED — every accounted span exactly a pre.computed span, nothing

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

@@ -20,11 +20,11 @@ export declare function perceiveKey(bytes: Uint8Array, boundaries?: readonly num
 /** Perceive input into a content-defined tree (the river fold).
  *  Deterministic — identical bytes always produce an identical tree.
  *
- *  `boundaries` is an optional sorted list of proper byte offsets where the
- *  fold must split so that each prefix segment folds identically to how it
- *  folded when it was learned (§10.3 stable-prefix contract).  Only the
- *  CALLER — who assembled the multi-turn context — knows where those
- *  boundaries are; the geometry never guesses them from the bytes. */
+ * `boundaries` is an optional sorted list of proper byte offsets where the fold
+ * must split so that each prefix segment folds identically to how it folded
+ * when it was learned (fold-contract.md stable-prefix contract). Only the
+ * CALLER — who assembled the multi-turn context — knows where those boundaries
+ * are; the geometry never guesses them from the bytes. */
 export declare function perceive(ctx: MindContext, input: Input, leafAt?: (i: number) => number | null, lookup?: (ids: number[]) => number | null, boundaries?: readonly number[]): Sema;
 /** The DEPOSIT-shaped perceive.  Folds over the stream's own content cuts —
  *  bit-identical to what inference computes for the same bytes.  That

package/dist/src/mind/primitives.js

@@ -40,11 +40,11 @@ export function perceiveKey(bytes, boundaries) {
 /** Perceive input into a content-defined tree (the river fold).
  *  Deterministic — identical bytes always produce an identical tree.
  *
- *  `boundaries` is an optional sorted list of proper byte offsets where the
- *  fold must split so that each prefix segment folds identically to how it
- *  folded when it was learned (§10.3 stable-prefix contract).  Only the
- *  CALLER — who assembled the multi-turn context — knows where those
- *  boundaries are; the geometry never guesses them from the bytes. */
+ * `boundaries` is an optional sorted list of proper byte offsets where the fold
+ * must split so that each prefix segment folds identically to how it folded
+ * when it was learned (fold-contract.md stable-prefix contract). Only the
+ * CALLER — who assembled the multi-turn context — knows where those boundaries
+ * are; the geometry never guesses them from the bytes. */
 export function perceive(ctx, input, leafAt, lookup, boundaries) {
     if (typeof input === "string" || input instanceof Uint8Array) {
         const bytes = typeof input === "string"

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

@@ -20,7 +20,11 @@ export declare function restatesQuery(query: Uint8Array, bytes: Uint8Array): boo
  *  when it declared one — see the pivot's own containment rule.  `pre` is the
  *  response's shared pre-computation — the post-grounding stages read the
  *  same container the mechanisms did. */
-export declare function reason(ctx: MindContext, query: Uint8Array, answer: Uint8Array, preConsumed: ReadonlySet<number>, pre: Precomputed, voiced?: readonly Uint8Array[]): Promise<Uint8Array>;
+export declare function reason(ctx: MindContext, query: Uint8Array, answer: Uint8Array, preConsumed: ReadonlySet<number>, pre: Precomputed, voiced?: readonly Uint8Array[], 
+/** The query material the GROUNDING left uncovered — the cost ladder's own
+ *  `unaccounted` spans.  Only the reasoner's OWN extensions are judged
+ *  against it; a mechanism carrying its own `used` set owns its shape. */
+uncovered?: readonly (readonly [number, number])[]): Promise<Uint8Array>;
 /** Fuse independent points of attention into one answer (multi-topic).
  *  When the consensus climb finds more than one dominant point, each
  *  independent point grounds its own answer; they are bridged together

package/dist/src/mind/reasoning.js

@@ -30,7 +30,11 @@ export function restatesQuery(query, bytes) {
  *  when it declared one — see the pivot's own containment rule.  `pre` is the
  *  response's shared pre-computation — the post-grounding stages read the
  *  same container the mechanisms did. */
-export async function reason(ctx, query, answer, preConsumed, pre, voiced = []) {
+export async function reason(ctx, query, answer, preConsumed, pre, voiced = [], 
+/** The query material the GROUNDING left uncovered — the cost ladder's own
+ *  `unaccounted` spans.  Only the reasoner's OWN extensions are judged
+ *  against it; a mechanism carrying its own `used` set owns its shape. */
+uncovered = []) {
     // Echo guard: a query that is ITSELF a learnt continuation (some context's
     // answer) is being asked back at the system — hopping forward from it would
     // chain through the very fact that produced it and echo the conversation
@@ -178,6 +182,55 @@ export async function reason(ctx, query, answer, preConsumed, pre, voiced = [])
         consumeAll(pivot);
         if (fc === null || bytesEqual(fc, cur) || restatesQuery(query, fc))
             break;
+        // WHOSE EXTENSION IS THIS?
+        //
+        // `voiced` is what the mechanism WITHHELD (the pipeline sends the used
+        // anchors' CONTINUATIONS, not their bytes — see pipeline's own note), so a
+        // non-empty `voiced` means exactly what that note says: the grounding came
+        // from a mechanism that carries its own short `used` set (cast/join) and
+        // therefore owns the shape of its answer.  The further terms inside such a
+        // seat are legitimately followable — test/29 C3's `Mona Lisa` lives inside
+        // the voiced seat and leads on to a fact about neither analog.
+        //
+        // Every other grounding is ordinary, and an extension of it is the
+        // reasoner's own inference: it is taken only while question material the
+        // grounding left uncovered remains AND the step carries some of it, judged
+        // by the mind's own line between chance and evidence — one W-byte window,
+        // no word notion, no character class, no threshold.  Measured: the drift's
+        // second step (`the Eiffel Tower is in Paris` after `Paris is famous for
+        // the Eiffel Tower`) carries no window of `" famous for"` and is refused,
+        // while the first carries it.  Terminates by a real argument: the uncovered
+        // material is finite and each taken extension must carry some of it.
+        const producerOwnsShape = voiced.length > 0;
+        if (!producerOwnsShape && uncovered.length > 0) {
+            const W = ctx.space.maxGroup;
+            let progress = false;
+            for (const [a, b] of uncovered) {
+                for (let i = a; i + W <= b && !progress; i++) {
+                    if (indexOf(fc, query.subarray(i, i + W), 0) >= 0)
+                        progress = true;
+                }
+                if (progress)
+                    break;
+            }
+            if (!progress) {
+                // THE BRAKE, MADE VISIBLE.  The reasoner declines a step that carries
+                // none of the material the grounding left uncovered — the drift the
+                // extension tests pin.  A refusal that leaves no trace is the kind of
+                // silent cut AGENTS §6 forbids: the rationale is where a reader learns
+                // that an extension was declined for want of question material, and
+                // where the next person sees why the chain stopped here.  Measured with
+                // the check disabled, test/110 and test/116 fail — so this brake is the
+                // only thing keeping the extension honest until the pivot reports its
+                // own accounted spans and the ladder can judge it instead.
+                const left = uncovered.reduce((n, [a, b]) => n + (b - a), 0);
+                ctx.trace?.step("pivotRefused", [rItem(cur, "answer"), rItem(query, "query")], uncovered.map(([a, b]) => rItem(query.subarray(a, b), "uncovered")), `the step carries none of the question material the grounding left ` +
+                    `uncovered (${left} byte(s) in ${uncovered.length} span(s)) — refused`);
+                break;
+            }
+        }
+        if (ctx.meter)
+            ctx.meter.pivotSteps++;
         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");
         cur = fc;

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

@@ -12,19 +12,20 @@ import type { MindContext, Recognition, Segment } from "./types.js";
  *
  *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus.
  *
- *  ONE READING PER BYTE STREAM, deliberately: there is no "cheap mode" that
- *  skips the edge-trim fallbacks.  A `trimmed` variant was tried and REFUTED
- *  twice over.  Its premise — "the trims only recover misaligned FRAGMENTS, so
- *  a consumer whose gate rejects fragments loses nothing" — is false: the
- *  left/right trim loops below exist precisely to find WHOLE trained forms
- *  embedded at an offset the query's own fold did not cut, and such a form has
- *  no structural parents or containers, so it passes the pivot's fragment gate
- *  and is exactly the candidate a multi-hop chain steps through.  Skipping them
- *  narrows the pivot's evidence silently.  And a per-caller variant has to key
- *  the memo by the variant, which breaks the "computed at most once" property
- *  (§2.11): the pipeline recognises a grounded answer untrimmed for
- *  `preConsumed`, and the pivot then recognises the same bytes again — the
- *  saving inverts into a doubling on the path it was measured for. */
+ * ONE READING PER BYTE STREAM, deliberately: there is no "cheap mode" that
+ * skips
+ * the edge-trim fallbacks. A `trimmed` variant was tried and REFUTED twice
+ * over. Its premise — "the trims only recover misaligned FRAGMENTS, so a
+ * consumer whose gate rejects fragments loses nothing" — is false: the
+ * left/right trim loops below exist precisely to find WHOLE trained forms
+ * embedded at an offset the query's own fold did not cut, and such a form has
+ * no structural parents or containers, so it passes the pivot's fragment gate
+ * and is exactly the candidate a multi-hop chain steps through. Skipping them
+ * narrows the pivot's evidence silently. And a per-caller variant has to key
+ * the memo by the variant, which breaks the "computed at most once" property
+ * (memoization.md): the pipeline recognises a grounded answer untrimmed for
+ * `preConsumed`, and the pivot then recognises the same bytes again — the
+ * saving inverts into a doubling on the path it was measured for. */
 export declare function recognise(ctx: MindContext, bytes: Uint8Array): Recognition;
 /** Segment bytes using the geometry's own groupings — leaf-parent
  *  nodes from the perceived tree, with consecutive bare leaves merged

package/dist/src/mind/recognition.js

@@ -23,19 +23,20 @@ import { isChunk } from "../sema.js";
  *
  *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus.
  *
- *  ONE READING PER BYTE STREAM, deliberately: there is no "cheap mode" that
- *  skips the edge-trim fallbacks.  A `trimmed` variant was tried and REFUTED
- *  twice over.  Its premise — "the trims only recover misaligned FRAGMENTS, so
- *  a consumer whose gate rejects fragments loses nothing" — is false: the
- *  left/right trim loops below exist precisely to find WHOLE trained forms
- *  embedded at an offset the query's own fold did not cut, and such a form has
- *  no structural parents or containers, so it passes the pivot's fragment gate
- *  and is exactly the candidate a multi-hop chain steps through.  Skipping them
- *  narrows the pivot's evidence silently.  And a per-caller variant has to key
- *  the memo by the variant, which breaks the "computed at most once" property
- *  (§2.11): the pipeline recognises a grounded answer untrimmed for
- *  `preConsumed`, and the pivot then recognises the same bytes again — the
- *  saving inverts into a doubling on the path it was measured for. */
+ * ONE READING PER BYTE STREAM, deliberately: there is no "cheap mode" that
+ * skips
+ * the edge-trim fallbacks. A `trimmed` variant was tried and REFUTED twice
+ * over. Its premise — "the trims only recover misaligned FRAGMENTS, so a
+ * consumer whose gate rejects fragments loses nothing" — is false: the
+ * left/right trim loops below exist precisely to find WHOLE trained forms
+ * embedded at an offset the query's own fold did not cut, and such a form has
+ * no structural parents or containers, so it passes the pivot's fragment gate
+ * and is exactly the candidate a multi-hop chain steps through. Skipping them
+ * narrows the pivot's evidence silently. And a per-caller variant has to key
+ * the memo by the variant, which breaks the "computed at most once" property
+ * (memoization.md): the pipeline recognises a grounded answer untrimmed for
+ * `preConsumed`, and the pivot then recognises the same bytes again — the
+ * saving inverts into a doubling on the path it was measured for. */
 export function recognise(ctx, bytes) {
     // Content-keyed memo — works for both single-turn respond() and multi-turn
     // respondTurn() (where the map persists across calls).  ALWAYS consulted,
@@ -159,16 +160,15 @@ function recogniseImpl(ctx, bytes) {
         // 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
+        // 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 commonality.md 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).

package/dist/src/mind/resonance.js

@@ -303,15 +303,15 @@ export async function pivotInto(ctx, answer, consumed, voiced = []) {
     // Byte containment, longest wins — the answer literally contains the
     // pivot's bytes, and the biggest well-evidenced span is the real pivot.
     //
-    // REAL SATURATION, not a hard cap: the score IS the candidate's byte
-    // length, so the scan is DECIDED the moment the first candidate that passes
-    // every filter is found in DESCENDING length order — a shorter candidate can
-    // never outscore it.  `contentLen` (the prefix-capped length read, §2.8) is
-    // the cheap ordering key, and the first-inserted tie-break is made explicit
-    // (`a.index - b.index`) so equal lengths keep `scored`'s insertion order —
-    // exactly the tie argmaxBy(strict) used to keep.  The bytes of at most ONE
-    // winning candidate are read; every shorter candidate the probes proposed is
-    // skipped without reconstruction, where the old argmax read them all.
+    // REAL SATURATION, not a hard cap: the score IS the candidate's byte length,
+    // so the scan is DECIDED the moment the first candidate that passes every
+    // filter is found in DESCENDING length order — a shorter candidate can never
+    // outscore it. `contentLen` (the prefix-capped length read, bounded-reads.md)
+    // is the cheap ordering key, and the first-inserted tie-break is made
+    // explicit (`a.index - b.index`) so equal lengths keep `scored`'s insertion
+    // order — exactly the tie argmaxBy(strict) used to keep. The bytes of at most
+    // ONE winning candidate are read; every shorter candidate the probes proposed
+    // is skipped without reconstruction, where the old argmax read them all.
     const ranked = [...scored.keys()]
         .map((id, index) => ({
         id,
@@ -322,11 +322,11 @@ export async function pivotInto(ctx, answer, consumed, voiced = []) {
     let pivotId = null;
     for (const c of ranked) {
         const id = c.id;
-        // A ZERO-LENGTH candidate is not a pivot.  `argmaxBy(…, 0, strict)` used to
+        // A ZERO-LENGTH candidate is not a pivot. `argmaxBy(…, 0, strict)` used to
         // carry this floor in its threshold argument, and dropping it here would
         // admit an empty node: `indexOf(answer, <empty>)` returns 0, so every
-        // filter below passes and the chain would hop through nothing (§2.13 —
-        // empty bytes are truthy).
+        // filter below passes and the chain would hop through nothing
+        // (INVARIANTS.md — empty bytes are truthy).
         if (c.len === 0)
             continue;
         // A PIVOT MUST BE A THING THE CORPUS DEPOSITED, NOT A PIECE OF ONE.
@@ -364,15 +364,15 @@ export async function pivotInto(ctx, answer, consumed, voiced = []) {
         // No constant enters — it is a structural predicate, not a threshold.
         if (ctx.store.hasParents(id) || ctx.store.hasContainers(id))
             continue;
-        // A candidate whose bytes are LONGER than the answer cannot be a
-        // substring of it — `indexOf` would return −1 regardless.  Prune by
-        // length BEFORE reconstructing the bytes: `read` is an UNCAPPED read
-        // (AGENTS §2.8), and a resonated context far longer than the answer is
-        // exactly the candidate that makes it cost a whole deposit's worth of
-        // reconstruction for a containment test that must fail.  `contentLen`
-        // with the `answer.length + 1` cap is the prefix-capped length read the
-        // same contract prescribes; the prune is byte-identical to the old
-        // `indexOf` miss (it returns −1 for a needle longer than the haystack).
+        // A candidate whose bytes are LONGER than the answer cannot be a substring
+        // of it — `indexOf` would return −1 regardless. Prune by length BEFORE
+        // reconstructing the bytes: `read` is an UNCAPPED read (bounded-reads.md),
+        // and a resonated context far longer than the answer is exactly the
+        // candidate that makes it cost a whole deposit's worth of reconstruction
+        // for a containment test that must fail. `contentLen` with the
+        // `answer.length + 1` cap is the prefix-capped length read the same
+        // contract prescribes; the prune is byte-identical to the old `indexOf`
+        // miss (it returns −1 for a needle longer than the haystack).
         if (c.len > answer.length)
             continue;
         const bytes = read(ctx, id);

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

@@ -2,14 +2,14 @@ import { Vec } from "../vec.js";
 import type { AncestorReach, MindContext } from "./types.js";
 /** The reach memo this ask 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. */
+ *  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
+ * memoization.md: a traced response is a different machine — never benchmark
+ * with a trace attached. */
 export declare function sharedReachMemo(ctx: MindContext): Map<number, AncestorReach>;
 /** Invalidate every session-lifetime structural read after a write. */
 export declare function invalidateStructuralCaches(ctx: MindContext): void;
@@ -59,13 +59,14 @@ export declare function atomIsHub(ctx: MindContext, contextCount: number): boole
  *  predicate, and never as a replacement for it. */
 export declare function bearsEdge(ctx: MindContext, id: number): boolean;
 /** Whether a node LEADS SOMEWHERE — it bears a continuation edge or a halo.
- *  The admission predicate recognition filters sites with (HOW_IT_WORKS
- *  §15.3): a form that leads nowhere contributes nothing to any derivation.
- *  Runs once per candidate span on the recognition hot path — `hasNext` is
- *  cached per response (the same flat-branch ids are probed across prefix
- *  variants by canonicalChunkId).  `hasHalo` is not cached: it's a single
- *  indexed point probe per candidate, and the candidates that reach this
- *  check have already been filtered by hasNext above in edgeAncestors. */
+ * The admission predicate recognition filters sites with (cover.md): a form
+ * that
+ * leads nowhere contributes nothing to any derivation. Runs once per candidate
+ * span on the recognition hot path — `hasNext` is cached per response (the same
+ * flat-branch ids are probed across prefix variants by canonicalChunkId).
+ * `hasHalo` is not cached: it's a single indexed point probe per candidate, and
+ * the candidates that reach this check have already been filtered by hasNext
+ * above in edgeAncestors. */
 export declare function leadsSomewhere(ctx: MindContext, id: number): boolean;
 /** The structural IDF read of ONE node: how many distinct learnt contexts
  *  its containment/edge climb reaches, or Infinity when it reaches none or
@@ -86,10 +87,10 @@ export declare function corpusN(ctx: MindContext): number;
  *  convention. */
 export declare function hubBound(ctx: MindContext): number;
 /** 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
- *  §8.6).  A node connected to more than √N others is a hub whose individual
- *  connections carry ~no discriminative information; materialising or scoring
- *  them all would make single decisions scale with the corpus. */
+ * fan-out convention every walk and disambiguation uses (see bounded-reads.md).
+ * A node connected to more than √N others is a hub whose individual connections
+ * carry ~no discriminative information; materialising or scoring them all would
+ * make single decisions scale with the corpus. */
 export declare function hubCap<T>(ctx: MindContext, ids: readonly T[]): readonly T[];
 /** Whether `descendant` lies within `ancestor`'s subtree — a structural DAG
  *  relation read off the hash-consed `kids` lists, by a bounded explicit-stack
@@ -100,16 +101,16 @@ export declare function contains(ctx: MindContext, ancestor: number, descendant:
  *  the EXACT half's veto on calling them synonyms.
  *
  *  Halos measure company, and the strongest company any two forms can keep is
- *  standing next to each other: a question and its answer co-occur in every
- *  episode that taught the pair, so their halos SHOULD be similar, and on a
- *  conversational store they are (measured on the CONV fixture: consecutive
- *  turns at 0.809 against a 0.516 concept threshold).  A gate reading halo
- *  cosine alone therefore reads adjacency as synonymy and revoices an answer
- *  in the words of the question it answers — "it hangs in madrid" spliced back
- *  into "where is it kept now".  The distributional layer cannot tell the two
- *  relations apart, because to it they are the same observation; the exact
- *  half can, for free, because it stored the edge.  §4.1's division of labour
- *  exactly: approximate proposes, exact decides.
+ * standing next to each other: a question and its answer co-occur in every
+ * episode that taught the pair, so their halos SHOULD be similar, and on a
+ * conversational store they are (measured on the CONV fixture: consecutive
+ * turns at 0.809 against a 0.516 concept threshold). A gate reading halo cosine
+ * alone therefore reads adjacency as synonymy and revoices an answer in the
+ * words of the question it answers — "it hangs in madrid" spliced back into
+ * "where is it kept now". The distributional layer cannot tell the two
+ * relations apart, because to it they are the same observation; the exact half
+ * can, for free, because it stored the edge. halo-sketch.md's division of
+ * labour exactly: approximate proposes, exact decides.
  *
  *  Read LIMITed in both directions at the hub bound — a common continuation's
  *  fan-in is corpus-sized, and no single decision may scale with it. */
@@ -162,12 +163,13 @@ export declare function chooseAmong(ctx: MindContext, candidates: readonly numbe
  *  W-window it spells is contained by more places than the hub bound allows,
  *  i.e. the whole query is corpus-global scaffolding.
  *
- *  WHAT IT IS FOR.  Several mechanisms ground a query through the literal
- *  spans it did NOT explain, and those spans are the whole of their evidence.
- *  When every one of them is a hub, the query says nothing the corpus can be
- *  held to, and grounding it means picking one of thousands of continuations
- *  it gives no evidence for — a fabrication whatever the answer happens to be.
- *  Answering with silence there is the honest degradation contract (§2.13).
+ * WHAT IT IS FOR. Several mechanisms ground a query through the literal spans
+ * it
+ * did NOT explain, and those spans are the whole of their evidence. When every
+ * one of them is a hub, the query says nothing the corpus can be held to, and
+ * grounding it means picking one of thousands of continuations it gives no
+ * evidence for — a fabrication whatever the answer happens to be. Answering
+ * with silence there is the honest degradation contract (INVARIANTS.md).
  *
  *  MEASURED SEPARATION (trained store, hubBound 571) — this is categorical,
  *  not marginal, and it is why the predicate lives here rather than being
@@ -184,11 +186,11 @@ export declare function chooseAmong(ctx: MindContext, candidates: readonly numbe
  *  evidence and sit on the SAME side as the correct ones, so this predicate
  *  is not what makes them silent and cannot be credited for them.
  *
- *  NO NEW THRESHOLD (§2.2): `hubBound` is the √N reading of "hub" used
- *  everywhere, and the containment read is clamped to it exactly as every
- *  other fan-out read is (§2.8).  A query with no stored window at all is NOT
- *  scaffolding-only — it has no evidence either way, and its callers already
- *  refuse it on their own terms. */
+ *  NO NEW THRESHOLD (thresholds.md): `hubBound` is the √N reading of "hub" used
+ * everywhere, and the containment read is clamped to it exactly as every other
+ * fan-out read is (bounded-reads.md). A query with no stored window at all is
+ * NOT scaffolding-only — it has no evidence either way, and its callers already
+ * refuse it on their own terms. */
 export declare function allWindowsAreScaffolding(ctx: MindContext, query: Uint8Array): boolean;
 /** Trained forms the query may OPEN, proposed from the write side's own
  *  leaf-id window index — the supply of last resort for prefix completion.
@@ -214,17 +216,17 @@ export declare function allWindowsAreScaffolding(ctx: MindContext, query: Uint8A
  *  by climbing containment then parents.  Nothing is added to the write side;
  *  this reads an index training already built.
  *
- *  BOUNDED (§2.8), AND WITH NO NEW THRESHOLD.  The window whose containment is
- *  SMALLEST carries the most evidence, and one saturated at `hubBound` carries
- *  none — that is the same √N reading of "hub" the rest of the mind uses, not
- *  a tuned knob.  The upward walk spends a budget of `hubBound` nodes and
- *  fans out by W, so a hub query enumerates nothing and the caller stays
- *  silent rather than guessing (§2.13).  Measured on the trained store: the
- *  photosynthesis form at a one-byte truncation picks a window with 52
- *  containers, visits 446 nodes, and yields exactly ONE candidate that
- *  survives the caller's byte compare — the form itself.
+ *  BOUNDED (bounded-reads.md), AND WITH NO NEW THRESHOLD. The window whose
+ * containment is SMALLEST carries the most evidence, and one saturated at
+ * `hubBound` carries none — that is the same √N reading of "hub" the rest of
+ * the mind uses, not a tuned knob. The upward walk spends a budget of
+ * `hubBound` nodes and fans out by W, so a hub query enumerates nothing and the
+ * caller stays silent rather than guessing (INVARIANTS.md). Measured on the
+ * trained store: the photosynthesis form at a one-byte truncation picks a
+ * window with 52 containers, visits 446 nodes, and yields exactly ONE candidate
+ * that survives the caller's byte compare — the form itself.
  *
- *  These are PROPOSALS only.  Every candidate still faces the byte-exact
- *  prefix compare and all three guards below, so a wrong proposal costs one
- *  bounded read and can never be voiced (§2.3). */
+ *  These are PROPOSALS only. Every candidate still faces the byte-exact prefix
+ * compare and all three guards below, so a wrong proposal costs one bounded
+ * read and can never be voiced (exact-vs-approximate.md). */
 export declare function formsOpenedBy(ctx: MindContext, query: Uint8Array): number[];