@hviana/sema 0.8.0 → 0.8.2

package/src/mind/resonance.ts

@@ -380,15 +380,15 @@ export async function pivotInto(
   // 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,
@@ -399,11 +399,11 @@ export async function pivotInto(
   let pivotId: number | null = 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.
     // "Longest wins" ranks candidates but never asks whether the winner is
@@ -439,15 +439,15 @@ export async function pivotInto(
     // a span that was never a fact on its own is not one to step through.
     // 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);
     if (indexOf(answer, bytes, 0) < 0) continue;

package/src/mind/traverse.ts

@@ -32,11 +32,11 @@ interface StructCache {
   hasParents: Map<number, boolean>;
 }
 //
-// Budgeted on the same terms as the reach memo below (AGENTS §2.12): these
-// three maps are cleared on every write, but a long read-only session over a
-// large store converges on one entry per node per map with nothing to bound
-// it.  Past the cap all three are dropped together and re-derived, costing
-// cold structural probes and never a wrong answer.
+// Budgeted on the same terms as the reach memo below (caches.md): these three
+// maps are cleared on every write, but a long read-only session over a large
+// store converges on one entry per node per map with nothing to bound it. Past
+// the cap all three are dropped together and re-derived, costing cold
+// structural probes and never a wrong answer.
 const STRUCT_MEMO_MAX = 100_000;
 const structCaches = new WeakMap<object, StructCache>();
 
@@ -55,21 +55,22 @@ const structCaches = new WeakMap<object, StructCache>();
 // battery repeatedly reaches the same corpus scaffolding even when its
 // surface questions differ.
 //
-// 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.
+// Budgeted, not unbounded (caches.md): 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 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 function sharedReachMemo(
   ctx: MindContext,
 ): Map<number, AncestorReach> {
@@ -481,13 +482,14 @@ export 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 function leadsSomewhere(ctx: MindContext, id: number): boolean {
   const memo = getStructCache(ctx);
   if (cachedHasNext(ctx, id, memo)) return true;
@@ -539,10 +541,10 @@ function boundFor(contextCount: number): 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 function hubCap<T>(
   ctx: MindContext,
   ids: readonly T[],
@@ -581,16 +583,16 @@ export function contains(
  *  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. */
@@ -745,26 +747,33 @@ export function chooseNext(
   // NO consensusFloor gate here (tried and reverted — see
   // test/40-choosenext-scale-guard.test.mjs): that floor is calibrated for
   // POOLED, IDF-weighted CLIMB VOTES (recallByResonance, commitVotes), where
-  // each corroborating region contributes at most ln N and the floor grows
-  // with N exactly as that per-region ceiling does (HOW_IT_WORKS.md §8.6).
-  // `bestSupport` here is a different kind of quantity — a raw prevCount of
-  // how many training contexts predicted ONE destination, bounded by how
-  // often that specific fact was retold, never by corpus size N.  Gating an
-  // N-invariant count against an N-growing threshold guarantees failure
-  // once N is large enough, discarding genuinely, structurally dominant
-  // edges (observed: a fact corroborated 2-to-1-1-1 refused at N≈325K,
-  // falling back to a noisy concept-hop).  The loop above already IS the
-  // "genuinely competing" test: a tie leaves first-inserted as the pick
-  // (test/30's own pinned behaviour); a strict winner is real evidence
-  // regardless of corpus scale.  Matches HOW_IT_WORKS.md §25's own
-  // chooseNext pseudocode, which has no such floor.
+  // each corroborating region contributes at most ln N and the floor grows with
+  // N exactly as that per-region ceiling does (thresholds.md). `bestSupport`
+  // here is a different kind of quantity — a raw prevCount of how many training
+  // contexts predicted ONE destination, bounded by how often that specific fact
+  // was retold, never by corpus size N. Gating an N-invariant count against an
+  // N-growing threshold guarantees failure once N is large enough, discarding
+  // genuinely, structurally dominant edges (observed: a fact corroborated
+  // 2-to-1-1-1 refused at N≈325K, falling back to a noisy concept-hop). The
+  // loop above already IS the "genuinely competing" test: a tie leaves
+  // first-inserted as the pick (test/30's own pinned behaviour); a strict
+  // winner is real evidence regardless of corpus scale. Matches `chooseNext`'s
+  // own pseudocode, which has no such floor.
 
   // Trace is built lazily — the filter + map below only execute when a
   // trace listener is attached, so the common (no-trace) path pays only
   // for the prevCount calls in the loop above, never for extra rItemShort
   // byte-reads.
   if (ctx.trace) {
-    const others = capped.filter((c) => c !== best);
+    // A BOUNDED SAMPLE, AND THE COUNT.  The step used to carry EVERY candidate
+    // it weighed — measured on the trained store, 1559 out-items in one step
+    // (hubBound's own size) and 1082 in another (the hub's degree).  The
+    // rationale's job is to explain the CHOICE, and the count is what says how
+    // wide the field was; the declared candidate budget (`recallQueryK`) is what
+    // bounds the sample, so no number is invented here.
+    const others = capped
+      .filter((c) => c !== best)
+      .slice(0, ctx.cfg.rationaleSampleK);
     ctx.trace.step(
       "disambiguate",
       [rItemShort(ctx, best, "halo-evidence", bestSupport)],
@@ -838,12 +847,13 @@ function rItemShort(
  *  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
@@ -860,11 +870,11 @@ function rItemShort(
  *  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 function allWindowsAreScaffolding(
   ctx: MindContext,
   query: Uint8Array,
@@ -916,19 +926,19 @@ export function allWindowsAreScaffolding(
  *  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 function formsOpenedBy(
   ctx: MindContext,
   query: Uint8Array,

package/src/mind/types.ts

@@ -65,12 +65,38 @@ export interface GraphSearchHost {
     starts: ReadonlySet<number>;
   };
   chooseNext?(node: number): number | undefined;
+  /** The boundary positions of `bytes` under the engine's ONE boundary rule
+   *  (geometry.ts's `contentBoundaries`), or undefined when the host has no
+   *  space to ask.  The join's key is an entity plus a prefix of the tail, and
+   *  the prefix that names a stored relation ENDS on one of these boundaries —
+   *  measured, 5 of 5 accepted keys over four join-firing queries, where the
+   *  byte-by-byte scan spent 153 probes for 14 boundaries.  Boundaries are
+   *  content-defined and STABLE under prefix extension, which is why a corpus
+   *  key's end is a boundary of the query's own fold of the same bytes. */
+  contentCuts?(bytes: Uint8Array): readonly number[];
   /** The admission predicate — `traverse.ts`'s `leadsSomewhere`, its ONE
    *  definition: does this node bear an edge or a halo?  Optional, so a bare
    *  host (a raw Store and nothing else) still works; when present, the search
    *  uses it rather than re-probing the store, which keeps the predicate
    *  single-defined AND memoised on the response-scoped struct cache. */
   leadsSomewhere?(id: number): boolean;
+  /** Report a SEARCH REFUSAL into the rationale — the channel AGENTS §6
+   *  requires: a callback threaded through a call chain must FEED the
+   *  rationale, the way `GraphSearch`'s `onDerivation` feeds `traceDerivation`,
+   *  never a channel of its own.  Optional, so a bare host stays silent rather
+   *  than crashing. */
+  reportSearch?(
+    name: string,
+    parts: ReadonlyArray<Uint8Array>,
+    note: string,
+  ): void;
+  /** The CANONICAL resolver ({@link canonResolve}), optional like
+   *  {@link leadsSomewhere}.  The store's keys were written through the
+   *  canonical fold, so a fact's `Gustaf Molander` and the deposited
+   *  `gustaf molander` are the SAME node (measured inside a response: the
+   *  canonical resolver maps the surface form to the deposited node while a raw
+   *  resolve returns null).  A bare host falls back to the plain probe. */
+  canonResolve?(bytes: Uint8Array): number | null;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -297,10 +323,10 @@ 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. */
+   * nothing is profiling — see src/meter.ts. WRITE-ONLY from the engine's point
+   * of view: no inference decision may read a counter, or determinism is gone
+   * (determinism.md). Every call site is `ctx.meter?.x++`, so an unprofiled
+   * response allocates nothing. */
   meter: Meter | null;
   space: Space;
   alphabet: Alphabet;

package/src/store.ts

@@ -541,16 +541,16 @@ export interface Store {
   // selected by identity hash so the choice is a property of each constituent
   // and never of where it sits in the fold.
   //
-  // DURABLE DERIVED STATE, NOT A CACHE.  §2.12 permits a cache to cost only
+  // DURABLE DERIVED STATE, NOT A CACHE. caches.md permits a cache to cost only
   // speed; this decides which terms enter a halo — a learned relation — so an
-  // eviction would change the geometry rather than slow it down.  It is
+  // eviction would change the geometry rather than slow it down. It is
   // therefore written like the canon index: computed once, kept, never
-  // budgeted.  Soundness rests on the set being INTRINSIC — minimality,
-  // `len ≥ W` and non-domination are properties of the node's own subtree and
-  // do not move as the corpus grows.  The one corpus-dependent reading, the
-  // hub exclusion, is deliberately NOT stored: it is applied by the caller at
-  // pour time over the ≤ k candidates, which is the drift companyProfile
-  // already documents as benign and one-directional.
+  // budgeted. Soundness rests on the set being INTRINSIC — minimality, `len ≥
+  // W` and non-domination are properties of the node's own subtree and do not
+  // move as the corpus grows. The one corpus-dependent reading, the hub
+  // exclusion, is deliberately NOT stored: it is applied by the caller at pour
+  // time over the ≤ k candidates, which is the drift companyProfile already
+  // documents as benign and one-directional.
   //
   // Backends that do not implement the pair leave both absent; companyProfile
   // then recomputes the sketch per pour and simply loses the amortisation.
@@ -1789,18 +1789,18 @@ export abstract class AbstractStore implements Store {
    *  remainders must fit the budget.  Scattered differences leave a wide
    *  middle and are rejected.
    *
-   *  Every read here is CAPPED (§2.8).  It used to open with
-   *  `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the
-   *  full materialising `bytes()` read — on the deposit hot path, and only
-   *  then compare lengths.  So a candidate the length test was about to reject
-   *  had already been reconstructed byte for byte.  The LENGTHS decide first
-   *  instead, from the `contentLen` memo the interning order has already built
-   *  bottom-up, and the target's length is itself read under a cap: a target
-   *  longer than `la + W` is rejected without touching one of its bytes.
-   *  Same semantics — the old capped `b` read would have produced
-   *  `a.length + W + 1` here and failed the very same test — strictly fewer
-   *  byte reads.  The `+ 1` on each byte cap keeps `_prefix`'s
-   *  "complete reconstruction" test true, so the results still cache. */
+   *  Every read here is CAPPED (bounded-reads.md). It used to open with
+   * `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the full
+   * materialising `bytes()` read — on the deposit hot path, and only then
+   * compare lengths. So a candidate the length test was about to reject had
+   * already been reconstructed byte for byte. The LENGTHS decide first instead,
+   * from the `contentLen` memo the interning order has already built bottom-up,
+   * and the target's length is itself read under a cap: a target longer than
+   * `la + W` is rejected without touching one of its bytes. Same semantics —
+   * the old capped `b` read would have produced `a.length + W + 1` here and
+   * failed the very same test — strictly fewer byte reads. The `+ 1` on each
+   * byte cap keeps `_prefix`'s "complete reconstruction" test true, so the
+   * results still cache. */
   private differsByOneWindow(
     kids: NodeId[],
     targetId: NodeId,

package/test/08-storage.test.mjs

@@ -361,7 +361,7 @@ test("a halo accumulates poured signatures and gates on mass", async () => {
 });
 
 // A multi-turn conversation is deposited as ACCUMULATED-CONTEXT episodes — the
-// pattern HOW_IT_WORKS §19a prescribes and example/train.ts uses:
+// pattern example/train.ts uses:
 //   (t0)            → t1
 //   (t0 + t1)       → t2
 //   (t0 + t1 + t2)  → t3

package/test/100-complete-grounding-trace.test.mjs

@@ -0,0 +1,109 @@
+// 100-complete-grounding-trace.test.mjs — a declared-complete grounding SAYS
+// SO in the rationale.
+//
+// THE GAP THIS CLOSES.  `pipeline.ts` ends the derivation when the winning
+// grounding carries `MechanismResult.complete` — the mechanism's own claim that
+// the query IS a stored context, so its continuation is the whole read-out and
+// a further pivot could only chain PAST the fact that produced the answer.  The
+// decision was correct and SILENT: no step, no note.  A reader of the rationale
+// therefore could not tell
+//
+//     "the chain stopped because the query WAS the context"   (complete)
+//
+// apart from
+//
+//     "nothing followed"                                      (no continuation)
+//
+// which are different claims about the same answer.  AGENTS §6 makes that an
+// instrumentation defect rather than a documentation gap: a bound that
+// truncates must be reportable AT THE POINT it truncates, through the one
+// surface that already exists.
+//
+// WHAT IS PINNED HERE.
+//   1. the stop is REPORTED (step `completeGrounding`) when it happens;
+//   2. the stop is REAL — the post-grounding extension did not run (no pivot or
+//      forward-absorb step), so the report cannot rot into a lie;
+//   3. the report does NOT appear for an ordinary grounding, so it names a
+//      decision rather than decorating every response.
+//
+// The fixture is test/76's CARRIED frame: the continuation quotes its filler
+// (`Run gcc <X>`), which is the shape the reference mechanism binds and
+// declares complete.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const CARRIED = [
+  ["How do I compile hello.c?", "Run gcc hello.c"],
+  ["How do I compile server.c?", "Run gcc server.c"],
+  ["How do I compile parser.c?", "Run gcc parser.c"],
+];
+
+/** The frame fixture — the same one test/76 pins the binding on. */
+async function frame() {
+  const m = new Mind({ seed: 7, store: new SQliteStore({ path: ":memory:" }) });
+  await m.ingest(CARRIED);
+  return m;
+}
+
+/** A grounding that is NOT declared complete: one plain learnt edge. */
+async function plainChain() {
+  const m = new Mind({ seed: 7, store: new SQliteStore({ path: ":memory:" }) });
+  await m.ingest([["Eva director", "The director of Eva is Gustaf Molander."]]);
+  return m;
+}
+
+const moves = (steps) => steps.map((s) => s.mechanism.at(-1));
+
+test("a binding that declares itself complete reports the stop", async () => {
+  const m = await frame();
+  const steps = [];
+  await m.respondText("How do I compile main.c?", (s) => steps.push(s));
+
+  const stop = steps.find((s) => s.mechanism.at(-1) === "completeGrounding");
+  assert.ok(stop, "the rationale must report the declared-complete stop");
+  assert.match(
+    stop.note,
+    /declared complete/,
+    "the note must carry the CLAIM, not a description of the answer",
+  );
+});
+
+test("the reported stop is real: the extension did not run", async () => {
+  const m = await frame();
+  const steps = [];
+  const answer = await m.respondText(
+    "How do I compile main.c?",
+    (s) => steps.push(s),
+  );
+
+  // The binding spliced the asker's referent (behaviour under test, asserted
+  // WITHOUT a trace below — a trace can change an answer, so the step and the
+  // bytes are pinned separately).
+  assert.ok(answer.length > 0, "the binding must answer");
+  const seen = moves(steps);
+  assert.equal(
+    seen.includes("pivotStep") || seen.includes("absorbForward"),
+    false,
+    "a complete grounding must not be extended",
+  );
+});
+
+test("the non-traced answer is the spliced one", async () => {
+  const m = await frame();
+  const answer = await m.respondText("How do I compile main.c?");
+  assert.equal(answer.replace(/\0+/g, "").trim(), "Run gcc main.c");
+});
+
+test("an ordinary grounding reports no complete-grounding stop", async () => {
+  const m = await plainChain();
+  const steps = [];
+  await m.respondText("Eva director", (s) => steps.push(s));
+  assert.equal(
+    moves(steps).includes("completeGrounding"),
+    false,
+    "the step names a decision, not every response",
+  );
+});

package/test/101-alignment-gap-bound.test.mjs

@@ -0,0 +1,106 @@
+// 101-alignment-gap-bound.test.mjs — the alignment's gap bound SAYS SO when it
+// bites.
+//
+// THE GAP THIS CLOSES.  `alignAround` matches a query against a stored context
+// by sweeping for the next common run of ≥ W bytes, with each side's gap
+// bounded by `chainReach(W)` = W².  When the sweep ends with material still
+// unmatched on BOTH sides, the alignment stopped because of that BOUND — and
+// nothing reported it: `match.ts` emitted no trace at all.  A reader of the
+// rationale therefore saw a substituted answer (the frame filled with ANOTHER
+// instance's filler) with no way to tell that the answer's own span had been
+// refused by a cap.
+//
+// MEASURED BOUNDARY (W = 4, cap = 16).  Against a learned
+// `Book a table at <filler> tonight.` → `Your table at <filler> is booked.`
+// frame, a NOVEL filler binds while it fits the cap and is replaced by a stored
+// instance's filler once it does not:
+//
+//     filler 7 B  → answer quotes the asker's filler   (bound)
+//     filler 12 B → answer quotes the asker's filler   (bound)
+//     filler 18 B → answer carries ANOTHER filler      (substituted)
+//     filler 30 B → answer carries ANOTHER filler      (substituted)
+//
+// THIS FILE PINS THE REPORT, not the substitution: the step must exist and must
+// carry the derived cap, so the bound is auditable at the point it truncates
+// (AGENTS §6).  The substitution itself is the scope defect a later lot fixes;
+// when it is fixed, this file's behavioural control (a filler inside the cap is
+// quoted back) stays true and the report stays reachable.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Mind } from "../dist/src/index.js";
+import { alignAround } from "../dist/src/mind/match.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const WORDS =
+  ("alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo lima " +
+    "mike november oscar papa quebec romeo sierra tango uniform victor whiskey " +
+    "xray yankee zulu amber bronze copper dahlia ember fjord gossamer harbour " +
+    "indigo jasmine kestrel lantern marigold nectar opal pewter quartz ripple " +
+    "saffron thistle umber violet willow xenon yarrow").split(" ");
+
+const short = (i) => `${WORDS[i % 50]}${i}`;
+const long = (i) =>
+  `${WORDS[i % 50]} ${WORDS[(i * 3) % 50]} ${WORDS[(i * 7) % 50]} street ${i}`;
+
+/** The frame whose continuation quotes its filler, with mixed filler widths. */
+async function frame(n = 60, opts = {}) {
+  const store = new SQliteStore({ path: ":memory:", D: 1024 });
+  const mind = new Mind({ seed: 7, store, ...opts });
+  const pairs = [];
+  for (let i = 0; i < n; i++) {
+    const f = i % 3 === 0 ? long(i) : short(i);
+    pairs.push([
+      `Book a table at ${f} tonight.`,
+      `Your table at ${f} is booked.`,
+    ]);
+  }
+  await mind.ingest(pairs);
+  return { store, mind };
+}
+
+/** A novel filler of exactly `len` bytes, never ingested. */
+const novel = (len) => "zephyr quartz lantern ".repeat(3).slice(0, len).trim();
+
+// THE LAW'S ASSERTION, straight on the aligner.  There is no bound to report
+// any more: the sweep's work is proportional to the bytes a run spans, so a
+// divergence far past the old arity bound (chainReach(W) = 16) is simply
+// bridged, on both sides, by finding the next common run.
+test("a divergence far past the old arity bound is bridged, not truncated", () => {
+  const enc = new TextEncoder();
+  const head = "the common head of the frame ";
+  const tail = " and the common tail of the frame";
+  const q = enc.encode(head + "a".repeat(60) + tail);
+  const c = enc.encode(head + "b".repeat(60) + tail);
+  const at = head.length - 1; // the seed: the shared head's own boundary
+  const { matched, gaps } = alignAround(
+    { space: { maxGroup: 4 } },
+    q,
+    c,
+    at,
+    at,
+  );
+  assert.equal(
+    matched.length,
+    2,
+    "both common runs must be found: " + JSON.stringify(matched),
+  );
+  assert.equal(gaps.length, 1, "with exactly one substitution between them");
+  const g = gaps[0];
+  assert.ok(
+    g.qe - g.qs >= 60 && g.ce - g.cs >= 60,
+    "the substitution's extent is the pair's own: " + JSON.stringify(g),
+  );
+});
+
+test("control: a filler inside the cap is quoted back, and the fixture is live", async () => {
+  const filler = novel(12);
+  const { mind } = await frame();
+  const answer = (await mind.respondText(
+    `Book a table at ${filler} tonight.`,
+  )).replace(/\0+/g, "").trim();
+  assert.ok(
+    answer.includes(filler),
+    "inside the cap the frame binds the asker's own filler",
+  );
+});