@hviana/sema 0.3.0 → 0.4.1

package/src/mind/bridge.ts

@@ -94,9 +94,14 @@ import { cosine } from "../vec.js";
 import { conceptThreshold, dominates } from "../geometry.js";
 import { bytesEqual, indexOf } from "../bytes.js";
 import type { MindContext } from "./types.js";
-import { foldTree, perceive } from "./primitives.js";
+import { foldTree, perceive, read } from "./primitives.js";
 import { chainReach, leafIdRun } from "./canonical.js";
-import { corpusN, edgeAncestors, hubBound } from "./traverse.js";
+import {
+  corpusN,
+  edgeAncestors,
+  hubBound,
+  sharedReachMemo,
+} from "./traverse.js";
 import { rItem, rNode } from "./trace.js";
 
 /** One accepted substitution: query span [qs,qe) stands in for the
@@ -242,10 +247,30 @@ function align(
 
 /** Recall's corroborated-substitution bridge — see the module comment.
  *  Returns the best bridged grounding proposal, or null. */
+/** `proposed` is a THUNK, not a list: the bridge's own cheap gates (the
+ *  two-quantum query floor and the O(|query|) stored-window anchor scan)
+ *  decide whether ANY candidate can be aligned, and they need no proposals
+ *  to do it.  Resolving the caller's proposals eagerly meant recall paid its
+ *  exhaustive whole-index resonance — the most expensive single act on the
+ *  refusal path — for every query, including the ones whose windows the
+ *  store has never seen and which the anchor scan rejects outright.  Same
+ *  investment discipline the mechanism floors follow (AGENTS §2.6): never
+ *  compute a shared analysis just to discard it. */
 export async function substitutionBridge(
   ctx: MindContext,
   query: Uint8Array,
-  proposed: ReadonlyArray<number> = [],
+  proposed: () => Promise<ReadonlyArray<number>> = async () => [],
+): Promise<BridgeHit | null> {
+  const meter = ctx.meter;
+  return meter
+    ? meter.time("substitutionBridge", () => bridgeImpl(ctx, query, proposed))
+    : bridgeImpl(ctx, query, proposed);
+}
+
+async function bridgeImpl(
+  ctx: MindContext,
+  query: Uint8Array,
+  proposed: () => Promise<ReadonlyArray<number>>,
 ): Promise<BridgeHit | null> {
   const W = ctx.space.maxGroup;
   if (query.length < 2 * W) return null;
@@ -254,6 +279,38 @@ export async function substitutionBridge(
   const bar = conceptThreshold(ctx.store.D);
   const reachCap = chainReach(W);
 
+  // PHRASE-SCALE CANDIDATE CAP — the same |content|·W bound the weave
+  // (pipeline-mechanism.ts), the cross-region junction ladder's
+  // `maxInterior`, and structural resonance's `maxSiblingBytes` all apply,
+  // for the same reason and now at the one remaining place that read
+  // candidate contexts WHOLE.
+  //
+  // The bridge accepts a candidate only when the query is DOMINATED by its
+  // matched runs plus substitutions, with at most one window W of slack at
+  // each edge and at most one chain reach (W²) per interior gap — so the
+  // candidate region an accepted alignment can ever consume is bounded by
+  // |query|·W.  Content beyond that cannot participate in any alignment
+  // this function would accept; reading it is pure cost.  And a candidate
+  // an order of magnitude past the query is not a paraphrase of it: it is a
+  // document or a whole conversation that merely quotes a phrase, and
+  // grounding through ITS learnt edge voices that document's continuation,
+  // not a phrase answer.
+  //
+  // Measured on the 17.7M-node / 325K-context store: uncapped, the refusal
+  // path materialised up to ~1 MB of candidate bytes per query (up to √N
+  // proposals plus √N climbed contexts, each read in full), and the frame-
+  // unanimity scan — which walks EVERY collected candidate's bytes, inside
+  // the per-gap expansion loop — paid that volume back tens of times per
+  // substitution.  Recall's run() was 0.7–2.6 s per refusing query.
+  const capBytes = query.length * W;
+  /** A candidate's bytes, phrase-scale capped: null when it exceeds the cap
+   *  (read one byte past it, so "too long" is decided without materialising
+   *  the rest) or has no content. */
+  const candidateBytes = (sid: number): Uint8Array | null => {
+    const b = read(ctx, sid, capBytes + 1);
+    return b.length === 0 || b.length > capBytes ? null : b;
+  };
+
   // 1. The query's stored windows, rarest first (fewest containers — the
   //    most discriminative anchors; hub-clamped like every fan-out read).
   //    The scan doubles as the ONE store probe of every query window: the
@@ -302,6 +359,54 @@ export async function substitutionBridge(
     }
     return false;
   };
+  // ── EXPLAINED SPANS — the scaffolding judgement, corpus-global ──────────
+  //
+  // The question every gap poses is "may the two forms differ HERE without
+  // differing in what they SAY?", and that is the discriminative-vs-
+  // scaffolding question AGENTS §2.7 names, over the CORPUS-GLOBAL
+  // population.  It already has one definition — `dominates(reachOf(...), N)`,
+  // the same gate confluence's filler test uses ("scaffolding never binds").
+  // Nothing new is derived here; the bar is read, not invented.
+  //
+  // A span is explained when EITHER
+  //   • it is sub-quantum (< W) — typographic glue, the tolerance identityBar
+  //     already prices ("below one river window, byte overlap is chance"); or
+  //   • every full W-window inside it is COMMON by the store's own climb:
+  //     the ascent SATURATES (the window sits in more places than √N — the
+  //     climb's own definition of non-discriminative), or it resolves to a
+  //     majority of the corpus's contexts.  "the process of ", " is the ".
+  //
+  // THE READING MATTERS, not just the population (AGENTS §2.7).  This
+  // deliberately does NOT go through `reachOf`, which maps BOTH "saturated"
+  // and "reaches nothing" to Infinity.  For IDF weighting those are the same
+  // thing (no usable identity evidence); for THIS question they are
+  // opposites — a window reaching nothing is novel content, the most
+  // discriminative material there is, and reading it as Infinity would call
+  // it scaffolding.  Measured: with `reachOf`, "Is water wet?" was answered
+  // with "No, heavy water is not wet." — "heav"/"eavy" occur once, reach no
+  // edge-bearing ancestor, and were written off as filler.  So an
+  // empty-rooted window is NEVER explained, and neither is an untrained one
+  // (the same principle attestedQ applies to the query side).
+  const reachMemo = sharedReachMemo(ctx);
+  const explainedSpan = (
+    bytes: Uint8Array,
+    from: number,
+    to: number,
+  ): boolean => {
+    if (to - from < W) return true;
+    for (let o = from; o + W <= to; o++) {
+      const ids = leafIdRun(ctx, bytes, o, o + W);
+      if (ids === null) return false;
+      const wid = ctx.store.findBranch(ids);
+      if (wid === null) return false;
+      const r = edgeAncestors(ctx, wid, N, reachMemo);
+      if (r.saturated) continue; // in too many places to discriminate
+      if (r.roots.length === 0) return false; // reaches nothing: novel content
+      if (!dominates(r.contextsReached, N)) return false;
+    }
+    return true;
+  };
+
   anchors.sort((a, b) => a.rarity - b.rarity);
   // Up to W anchors, at least one window apart — the quantum's own count.
   const picked: typeof anchors = [];
@@ -331,11 +436,13 @@ export async function substitutionBridge(
   // that could align at all: alignment can only seed at a picked anchor
   // window occurring literally in the candidate (measured: unconditional
   // re-folds multiplied the refusal-path latency several-fold).
-  for (const sid of proposed) {
+  // FIRST TOUCH of the caller's proposals — past every gate that could have
+  // refused without them (see substitutionBridge's doc).
+  for (const sid of await proposed()) {
     if (seen.has(sid)) continue;
     seen.add(sid);
-    const tb = ctx.store.bytes(sid);
-    if (tb.length === 0) continue;
+    const tb = candidateBytes(sid);
+    if (tb === null) continue;
     if (
       !picked.some((a) => indexOf(tb, query.subarray(a.off, a.off + W), 0) >= 0)
     ) continue;
@@ -368,8 +475,14 @@ export async function substitutionBridge(
   }
 
   // 3. Align each candidate; gate its mismatches; keep the best.
+  // Over-cap candidates are dropped here rather than earlier: the climb
+  // channel deliberately reads no bytes while collecting (the climb visits
+  // hundreds of roots), so this is where its proposals are first sized.
   const allBytes = new Map<number, Uint8Array>();
-  for (const sid of candidates) allBytes.set(sid, ctx.store.bytes(sid));
+  for (const sid of candidates) {
+    const b = candidateBytes(sid);
+    if (b !== null) allBytes.set(sid, b);
+  }
 
   // FRAME UNANIMITY: a substitution U → C inside the frame (Lf, Rf) is
   // groundable only when the collected candidates — the store's own sample
@@ -428,8 +541,8 @@ export async function substitutionBridge(
   let best: BridgeHit | null = null;
   let bestAccounted = 0;
   for (const sid of candidates) {
-    const cBytes = allBytes.get(sid)!;
-    if (cBytes.length === 0) continue;
+    const cBytes = allBytes.get(sid);
+    if (cBytes === undefined) continue;
     // Seed at the rarest picked anchor that literally occurs in this
     // candidate.
     let seed: { qo: number; co: number } | null = null;
@@ -541,7 +654,7 @@ export async function substitutionBridge(
     // resonance rank but has no outgoing edge to bridge through).  This
     // mechanism exists to explain SUBSTITUTIONS; a query needing none is
     // recall's job, not the bridge's.
-    if (!ok || subs.length === 0) continue;
+    if (!ok) continue;
 
     // Coverage: matched runs plus accepted substitutions must dominate the
     // query, every interior gap already proved ≤ W above, and the EDGES
@@ -565,6 +678,70 @@ export async function substitutionBridge(
     if (spans[0][0] > W || query.length - reachEnd > W) continue;
     if (!dominates(covered, query.length)) continue;
 
+    // ZERO-SUBSTITUTION ADMISSION — an IDENTITY claim, not a substitution.
+    //
+    // A candidate needing no substitution is normally refused (see the trap
+    // above), and that refusal is right for the case it was written for: the
+    // query is a strict byte-PREFIX of several candidates, each of which
+    // continues differently, and nothing here corroborates picking one
+    // continuation over another.  But that trap has a signature — the
+    // candidate carries substantial content BEYOND the alignment, and that
+    // surplus is exactly the "answer" the bridge would be inventing.
+    //
+    // The opposite shape is not ambiguous at all: the alignment explains BOTH
+    // strings end to end, and the only thing between them is sub-quantum glue
+    // — typographic punctuation the fold treats as structure.  Then the two
+    // are the SAME learnt form, and grounding through its edge returns that
+    // form's own trained answer, never a chosen-among-many completion.
+    //
+    // Why the ladder cannot reach these otherwise: the gist is a STRUCTURAL
+    // signature, so a mid-string insertion shifts every fold boundary after
+    // it.  Measured: `Who wrote Romeo and Juliet?` against the trained
+    // `Who wrote "Romeo and Juliet"?` — two inserted quote characters — scores
+    // cos 0.377, BELOW unrelated neighbours like "Who wrote the opera
+    // Carmen??" (0.603).  Recall's identity tiers gate on identityBar (0.969
+    // here) and its reach tiers on 0.875, so no gist-based tier can ever see
+    // it; only byte-exact alignment can, which is what this function does.
+    //
+    // The claim is deliberately strict, in three parts:
+    //
+    //   • QUERY SIDE — EXACT.  Every byte of the query must be a literal
+    //     match against the candidate: covered === query.length, no slack at
+    //     all, not even sub-quantum.  The query is what we are answering, so
+    //     an identity claim about it may write off NOTHING.  This is stricter
+    //     than the ≤ W edge tolerance the substituted path uses, and it has
+    //     to be: with a one-window allowance, `what is 2^10?` matched the
+    //     trained `what is 2+2?` — "^10" against "+2", four bytes, both sides
+    //     below W — and answered "2+2 is 4.", outweighing cover's authoritative
+    //     ALU result.  Below W, byte OVERLAP is chance rather than evidence;
+    //     that never made a below-W DIFFERENCE meaningless, and digits are the
+    //     case that proves it.
+    //   • CANDIDATE SIDE, INTERIOR — each gap must be an EXPLAINED span (see
+    //     explainedSpan): sub-quantum glue, or corpus-global scaffolding.
+    //     This side is asymmetric ON PURPOSE.  Material the CANDIDATE has and
+    //     the query omits is not something the asker asked about: if it is
+    //     scaffolding, dropping it changes nothing ("What is *the process of*
+    //     photosynthesis?"); if it is discriminative, the candidate answers a
+    //     DIFFERENT, narrower question ("Is *heavy* water wet?") and must be
+    //     refused.  Only the corpus can tell those apart, and it does.
+    //   • CANDIDATE SIDE, SURPLUS — its bytes are the matched runs
+    //     (byte-identical to the query's, hence the same total length) plus
+    //     its own gap spans; anything past that is surplus, and surplus is
+    //     the prefix trap.  A prefix-completion candidate fails here by the
+    //     whole length of the completion it wanted to supply — which is why
+    //     admitting scaffolding interiors does not reopen that trap.
+    //
+    // Ordered cheapest-first: the two arithmetic tests run before
+    // explainedSpan, whose per-window `reachOf` climbs are the only costly
+    // part (shared through the response/conversation reach memo, and reached
+    // only by a candidate that already survived every structural gate).
+    if (subs.length === 0) {
+      if (covered !== query.length) continue;
+      const cGap = gaps.reduce((n, g) => n + (g.ce - g.cs), 0);
+      if (cBytes.length - covered - cGap > W) continue;
+      if (!gaps.every((g) => explainedSpan(cBytes, g.cs, g.ce))) continue;
+    }
+
     // KNOWN content may never be dismissed — see dismissedKnownContent
     // (the live case: "what is the capital of france" aligning into a
     // Matrix synopsis by writing off "ance" — a stored window of the

package/src/mind/canonical.ts

@@ -27,7 +27,12 @@ import type { MindContext } from "./types.js";
 
 /** The two sliding-window lengths the WRITE side interns over a stream's leaf
  *  ids: W−1 and W (the river's grouping quantum and its off-by-one neighbour,
- *  so a form straddling a group boundary is reachable from either cut). */
+ *  so a form straddling a group boundary is reachable from either cut).
+ *
+ *  Widening this to cover the reader's full segment scale (W−1..2W) was
+ *  measured and REFUTED: it tripled the store (3,160 → 8,980 nodes on a
+ *  200-pair corpus), slowed ingest 80%, and fixed not one test.  Unknown
+ *  regions are not caused by the index's scale. */
 export function canonicalWindows(W: number): [number, number] {
   return [W - 1, W];
 }

package/src/mind/graph-search.ts

@@ -350,6 +350,18 @@ export class GraphSearch {
     private readonly host: GraphSearchHost,
   ) {}
 
+  /** The hub bound √N (AGENTS §2.8) — the ONE fan-out cap, stated here
+   *  rather than imported from `traverse.ts` because this module is
+   *  deliberately host-based (it holds a bare Store, never a MindContext).
+   *  That is the same write/read-side duplication convention canonical.ts's
+   *  header documents: if the formula changes it must change in BOTH places.
+   *  It is stated ONCE per side, though — the expression used to be spelled
+   *  out at three call sites here, one of them inside a per-item rules
+   *  generator, and they had already drifted on the `Math.max(2, …)` floor. */
+  private hubBound(): number {
+    return Math.ceil(Math.sqrt(Math.max(2, this.store.edgeSourceCount())));
+  }
+
   /** Explore the Sema graph for the lightest cover of the query and return its
    *  chosen spans left-to-right — WITH the derivation's total weight (the g
    *  value of the goal item, in the exported cost ladder), which think's
@@ -442,7 +454,17 @@ export class GraphSearch {
       connectors,
       computedResults,
     );
-    const derivation = lightestDerivation(system);
+    // Search-effort accounting (src/meter.ts): the chart's pops/pushes are
+    // the cover's real cost, and a heuristic that stops being admissible
+    // shows up as a pop count that explodes while the answer stays the same.
+    const meter = this.host.meter;
+    const stats = meter ? { pops: 0, pushes: 0 } : undefined;
+    const derivation = lightestDerivation(system, stats);
+    if (meter && stats) {
+      meter.searches++;
+      meter.searchPops += stats.pops;
+      meter.searchPushes += stats.pushes;
+    }
     // When covering under a substitution map (articulation), a form→out rule is
     // the form EMITTING the asker's voice, not grounding to its own answer — so
     // tell the reader to name those moves `voice` rather than `ground`.
@@ -475,15 +497,12 @@ export class GraphSearch {
   ): DeductionSystem<GItem> {
     const W = this.maxGroup; // fusible span ceiling (shortest composite bound)
     // Same corpus-scale hub floor {@link atomIsHub}/{@link atomReach} (traverse.ts)
-    // derive for byte atoms — duplicated here rather than imported because this
-    // module is deliberately host-based (no MindContext), and both inputs
-    // (maxGroup, edgeSourceCount) are already in scope with no ctx needed.  If
-    // the formula ever changes, it must change in BOTH places (see canonical.ts's
-    // header for the same write/read-side duplication convention).
+    // derive for byte atoms — see {@link hubBound} below for why this module
+    // states the formula itself instead of importing it.
     const atomsAreHubs = Math.max(
       1,
       Math.ceil((this.store.edgeSourceCount() * W) / 256),
-    ) > Math.ceil(Math.sqrt(Math.max(2, this.store.edgeSourceCount())));
+    ) > this.hubBound();
     const nodeBytes = (n: number) => this.store.bytesPrefix(n, ALL);
     // Content-addressed probes over the store's hash-cons maps — the same keys
     // training filled.  No byte-by-byte trie walk.
@@ -753,10 +772,7 @@ export class GraphSearch {
       // guard then dead-ends it) with no way to reach the forward edge.
       // Forking offers every continuation as its own rule so the one that
       // genuinely advances (not a duplicate) is still reachable.
-      const bound = Math.ceil(
-        Math.sqrt(Math.max(2, this.store.edgeSourceCount())),
-      );
-      const nx = this.store.nextFirst(it.node, bound);
+      const nx = this.store.nextFirst(it.node, this.hubBound());
       if (nx.length) {
         // The SAME evidence-weighted disambiguation the first hop uses
         // (below) identifies the most-corroborated continuation.  Yielding
@@ -1142,16 +1158,39 @@ export class GraphSearch {
     // is opportunistic cross-leaf recovery exactly like recognition.ts's own
     // canonical chain — findLeaf/findBranch here have no idea WHY these two
     // leaves are adjacent, only that their concatenation happens to spell a
-    // trained form ("hi" recovered from "W[hi]ch").  The same corpus-scale
-    // caution recognition.ts's `boundary` gate applies: trust it fully when
-    // `l.i` is a position the query's OWN fold chose as a boundary (real
-    // structural evidence); past the scale where atoms themselves stop
-    // discriminating, an interior offset's opportunistic match is noise, not
-    // a genuine cross-leaf recovery.  A completion-involved fuse (l.rec ||
-    // r.rec) is a different, legitimate case — a rewrite growing into its
-    // neighbour — and is exempt, same as recognition.ts's rec-derived sites.
-    const trusted = l.rec || r.rec || ctx.starts.has(l.i) ||
-      !ctx.atomsAreHubs;
+    // trained form ("hi" recovered from "W[hi]ch").  At hub scale, where
+    // atoms themselves no longer discriminate, that coincidence is noise.
+    //
+    // A FOLD BOUNDARY IS NOT EVIDENCE.  This gate used to exempt any fuse
+    // starting at `starts.has(l.i)` — documented as "a position the query's
+    // OWN fold chose as a boundary (real structural evidence)".  The plain
+    // river fold CHOOSES NOTHING: `riverFold` groups fixed-arity
+    // (`for (i = 0; i < complete; i += mg)`), so `starts` is exactly
+    // {0, W, 2W, 3W, …} for every query.  Measured on three unrelated
+    // queries: starts = 0,4,8,12,16,20,24,28[,32] in every case — the set
+    // carries ZERO content information, and the exemption therefore fired at
+    // a quarter of all offsets by arithmetic alone.
+    //
+    // What it cost (17.9M-node store, W=4): "In which country is the Eiffel
+    // Tower?" fused the atoms "h"+"i" at offset 4 — trusted only because
+    // 4 ≡ 0 (mod 4) — into the trained form "hi", followed its continuation
+    // edge, and grounded "Hello there. If you are looking for Open
+    // Assistant, look no further." as a FACT, explaining 2 of 37 bytes
+    // (density 0.054, a fifth of the 1/W honesty bar `thinGrounding`
+    // reports and does not enforce).
+    //
+    // So the exemption is removed rather than replaced: there is no cheap
+    // signal here that means what it claimed to mean, and inventing one
+    // would be worse than admitting the absence. Genuine cross-leaf forms
+    // are not lost — recognition.ts's canonical pass already probes EVERY
+    // byte offset for the write side's interned windows and emits them as
+    // sites, which arrive here as `l.rec`/`r.rec` and stay exempt. What
+    // remains excluded at hub scale is precisely the case with no evidence
+    // behind it: two byte atoms that happen to spell something.
+    //
+    // Below hub scale nothing changes (`!atomsAreHubs`): on a small store
+    // coincidence is rare and every chain is real evidence.
+    const trusted = l.rec || r.rec || !ctx.atomsAreHubs;
     let node = (trusted && bytes.length <= ctx.W)
       ? ctx.findLeafU(bytes)
       : undefined;

package/src/mind/junction.ts

@@ -186,6 +186,16 @@ function cachedContainers(
  *     few levels of its parts).  A side too common to decide within the
  *     budget abstains here and falls through to the resonance tier (the
  *     climb's own saturation semantics).
+ *
+ *     REFUTED TIGHTENING (measured, 325K contexts): giving this walk
+ *     edgeAncestors' cumulative LATERAL-CONE limit — abstain once the
+ *     accumulated lateral entries pass √N — would cut most of the pops (47
+ *     of 56 walks exceed √N lateral, and 47 exhaust the budget), but TWO OF
+ *     THE FOUR walks that actually found a container had lateral spread of
+ *     1425 and 1426, far past √N.  The cone limit is sound for
+ *     edgeAncestors' question and wrong for this one: a junction container
+ *     is legitimately reached across many containing structures.  Half the
+ *     successful junctions would be lost.
  *   • per-node hub guards — parent fan-outs beyond √N are hubs (not
  *     expanded); each node contributes at most one √N page of containers;
  *     √N collected candidates decide. */
@@ -215,6 +225,7 @@ export function junctionContainersFrom(
   if (seeds.length === 0) return [];
 
   const b = budget ?? { n: bound * ctx.space.maxGroup };
+  if (ctx.meter) ctx.meter.junctionWalks++;
   // DEPTH CAP: perception trees are W-ary and a junction container is
   // phrase-scale, so it sits within ~log_W(maxContainer) structural levels
   // of its parts — at most W levels for any practical W (plus the
@@ -231,6 +242,7 @@ export function junctionContainersFrom(
   }));
   while (stack.length > 0 && out.length < bound && b.n-- > 0) {
     const { id: x, d } = stack.pop()!;
+    if (ctx.meter) ctx.meter.junctionPops++;
     const f = cachedRead(ctx, cache, x, maxContainer);
     if (f.length > maxContainer) continue; // beyond phrase scale: prune branch
     if (unordered) {

package/src/mind/match.ts

@@ -31,7 +31,7 @@ import { conceptThreshold, identityBar, significanceBar } from "../geometry.js";
 import { indexOf } from "../bytes.js";
 import type { MindContext } from "./types.js";
 import { leafIdRun } from "./canonical.js";
-import { gistOf, read, resolve } from "./primitives.js";
+import { foldTree, gistOf, perceive, read, resolve } from "./primitives.js";
 import {
   argmaxCosine,
   chooseAmong,
@@ -119,6 +119,25 @@ export function alignRuns(
   query: Uint8Array,
   ct: Uint8Array,
 ): Array<{ qs: number; qe: number; cs: number }> {
+  if (ctx.meter) {
+    ctx.meter.alignments++;
+    // The alignment family's honest unit: the seed index is O(|query|) but
+    // the run extension is O(|query|·|ct|) in the worst case, and a weave
+    // that starts scanning conversation-length contexts shows up HERE long
+    // before it shows up in a call count.
+    ctx.meter.alignCells += query.length * ct.length;
+  }
+  // MEASURED AND REFUTED — seeding at the write side's unit floor W−1 instead
+  // of W.  `canonicalWindows` interns both lengths precisely so a form
+  // straddling a group boundary is reachable from either cut, and the runs
+  // found here are exactly such remnants: test/29 C1's query shares only `ce `
+  // with `Ice is cold` — three bytes, never seeded at W, so that structure
+  // enters the weave carrying nothing but the scaffolding run every exemplar
+  // shares.  But this is a byte MATCHER between two streams, not an index, and
+  // at W−1 the corpus is dense with spurious 3-byte agreements: the extra runs
+  // reshuffle which point claims which span, and test/29 A2 loses its analog.
+  // C1 does not pass either way.  The store's unit floor does not transfer to
+  // the aligner's seed length.
   const quantum = Math.min(ctx.space.maxGroup, ct.length);
   if (quantum < 1 || query.length < quantum) return [];
   const gram = (b: Uint8Array, at: number): string => {
@@ -167,6 +186,13 @@ export function alignRuns(
  *  kind, so the substitution/redirection schemas work unchanged on conceptual
  *  alignment. */
 export interface GradedRun {
+  /** True for a run the CLIMB proposed rather than the byte matcher found — see
+   *  {@link computeWeave}'s phase 2.  Provenance only: a proposed run reaches
+   *  CAST already gated (dominant literal agreement, not frame, and over bytes
+   *  no literal run claimed), so every consumer reads it exactly like any other
+   *  run.  Filtering seat-shaped reads by this flag was tried and is NOT
+   *  needed — the gates, not the flag, are what make it safe. */
+  proposed?: boolean;
   qs: number;
   qe: number;
   cs: number;
@@ -542,3 +568,122 @@ export async function project(
   if (fc) return fc;
   return reverseContext(ctx, id, guide);
 }
+
+// ── The span-shape family ───────────────────────────────────────────────────
+//
+// "Is this answer drawn from this context?" has TWO formally distinct
+// readings, and the pair plus the anchor classifier built on them are SHARED
+// machinery — extraction proposes span-shaped exemplars with them, the
+// shared `Precomputed.spanShapedOf` container computes them, and fusion
+// (reasoning.ts) gates on the strict one.  They lived inside
+// mechanisms/extraction.ts, so `pipeline-mechanism.ts` and `reasoning.ts`
+// both had to import back OUT of a specific mechanism — an inversion the
+// mechanism market forbids (AGENTS §2.6: the shared contract may not depend
+// on any one mechanism; §2.5: a shared matcher belongs to this family, never
+// to a mechanism's private helpers).  Deleting extraction must not break the
+// shared container, so they live here.
+//
+//   • isSpanShaped  — the OPEN reading (sparse in-order embedding).
+//   • containsSpan  — the STRICT reading (contiguous run or resolved node).
+//   • skillExemplar — classify one anchor into (context, answer) using them.
+//
+// The two readings are NOT interchangeable; AGENTS §2.5 pins the distinction
+// and each function's own doc states what breaks if it is substituted.
+
+/** Check whether an anchor is a span-shaped skill exemplar: it represents a
+ *  fact whose context and answer together form a span-in-context pattern.
+ *  If the anchor has a nextOf continuation, that is the answer and the anchor
+ *  itself is the context.  Otherwise the anchor's prevOf parents provide
+ *  candidate contexts, and the longest one whose span is span-shaped wins. */
+export async function skillExemplar(
+  ctx: MindContext,
+  anchor: number,
+  guide?: Vec | null,
+): Promise<{ contextBytes: Uint8Array; answerBytes: Uint8Array } | null> {
+  if (ctx.store.hasNext(anchor)) {
+    const contextBytes = read(ctx, anchor);
+    const answerBytes = await follow(ctx, anchor, guide);
+    if (
+      answerBytes !== null && isSpanShaped(ctx, contextBytes, answerBytes)
+    ) {
+      return { contextBytes, answerBytes };
+    }
+    return null;
+  }
+  const answerBytes = read(ctx, anchor);
+  // Candidate contexts, capped at the hub bound (a common answer's reverse
+  // fan-in is corpus-sized).
+  const capped = ctx.store.prevFirst(anchor, hubBound(ctx));
+  const spanShaped: Array<{ id: number; bytes: Uint8Array }> = [];
+  for (const p of capped) {
+    const ctxB = read(ctx, p);
+    if (ctxB.length > 0 && isSpanShaped(ctx, ctxB, answerBytes)) {
+      spanShaped.push({ id: p, bytes: ctxB });
+    }
+  }
+  if (spanShaped.length === 0) return null;
+  // Among span-shaped contexts, the longest wins (the smallest spanning frame
+  // heuristic's dual: more frame to locate in the query); the query gist,
+  // when given, breaks LENGTH TIES via chooseAmong — the same reverse-regime
+  // disambiguator every context pick uses, whose gist cache spares the
+  // re-fold this block once paid per tied candidate.  Same strict first-seen
+  // tie-break as the hand loop it replaces.
+  const maxLen = Math.max(...spanShaped.map((s) => s.bytes.length));
+  const longest = spanShaped.filter((s) => s.bytes.length === maxLen);
+  let contextBytes = longest[0].bytes;
+  if (guide && longest.length > 1) {
+    const pick = chooseAmong(ctx, longest.map((s) => s.id), guide).id;
+    contextBytes = longest.find((s) => s.id === pick)!.bytes;
+  }
+  return { contextBytes, answerBytes };
+}
+
+/** Whether the answer is a SPARSE subsequence of the context (bytes in
+ *  order, arbitrary gaps) — the OPEN span-shape reading (see the section
+ *  note above).  This is what lets extraction validate a MULTI-PIECE
+ *  exemplar whose answer is stitched from several context runs — but it is
+ *  deliberately permissive, so it must never be used as evidence that one
+ *  span was "drawn from" another (see {@link containsSpan} for that).
+ *
+ *  There is deliberately NO containsSpan pre-check here: strict containment
+ *  IMPLIES the subsequence embedding (a contiguous run, or a resolved node —
+ *  whose content-addressed identity means its bytes occur contiguously — is
+ *  an in-order embedding with zero gaps), so the scan below decides alone,
+ *  with the same truth value.  The old pre-check re-perceived the context
+ *  (a full river fold) per CANDIDATE in skillExemplar's √N-capped loop —
+ *  pure cost, no discrimination. */
+export function isSpanShaped(
+  _ctx: MindContext,
+  context: Uint8Array,
+  answer: Uint8Array,
+): boolean {
+  let ai = 0;
+  for (let ci = 0; ci < context.length && ai < answer.length; ci++) {
+    if (context[ci] === answer[ai]) ai++;
+  }
+  return ai === answer.length;
+}
+
+/** STRICT containment: the answer's resolved node appears in the context's
+ *  folded tree, or the answer occurs as one CONTIGUOUS byte run of the
+ *  context.  This is real evidence the answer was drawn from the context.
+ *  Fusion gates on this — the sparse-subsequence reading of
+ *  {@link isSpanShaped} is trivially satisfied by short answers over long
+ *  queries ("cold" is a gap-tolerant subsequence of most sentences holding
+ *  c…o…l…d in order), and gating fusion on it silently starved multi-topic
+ *  queries of their further points of attention. */
+export function containsSpan(
+  ctx: MindContext,
+  context: Uint8Array,
+  answer: Uint8Array,
+): boolean {
+  const ansId = resolve(ctx, answer);
+  if (ansId !== null) {
+    let found = false;
+    foldTree(ctx, perceive(ctx, context), 0, (_n, _s, _e, node) => {
+      if (node === ansId) found = true;
+    });
+    if (found) return true;
+  }
+  return indexOf(context, answer, 0) >= 0;
+}