@hviana/sema 0.5.2 → 0.5.4

package/src/mind/{prefix-completion.ts → mechanisms/prefix-completion.ts}

@@ -1,5 +1,20 @@
-// prefix-completion.ts — Grounding a query that IS the opening of a trained
-// form.
+// mechanisms/prefix-completion.ts — Grounding a query that IS the opening of a
+// trained form (Grounding V).
+//
+// A MECHANISM, NOT A TIER.  This used to run inside recall's refusal path, in
+// a fixed if-chain that first-match-wins — the shape CAST was refactored away
+// from, where placement rather than the cost ladder decided.  Its claim is
+// maximal (every query byte literally matched, from offset zero, against a
+// trained form) at one STEP, so as a market candidate it competes honestly and
+// the decider weighs it like everything else.  It is registered LAST: recall's
+// exact self-match makes an IDENTITY claim about the query while this makes a
+// CONTAINMENT one, and on an exact grade tie the identity claim is the
+// stronger evidence — the same ordering §2.3's ladders use.
+//
+// Its SUPPLY moved too, and further: `formsOpenedBy` (traverse.ts) answers a
+// question about the STORE — "which trained forms does this byte run open?" —
+// so it is retrieval machinery any mechanism may ask, not this one's private
+// helper.
 //
 // THE SHAPE.  `The capital of France is` grounds nothing, while
 // `The capital of France is Paris.` is trained and reads back byte-exact.  The
@@ -75,96 +90,12 @@
 // same continuation reached through two trained forms is one answer, not an
 // ambiguity.
 
-import type { MindContext } from "./types.js";
-import { bytesEqual } from "../bytes.js";
-import { rItem } from "./trace.js";
-import { canonicalWindows, leafIdPrefix } from "./canonical.js";
-import { hubBound } from "./traverse.js";
-
-/** Trained forms the query may OPEN, proposed from the write side's own
- *  leaf-id window index — the supply of last resort for {@link
- *  prefixCompletion}.
- *
- *  WHY A SECOND SUPPLY EXISTS.  The ranked list this mechanism normally reads
- *  is a resonance list, and resonance cannot rank a proper prefix: measured on
- *  the trained store, cos(prefix, form) falls from 0.9629 at a one-byte
- *  truncation to 0.6206 at three bytes, against a reachThreshold of 0.8750.
- *  Three bytes of truncation put the answer out of reach on GEOMETRY, not on a
- *  bug, so no k and no re-ranking recovers it.
- *
- *  WHY THIS ROUTE WORKS WHERE THE FOLD DOES NOT.  A query's own fold is
- *  useless here: content addressing is not phrase-position-invariant, so a
- *  standalone prefix folds to a DIFFERENT node than the same bytes sitting
- *  inside a longer deposit, and neither the prefix's own node nor its
- *  ancestors lead to the deposit (measured: the 22-byte prefix of the
- *  photosynthesis form resolves, is shared by 6 contexts, and does not have
- *  the form among its ancestors).  Leaf ids ARE position-invariant — they are
- *  content-addressed on single bytes — and `indexSubSpans` already interns a
- *  flat branch over every canonical WINDOW of a deposit's leaf-id stream, with
- *  containment edges to the chunks that window spans.  A query that is a
- *  prefix therefore shares those window nodes exactly, and reaches the deposit
- *  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.
- *
- *  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). */
-export function prefixCandidates(
-  ctx: MindContext,
-  query: Uint8Array,
-): number[] {
-  const store = ctx.store;
-  const W = ctx.space.maxGroup;
-  const run = leafIdPrefix(ctx, query);
-  // The widest canonical window is the most discriminative one the write side
-  // ever interned; a query too short to spell one carries no window evidence.
-  const len = canonicalWindows(W)[1];
-  if (run.length < len) return [];
-  const bound = hubBound(ctx);
-
-  let best: number | null = null;
-  let bestN = 0;
-  for (let off = 0; off + len <= run.length; off++) {
-    const wid = store.findBranch(run.slice(off, off + len));
-    if (wid === null) continue;
-    const n = store.containersSlice(wid, 0, bound).length;
-    // Empty says the window spans no chunk; saturated says it is a hub, whose
-    // containment discriminates nothing.  Neither is evidence.
-    if (n === 0 || n >= bound) continue;
-    if (best === null || n < bestN) {
-      best = wid;
-      bestN = n;
-    }
-  }
-  if (best === null) return [];
-
-  let frontier = store.containersSlice(best, 0, bound);
-  const seen = new Set<number>(frontier);
-  let budget = bound;
-  while (frontier.length > 0 && budget > 0) {
-    const next: number[] = [];
-    for (const f of frontier) {
-      if (budget-- <= 0) break;
-      for (const p of store.parentsFirst(f, W)) {
-        if (seen.has(p)) continue;
-        seen.add(p);
-        next.push(p);
-      }
-    }
-    frontier = next;
-  }
-  return [...seen];
-}
+import type { MindContext } from "../types.js";
+import { bytesEqual } from "../../bytes.js";
+import { rItem } from "../trace.js";
+import { formsOpenedBy } from "../traverse.js";
+import { STEP } from "../graph-search.js";
+import type { PipelineMechanism, Precomputed } from "../pipeline-mechanism.js";
 
 /** A trained form the query opens, and the bytes by which it continues. */
 export interface PrefixCompletion {
@@ -312,3 +243,46 @@ export function prefixCompletion(
     data,
   );
 }
+
+// ── Pipeline mechanism ──────────────────────────────────────────────────────
+
+export const prefixMechanism: PipelineMechanism = {
+  name: "prefix",
+  provenance: "prefix",
+  async floor(ctx, query, _pre, worthRunning) {
+    // One projection: the form is voiced whole, nothing is substituted.
+    // INVESTMENT DISCIPLINE — the supplies below are the response's wide
+    // candidate list and a bounded √N walk, so neither is touched until the
+    // bound can still beat the incumbent.
+    if (!worthRunning(STEP)) return STEP;
+    // A query with no room for a perceivable continuation inside the phrase
+    // cap cannot clear guard 2, so it is not worth a single read.
+    const cap = query.length * ctx.space.maxGroup;
+    if (query.length === 0 || cap < query.length + ctx.space.maxGroup) {
+      return null;
+    }
+    return STEP;
+  },
+  async run(ctx, query, pre) {
+    // The response's shared wide list first; only when it supplies nothing does
+    // the write side's window index propose.  That ordering is the whole cost
+    // story: a query the ranked list can already explain pays not one extra
+    // read, and the bounded walk is spent only where the alternative is an
+    // empty answer.  A second SUPPLY, not a second mechanism — the same three
+    // guards decide either way.
+    const completed = prefixCompletion(ctx, query, await pre.wideResonance()) ??
+      prefixCompletion(ctx, query, formsOpenedBy(ctx, query));
+    if (completed === null) return [];
+    return [{
+      bytes: completed.form,
+      // Every query byte is literally matched against the form, so there is
+      // nothing to be humble about in the accounting — the same reading the
+      // IDENTITY bridge takes.
+      accounted: [[0, query.length]],
+      moves: STEP,
+      unexplained: "",
+      // NOT complete: the query is a proper PREFIX, so the form may carry more
+      // past the remainder this voiced.
+    }];
+  },
+};

package/src/mind/mechanisms/recall.ts

@@ -1,4 +1,4 @@
-// mechanisms/recall.ts — Recall by resonance (Grounding IV).
+// mechanisms/recall.ts — Recall by resonance (Grounding VI).
 //
 // The recall mechanism resonates the whole query's gist against the content
 // index and grounds the nearest learned form.  Four tiers, orderly degrading
@@ -17,14 +17,17 @@ import type { MindContext } from "../types.js";
 import { gistOf, read, resolve } from "../primitives.js";
 import { bytesEqual, indexOf } from "../../bytes.js";
 import { allWindowsAreScaffolding, corpusN, hubBound } from "../traverse.js";
-import { follow, project, reverseContext } from "../match.js";
+import {
+  follow,
+  project,
+  reverseContext,
+  voicesDisplacedFiller,
+} from "../match.js";
 import { CONCEPT, STEP } from "../graph-search.js";
 import { unexplainedLabel } from "../rationale.js";
 import type { PipelineMechanism, Precomputed } from "../pipeline-mechanism.js";
 import { rItem, rNode } from "../trace.js";
 import { substitutionBridge } from "../bridge.js";
-import { frameFillerSubstitution } from "../frame-filler.js";
-import { prefixCandidates, prefixCompletion } from "../prefix-completion.js";
 
 /** A recall result. */
 export interface RecallResult {
@@ -165,7 +168,10 @@ export async function recallByResonance(
     }
   }
 
-  const whole = await ctx.store.resonate(queryGist, k);
+  // The response's ONE top-k read (Precomputed.resonance) — the same list the
+  // frame inventory is assembled from, so a query that reaches both pays for a
+  // single ANN query rather than two identical ones.
+  const whole = await pre.resonance();
   if (whole.length === 0) {
     return ground(null, "empty store — nothing to resonate with", [], 0);
   }
@@ -348,7 +354,28 @@ export async function recallByResonance(
         (dominates(forest[0].breadth, 1) && forest[0].peak > Math.LN2))
     ) {
       const g = await project(ctx, forest[0].anchor, queryGist);
-      // The anchor cleared the consensus floor, but the floor prices the
+      // THE ANCHOR'S OCCUPANT IS NOT THE ASKER'S.  This tier grounds an anchor
+      // the climb elected, and voices that anchor's continuation.  When the
+      // query is the same structure with one position filled differently, the
+      // continuation speaks the ANCHOR's occupant of that position — a fluent,
+      // specific, wrong answer (see voicesDisplacedFiller).  Refusing here is
+      // silence, not a redirection: putting the asker's referent in its place
+      // is a stronger claim that needs the corpus's own carriage evidence, and
+      // that is `reference`'s job.
+      const anchorBytes = read(
+        ctx,
+        forest[0].anchor,
+        query.length * ctx.space.maxGroup + 1,
+      );
+      if (g !== null && voicesDisplacedFiller(ctx, query, anchorBytes, g)) {
+        ctx.trace?.step(
+          "displacedFiller",
+          [rItem(query, "query"), rNode(ctx, forest[0].anchor, "anchor")],
+          [rItem(g, "withheld")],
+          "refused — the anchor's continuation speaks the anchor's own " +
+            "occupant of a position this query fills differently",
+        );
+      } // The anchor cleared the consensus floor, but the floor prices the
       // ANCHOR's evidence, not the projection's: a junk attractor can clear
       // it and project a PIECE OF THE QUERY back at it (the observed
       // "buenos días in English" → "English" fragment).  A projection that
@@ -356,7 +383,7 @@ export async function recallByResonance(
       // — never an answer (the same principle as `restates` above, extended
       // to fragments).  Genuine anchor groundings — longer than the query,
       // or disjoint from it — pass untouched.
-      if (g && !(g.length < query.length && indexOf(query, g, 0) >= 0)) {
+      else if (g && !(g.length < query.length && indexOf(query, g, 0) >= 0)) {
         return ground(
           g,
           "scaffolding-dominated query — ground the consensus-climb anchor",
@@ -385,48 +412,10 @@ export async function recallByResonance(
     }
   }
   // 3b. Corroborated-substitution bridge — refusal-path only (bridge.ts).
-  // MEMOISED ACROSS EVERY REMAINING TIER, and that is load-bearing rather than
-  // tidy: the bridge, prefix completion and the frame filler all read the SAME
-  // candidate list, so the exhaustive branch runs at most once per response.
-  // Without the memo each tier re-issues it — measured at 490 ms median against
-  // 13 ms non-exhaustive (36x).
-  const wideIdsOnce = async (): Promise<ReadonlyArray<number>> => {
-    // When the top resonance hit is below the concept threshold, the query
-    // gist has no concept-level match to any stored form — an exhaustive √N
-    // ANN would only score more vectors below the bar (profiled at 38K–40K
-    // annVectorReads per refusing query on a 325K-context store).  The
-    // bridge's structural channels (junction walks, anchor climbs) are the
-    // correct proposal source for a query whose gist has no clean match;
-    // the ANN cannot propose what the gist cannot rank.
-    // The condition above is the SCORE of the top hit, not the size of the
-    // corpus.  It used to be spelled `corpusN(ctx) <= (k · W)³`, which asks
-    // a different question and answers it wrongly at exactly the scale the
-    // note was written from: on the trained store N = 325,608 with k = 24
-    // and W = 4 puts the cube at 884,736, so that store took the exhaustive
-    // branch — the very branch measured here as 38K–40K annVectorReads.
-    // Measured cost of the mismatch: substitutionBridge 8,544ms of a
-    // 19,548ms think (44%), against 1,248ms and 14,218ms without it, with
-    // every answer in the battery byte-identical and the suite unchanged
-    // at 445/445.  Corpus size was never the discriminator; whether the
-    // gist ranks ANYTHING at concept level is.
-    //
-    // Reading it as the note states also removes a duplicated (k · W)³ —
-    // the same cube gates crossRegionVotes' walk budget, where it likewise
-    // never engages at real scale (see attention.ts).
-    if (whole.length > 0 && whole[0].score >= conceptThreshold(ctx.store.D)) {
-      const exhaustive = await ctx.store.resonate(
-        queryGist,
-        hubBound(ctx),
-        true,
-      );
-      return exhaustive.map((h) => h.id);
-    }
-    return whole.map((h) => h.id);
-  };
-  let wide: Promise<ReadonlyArray<number>> | null = null;
-  const wideIds = (): Promise<
-    ReadonlyArray<number>
-  > => (wide ??= wideIdsOnce());
+  // The WIDE candidate list every past-the-top-k mechanism reads lives on
+  // Precomputed (see wideResonance): shared across the whole response, so the
+  // exhaustive branch runs at most once whoever first-touches it.
+  const wideIds = () => pre.wideResonance();
 
   // Every gist-based tier has failed; before refusing, align the query
   // byte-for-byte against the trained contexts its own stored windows
@@ -547,86 +536,6 @@ export async function recallByResonance(
         );
       }
     }
-
-    // 3b′. PREFIX COMPLETION — refusal-path only (prefix-completion.ts).
-    // Inside the bridge's block, and deliberately: it consumes `wideIds`, the
-    // list the bridge has already fetched, so it costs a bounded byte compare
-    // per candidate and not one resonance.  The claim it makes is the
-    // strongest in the ladder — every query byte is a LITERAL match from
-    // offset zero of a trained form — so it needs no projection and no reach
-    // gate.  It runs after the bridge only because the bridge answers the
-    // richer relation when it can; a prefix match that the bridge also
-    // explains is the same trained form either way.
-    {
-      // The resonance list first; only when it supplies nothing does the
-      // write side's leaf-id window index propose (prefixCandidates).  That
-      // ordering is the whole cost story: a query the ranked list can already
-      // explain pays not one extra read, and the fallback's bounded walk is
-      // spent only where the alternative is an empty answer.  It is a second
-      // SUPPLY, not a second mechanism — the same three guards decide.
-      const completed = prefixCompletion(ctx, query, await wideIds()) ??
-        prefixCompletion(ctx, query, prefixCandidates(ctx, query));
-      if (completed !== null) {
-        return ground(
-          completed.form,
-          "prefix completion — the query IS the opening of exactly one " +
-            "trained form, which this grounds whole",
-          // Every query byte is literally matched against the form.  The
-          // completion is the form's own continuation, not a substitution, so
-          // there is nothing to be humble about in the accounting — the same
-          // reading the IDENTITY bridge above takes.
-          whole_,
-          STEP,
-          false,
-          // NOT complete: the query is a proper PREFIX, so the form may carry
-          // more past the remainder this tier voiced.
-          false,
-        );
-      }
-    }
-  }
-
-  // 3c. FRAME-FILLER SUBSTITUTION — refusal-path only (frame-filler.ts).
-  // The bridge has failed, and for the shape this tier answers it MUST fail:
-  // a definite description standing where a proper noun stands is not a
-  // similarity relation the bridge can price (raw balance refuses
-  // `dominates(6, 37)`, and correctly — that is the France/Spain trap).  This
-  // tier makes a different claim: not that the two spans resemble each other,
-  // but that the store ALREADY HOLDS this query with the filler in the
-  // description's place, byte-exactly.  A key the store does not hold is
-  // discarded, so the answer is always a trained continuation.
-  {
-    // THE COHORT NEEDS EVIDENCE, AND THE REFUSAL PATH HAS ALREADY BOUGHT IT.
-    // This tier reads constituency from what a cohort of exemplars does NOT
-    // share, so its resolution is bounded by how many instances of the frame it
-    // can see.  The top-k resonance hits are too few — on the two-hop probe the
-    // exemplars holding the query's discriminative content number TWO, and two
-    // structures agree on so little that a whole clause reads as content.  The
-    // exhaustive list the bridge fetched is the same evidence at ~570 wide, and
-    // it is already paid for (memoised above, so this costs no ANN call).
-    const filled = frameFillerSubstitution(ctx, query, await wideIds());
-    if (filled !== null) {
-      const g = await project(ctx, filled.id, queryGist);
-      // The same restated-fragment and manufactured-answer guards every tier
-      // above applies: a projection contained in the FILLER is the
-      // substitution restated as if it were knowledge, not knowledge.
-      if (
-        g !== null && g.length > 0 && !restates(g) &&
-        indexOf(filled.filler, g, 0) < 0 &&
-        !(g.length < query.length && indexOf(query, g, 0) >= 0)
-      ) {
-        return ground(
-          g,
-          "frame-filler substitution — a trained form IS this query with a " +
-            "corroborated filler in the described span's place",
-          // The frame is literally matched against the resolved form and the
-          // described span is explained by the substitution — the same
-          // matched-plus-substituted accounting the bridge reports.
-          [[0, query.length]],
-          CONCEPT + STEP,
-        );
-      }
-    }
   }
 
   // The refusal/echo decision.  The echo returns a stored form's bytes AS