@hviana/sema 0.1.6 → 0.1.7

package/src/geometry.ts

@@ -314,17 +314,32 @@ export function knownPrefixLength(
 /** Bytes → Sema tree.  `leafAt` and `lookup` are store capabilities for
  *  detecting previously-stored prefixes so the river can split at the
  *  correct boundary.  Pass them through from `perceive`; the geometry
- *  computes the stable prefix internally. */
+ *  computes the stable prefix internally.
+ *
+ *  `boundaries` is the CALLER-computed stable-prefix boundary set (§10.3):
+ *  strictly-increasing proper byte offsets, each the length of a prefix that
+ *  is already a stored whole-stream form.  When given, the fold splits into
+ *  the segments between consecutive boundaries — each folded independently,
+ *  exactly as it folded when it was learned — and the segment roots join
+ *  LEFT-NESTED (((s₀·s₁)·s₂)…), so every learnt cumulative-context root
+ *  reappears as an identical subtree (and, by hash-consing, the very same
+ *  node) inside the grown stream.  This is what lets a conversation's next
+ *  turn extend perception instead of refolding it: identical prefixes
+ *  produce identical subtrees regardless of what follows them. */
 export function bytesToTree(
   space: Space,
   alphabet: Alphabet,
   bytes: Uint8Array,
   leafAt?: (i: number) => number | null,
   lookup?: (leafIds: number[]) => number | null,
+  boundaries?: readonly number[],
 ): Sema {
   if (bytes.length === 0) {
     return sema(alphabet.vecs[0], new Uint8Array(0), null);
   }
+  if (boundaries !== undefined && boundaries.length > 0) {
+    return stablePrefixFold(space, alphabet, bytes, boundaries);
+  }
   const sb = (leafAt && lookup) ? knownPrefixLength(bytes, leafAt, lookup) : 0;
   return riverFold(
     space,
@@ -333,6 +348,83 @@ export function bytesToTree(
   ).tree;
 }
 
+/** The stable-prefix segmented fold (§10.3).  Each segment between
+ *  consecutive boundaries folds PLAINLY and independently; segment roots
+ *  join left-nested, and only the final root is normalized (the linear-fold
+ *  contract: one normalize per perception).  A segment's own inner splits
+ *  need no recursion here: a nested learnt prefix is itself an earlier
+ *  boundary, so the left-nested join reproduces every intermediate learnt
+ *  root ((s₀·s₁) IS the root the store learnt for the first two segments'
+ *  bytes, and so on). */
+function stablePrefixFold(
+  space: Space,
+  alphabet: Alphabet,
+  bytes: Uint8Array,
+  boundaries: readonly number[],
+): Sema {
+  const cuts: number[] = [];
+  let prev = 0;
+  for (const b of boundaries) {
+    if (b > prev && b < bytes.length) {
+      cuts.push(b);
+      prev = b;
+    }
+  }
+  if (cuts.length === 0) {
+    return riverFold(space, bytesToLeaves(alphabet, bytes), bytes.length).tree;
+  }
+  const edges = [0, ...cuts, bytes.length];
+  const segs: Folded[] = [];
+  for (let i = 0; i + 1 < edges.length; i++) {
+    const seg = bytes.subarray(edges[i], edges[i + 1]);
+    segs.push(riverFoldRaw(space, bytesToLeaves(alphabet, seg)));
+  }
+  let cur = segs[0];
+  for (let i = 1; i < segs.length; i++) cur = fold2(space, cur, segs[i]);
+  normalize(cur.tree.v);
+  return cur.tree;
+}
+
+/** Join two folded items as one 2-kid branch — the top-level join of the
+ *  stable-prefix fold, identical FP ops to foldSlice's seat-bound
+ *  accumulation over a group of two.  Unnormalized (interior). */
+function fold2(space: Space, a: Folded, b: Folded): Folded {
+  const D = space.D;
+  const gist = new Float32Array(D);
+  const kids = [a.tree, b.tree];
+  for (let k = 0; k < 2; k++) {
+    const seat = space.seats[k].fwd;
+    const v = kids[k].v;
+    for (let d = 0; d < D; d++) gist[d] += v[seat[d]];
+  }
+  return { tree: sema(gist, null, kids), len: a.len + b.len };
+}
+
+/** Plain river fold WITHOUT the final root normalize — the segment-level
+ *  building block of {@link stablePrefixFold} (interiors must keep their
+ *  byte-proportional magnitude; only the whole perception's root is ever
+ *  normalized). */
+function riverFoldRaw(space: Space, row: Folded[]): Folded {
+  if (row.length === 0) {
+    const z = new Float32Array(space.D);
+    return { tree: sema(z, new Uint8Array(0), null), len: 0 };
+  }
+  if (row.length === 1) return row[0];
+  let level = row;
+  while (level.length > 1) {
+    const next: Folded[] = [];
+    foldSlice(space, level, 0, level.length, next, false);
+    if (next.length === level.length) {
+      const forced: Folded[] = [];
+      foldSlice(space, next, 0, next.length, forced, true);
+      level = forced;
+    } else {
+      level = next;
+    }
+  }
+  return level[0];
+}
+
 // ---- pyramid fold (incremental plain perception) ----
 
 /** The PLAIN fold's full level pyramid — every level's item list, bottom

package/src/mind/attention.ts

@@ -27,7 +27,7 @@ import type {
   SaturationInfo,
 } from "./types.js";
 import { consensusFloor, dominates, estimatorNoise } from "../geometry.js";
-import { foldTree, gistOf, perceive, read } from "./primitives.js";
+import { foldTree, gistOf, latin1Key, perceive, read } from "./primitives.js";
 import { recognise } from "./recognition.js";
 import { leafIdRun } from "./canonical.js";
 import { corpusN, edgeAncestors } from "./traverse.js";
@@ -65,14 +65,19 @@ export async function climbAttentionAll(
   k: number,
   mode: DFMode = "inverse",
 ): Promise<AttentionRead> {
+  // Content-keyed memo — works for both single-turn respond() and multi-turn
+  // respondTurn().  Skipped while tracing.
   if (ctx.climbMemo && !ctx.trace) {
-    const key = `${k}:${mode}`;
-    let byRead = ctx.climbMemo.get(query);
-    if (byRead === undefined) ctx.climbMemo.set(query, byRead = new Map());
-    const hit = byRead.get(key);
+    const contentKey = latin1Key(query);
+    const modeKey = `${k}:${mode}`;
+    let byRead = ctx.climbMemo.get(contentKey);
+    if (byRead === undefined) {
+      ctx.climbMemo.set(contentKey, byRead = new Map());
+    }
+    const hit = byRead.get(modeKey);
     if (hit !== undefined) return hit;
     const read = await computeAttention(ctx, query, k, mode);
-    byRead.set(key, read);
+    byRead.set(modeKey, read);
     return read;
   }
   return computeAttention(ctx, query, k, mode);

package/src/mind/mechanisms/recall.ts

@@ -168,8 +168,21 @@ export async function recallByResonance(
   // long answer sharing only scaffolding pass; the query-relative fraction
   // measures exactly what the reach bar means: how much of THE QUERY the
   // store accounts for.
+  // Chance similarity survives the length conversion AMPLIFIED: the same
+  // √(lenG/lenQ) factor that converts an honest shared fraction into a
+  // query-relative one multiplies the estimator/chance floor too, so a long
+  // stored form (√(lenG/lenQ) ≈ 10 at 100×) lifted a noise-level cosine past
+  // the reach bar and grounded pure gibberish (observed).  Only the
+  // ABOVE-CHANCE part of the similarity is evidence of shared content —
+  // subtract the significance bar (3/√D, §8.3) before converting.  Derived
+  // from the existing bars; never tuned.
+  const sig = significanceBar(ctx.store.D);
   const fracOfQuery = (cos: number, otherLen: number): number =>
-    Math.min(1, cos * Math.sqrt(otherLen / Math.max(1, query.length)));
+    Math.min(
+      1,
+      Math.max(0, cos - sig) *
+        Math.sqrt(otherLen / Math.max(1, query.length)),
+    );
   for (const h of whole) {
     const g = await project(ctx, h.id, queryGist);
     if (g) {
@@ -186,18 +199,21 @@ export async function recallByResonance(
       }
     }
   }
-  // The refusal/echo decision, in the same query-relative units — the top
-  // hit's magnitude read from the store (contentLen: √bytes IS the linear
-  // fold's gist norm), never from re-reading its bytes.
-  // The magnitude read SATURATES at the decision point: frac reaches the
-  // reach bar exactly when lenH = lenQ·(reach/score)², so the walk never
-  // needs to see past that — a huge conversation root costs a capped read,
-  // and a clamped return decides "pass" identically (frac ≥ reach).
+  // The refusal/echo decision.  The echo returns a stored form's bytes AS
+  // the answer — a near-identity claim about the query — and identity-grade
+  // decisions are never made on an estimated score ("approximate scores may
+  // rank and propose; they may never decide", §6.2): the RaBitQ estimate
+  // overshooting the reach bar echoed a WRONG-entity neighbour ("capital of
+  // Zamunda?" echoed the Armenia fact, observed).  The bytes are read
+  // anyway to be echoed, so the decision uses their EXACT fold: one river
+  // fold of the top hit, measured in the same query-relative,
+  // chance-corrected units as the tier above.
   const reach = reachThreshold(ctx.space.maxGroup);
-  const lenCap = Math.ceil(
-    query.length * (reach / Math.max(top.score, 1e-6)) ** 2,
-  ) + 1;
-  if (fracOfQuery(top.score, ctx.store.contentLen(top.id, lenCap)) < reach) {
+  const topBytes = read(ctx, top.id);
+  const exact = topBytes.length > 0
+    ? cosine(queryGist, gistOf(ctx, topBytes))
+    : 0;
+  if (fracOfQuery(exact, topBytes.length) < reach) {
     return ground(
       null,
       "below reach threshold — nothing in the store relates to this query",
@@ -207,7 +223,7 @@ export async function recallByResonance(
   }
   // Honest echo.
   return ground(
-    read(ctx, top.id),
+    topBytes,
     "last resort: the nearest resonant form's own bytes (echo, not grounded)",
     [],
     0,

package/src/mind/mind.ts

@@ -14,6 +14,8 @@ import { bindSeat, fold, Sema, Space } from "../sema.js";
 import { Alphabet } from "../alphabet.js";
 import {
   bytesToTree,
+  bytesToTreePyramid,
+  type FoldPyramid,
   Grid,
   gridToTree,
   hilbertBytes,
@@ -68,6 +70,53 @@ export interface Response {
   provenance?: import("./pipeline.js").Provenance;
 }
 
+/** Serializable state of a conversation — can be saved and restored across
+ *  sessions.  The Mind never interprets the bytes; it only tracks their
+ *  cumulative lengths so the caller can reconstruct turn boundaries later
+ *  without inspecting content. */
+export interface ConversationState {
+  /** The accumulated context bytes — raw concatenation of every turn's
+   *  bytes in order.  No separator is inserted; the boundary offsets
+   *  ({@link boundaries}) tell the caller where each turn ends. */
+  context: Uint8Array;
+  /** Cumulative byte length after each completed turn.  Sorted, strictly
+   *  increasing, each {@code < context.length}.  The first turn's length
+   *  is `boundaries[0]`; the second turn starts at that offset, and so
+   *  on.  Empty for a single-turn or new conversation. */
+  boundaries: number[];
+}
+
+/** An active conversation handle.  Opaque — interact through the Mind's
+ *  conversation methods ({@link Mind.beginConversation},
+ *  {@link Mind.respondTurn}, {@link Mind.endConversation}). */
+export interface Conversation {
+  readonly id: number;
+}
+
+/** Internal per-conversation state.
+ *
+ *  The {@link pyramid} IS the conversation — the accumulated internal
+ *  processing state.  {@link bytes} is the raw accumulated input, kept
+ *  in sync with the pyramid for O(1) concatenation.
+ *
+ *  Memos persist across turns so the inference pipeline does not
+ *  re-process the prefix.  Content-keyed (latin1) — each turn's fresh
+ *  {@code Uint8Array} would never hit an object-identity key.
+ *
+ *  {@link resolvedSubtrees} caches foldTree resolutions at the Sema-node
+ *  level.  When the pyramid reuses prefix subtrees (identical objects),
+ *  foldTree returns their ids immediately — O(suffix) instead of
+ *  O(context) for every tree walk. */
+interface ConversationData {
+  pyramid: FoldPyramid;
+  bytes: Uint8Array;
+  boundaries: number[];
+  perceiveMemo: Map<string, Sema>;
+  recogniseMemo: Map<string, Recognition>;
+  climbMemo: Map<string, Map<string, AttentionRead>>;
+  resolvedSubtrees: WeakMap<Sema, { id: number; len: number }>;
+}
+
 // Mind module imports
 import type { AttentionRead, MindContext, Recognition } from "./types.js";
 import { changedNodes, liftAnswer, spliceAll } from "./types.js";
@@ -75,6 +124,7 @@ import {
   foldTree,
   gistOf,
   inputBytes,
+  latin1Key,
   perceive as perceiveImpl,
   read,
   resolve as resolveImpl,
@@ -132,19 +182,23 @@ export class Mind implements MindContext {
   /** The live rationale tracer for the inference currently in flight, or null. */
   trace: Rationale | null = null;
 
-  /** Per-response memo of the consensus climb.  NOTE: this memo and
-   *  {@link recogniseMemo} are BYPASSED while a rationale trace is attached
-   *  (every mechanism must emit its own steps), so a traced respond re-pays
-   *  up to four consensus climbs plus repeat recognitions — that is where the
-   *  traced-vs-untraced latency multiple comes from, by design. */
-  climbMemo: WeakMap<Uint8Array, Map<string, AttentionRead>> | null = null;
+  /** Memo of the consensus climb — content-keyed.  See {@link MindContext.climbMemo}. */
+  climbMemo: Map<string, Map<string, AttentionRead>> | null = null;
 
-  /** Per-response memo of recognise() — see {@link MindContext.recogniseMemo}. */
-  recogniseMemo: WeakMap<Uint8Array, Recognition> | null = null;
+  /** Memo of recognise() — content-keyed.  See {@link MindContext.recogniseMemo}. */
+  recogniseMemo: Map<string, Recognition> | null = null;
 
-  /** Per-response memo of perceive() — see {@link MindContext.perceiveMemo}. */
+  /** Memo of perceive() — content-keyed.  See {@link MindContext.perceiveMemo}. */
   perceiveMemo: Map<string, import("../sema.js").Sema> | null = null;
 
+  /** Subtree-resolution cache.  See {@link MindContext._resolvedSubtrees}. */
+  _resolvedSubtrees:
+    | WeakMap<
+      import("../sema.js").Sema,
+      { id: number; len: number }
+    >
+    | null = null;
+
   /** The perceived gist of the query currently being answered.  Set by `think`
    *  before the graph search runs; `chooseNext` consults it as a gate (a null
    *  guide means no query is in flight, so structural walkers keep plain
@@ -176,6 +230,11 @@ export class Mind implements MindContext {
   _depositLens = new Set<number>();
   _internIds = new WeakMap<import("../sema.js").Sema, number>();
 
+  // ── Conversation state ──────────────────────────────────────────────────
+
+  private _nextConvId = 1;
+  private _conversations = new Map<number, ConversationData>();
+
   // ── GraphSearchHost implementation ─────────────────────────────────────
 
   /** Canonical node id of a byte span.  Required by GraphSearchHost & MindContext. */
@@ -321,8 +380,8 @@ export class Mind implements MindContext {
    *  created, so adding a memo cannot forget its reset. */
   private beginResponse(inspectRationale?: InspectRationale): void {
     this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
-    this.climbMemo = new WeakMap();
-    this.recogniseMemo = new WeakMap();
+    this.climbMemo = new Map();
+    this.recogniseMemo = new Map();
     this.perceiveMemo = new Map();
   }
 
@@ -337,24 +396,26 @@ export class Mind implements MindContext {
     this._edgeChoice.clear();
   }
 
-  async respond(
-    input: Input,
+  /** Shared response core — the one path from bytes to voiced answer.
+   *  `respond` calls this directly; `respondTurn` has its own path
+   *  with conversation-persistent memos and incremental perception. */
+  private async _respondImpl(
+    queryBytes: Uint8Array,
     inspectRationale?: InspectRationale,
+    traceLabel = "respond",
   ): Promise<Response> {
     this.beginResponse(inspectRationale);
     try {
-      const inBytes = inputBytes(this, input);
-      const top = this.trace?.enter("respond", [
-        rItem(inBytes, "query"),
+      const top = this.trace?.enter(traceLabel, [
+        rItem(queryBytes, "query"),
       ]);
-
-      const thought = await think(this, inBytes, this.mechanisms);
+      const thought = await think(this, queryBytes, this.mechanisms);
       if (thought === null) {
         top?.done([], "nothing to perceive or an empty store — no answer");
         return { v: null, bytes: new Uint8Array(0) };
       }
 
-      const voiced = await articulate(this, thought.bytes, inBytes);
+      const voiced = await articulate(this, thought.bytes, queryBytes);
       top?.done(
         [rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)],
         "the answer, re-voiced in the asker's words",
@@ -369,6 +430,13 @@ export class Mind implements MindContext {
     }
   }
 
+  async respond(
+    input: Input,
+    inspectRationale?: InspectRationale,
+  ): Promise<Response> {
+    return this._respondImpl(inputBytes(this, input), inspectRationale);
+  }
+
   /** Text view of {@link respond}.  NUL bytes (0x00) are stripped before
    *  decoding — they are structural padding in text answers.  LOSSY for a
    *  binary answer that legitimately contains NULs: use {@link respond} and
@@ -381,6 +449,169 @@ export class Mind implements MindContext {
     return decodeText(r.bytes);
   }
 
+  // ── Conversation API ────────────────────────────────────────────────────
+
+  /** Begin a new conversation, optionally restoring from a previously-saved
+   *  {@link ConversationState}.  The returned handle is required for
+   *  {@link respondTurn} and {@link endConversation}.
+   *
+   *  Conversations are independent — a Mind can manage several concurrently.
+   *  Each tracks the fold pyramid (accumulated internal processing) and
+   *  turn-boundary offsets; the geometry never inspects content to guess
+   *  where one turn ends and the next begins. */
+  beginConversation(state?: ConversationState): Conversation {
+    const id = this._nextConvId++;
+    // Build the initial pyramid: from scratch for a new conversation,
+    // or from the saved context bytes when restoring.
+    const initBytes = state?.context ?? new Uint8Array(0);
+    const { pyramid } = bytesToTreePyramid(
+      this.space,
+      this.alphabet,
+      initBytes,
+    );
+    this._conversations.set(id, {
+      pyramid,
+      bytes: initBytes,
+      boundaries: state?.boundaries ? [...state.boundaries] : [],
+      perceiveMemo: new Map(),
+      recogniseMemo: new Map(),
+      climbMemo: new Map(),
+      resolvedSubtrees: new WeakMap(),
+    });
+    return { id };
+  }
+
+  /** End a conversation, releasing its internal resources (accumulated
+   *  context, boundary offsets, and the fold-pyramid cache).  Idempotent. */
+  endConversation(conv: Conversation): void {
+    this._conversations.delete(conv.id);
+  }
+
+  /** The current serialisable state of an active conversation.  Save this
+   *  to resume the conversation later via {@link beginConversation}. */
+  conversationState(conv: Conversation): ConversationState | null {
+    const data = this._conversations.get(conv.id);
+    if (!data) return null;
+    return {
+      context: data.bytes,
+      boundaries: [...data.boundaries],
+    };
+  }
+
+  /** Process one turn of a conversation.
+   *
+   *  `turn` is the raw input for the latest turn — its bytes are appended
+   *  to the accumulated context directly (raw concatenation).  The Mind
+   *  tracks the byte offset where each turn ends; no separator is ever
+   *  inserted or inspected.
+   *
+   *  Returns the response AND the updated {@link ConversationState} so the
+   *  caller can persist it.  The conversation handle's internal state is
+   *  updated in place — the returned state is a snapshot for storage. */
+  async respondTurn(
+    conv: Conversation,
+    turn: Input,
+    inspectRationale?: InspectRationale,
+  ): Promise<{ response: Response; state: ConversationState }> {
+    const data = this._conversations.get(conv.id);
+    if (!data) throw new Error(`Conversation ${conv.id} not found`);
+
+    const turnBytes = inputBytes(this, turn);
+    const prevLen = data.pyramid.bytes;
+
+    const prevBytes = data.bytes;
+    const newContext = prevLen > 0 ? concat2(prevBytes, turnBytes) : turnBytes;
+    data.bytes = newContext;
+
+    if (prevLen > 0) data.boundaries.push(prevLen);
+
+    // Incremental perception — O(turn) instead of O(context).
+    const { tree, pyramid } = bytesToTreePyramid(
+      this.space,
+      this.alphabet,
+      newContext,
+      data.pyramid,
+    );
+    data.pyramid = pyramid;
+
+    // Swap in the conversation's persistent state so the inference
+    // pipeline does not re-process the prefix from scratch.
+    //   perceiveMemo / recogniseMemo / climbMemo — content-keyed;
+    //     the prefix's results from the previous turn are found by
+    //     the current turn's sub-span calls.
+    //   _resolvedSubtrees — Sema-node-keyed; when the pyramid reuses
+    //     prefix subtrees (identical objects), foldTree returns their
+    //     ids immediately — O(suffix) instead of O(context).
+    this.perceiveMemo = data.perceiveMemo;
+    this.recogniseMemo = data.recogniseMemo;
+    this.climbMemo = data.climbMemo;
+    this._resolvedSubtrees = data.resolvedSubtrees;
+    this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
+
+    try {
+      this.perceiveMemo.set(latin1Key(newContext), tree);
+
+      const top = this.trace?.enter("respondTurn", [
+        rItem(newContext, "query"),
+      ]);
+
+      const thought = await think(this, newContext, this.mechanisms);
+      if (thought === null) {
+        top?.done([], "nothing to perceive or an empty store — no answer");
+        return {
+          response: { v: null, bytes: new Uint8Array(0) },
+          state: this.conversationState(conv)!,
+        };
+      }
+
+      const voiced = await articulate(this, thought.bytes, newContext);
+      top?.done(
+        [rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)],
+        "the answer, re-voiced in the asker's words",
+      );
+
+      return {
+        response: {
+          v: gistOf(this, voiced),
+          bytes: voiced,
+          provenance: thought.provenance,
+        },
+        state: this.conversationState(conv)!,
+      };
+    } finally {
+      // Save back to the conversation for the next turn.
+      data.perceiveMemo = this.perceiveMemo;
+      data.recogniseMemo = this.recogniseMemo;
+      data.climbMemo = this.climbMemo;
+      data.resolvedSubtrees = this._resolvedSubtrees!;
+      // Clear Mind references — non-conversation respond() calls get
+      // fresh per-response memos.
+      this.trace = null;
+      this.perceiveMemo = null;
+      this.recogniseMemo = null;
+      this.climbMemo = null;
+      this._resolvedSubtrees = null;
+      this._edgeGuide = null;
+      this._edgeChoice.clear();
+    }
+  }
+
+  /** Text view of {@link respondTurn}.  See {@link respondText} for the
+   *  NUL-stripping caveat.  For binary or grid turns use {@link respondTurn}
+   *  directly — this is a text-only convenience, like {@link respondText}. */
+  async respondTurnText(
+    conv: Conversation,
+    turn: string,
+    inspectRationale?: InspectRationale,
+  ): Promise<{ response: string; state: ConversationState }> {
+    const { response, state } = await this.respondTurn(
+      conv,
+      turn,
+      inspectRationale,
+    );
+    return { response: decodeText(response.bytes), state };
+  }
+
   async embedding(input: Input): Promise<Vec | null> {
     return (await this.respond(input)).v;
   }

package/src/mind/primitives.ts

@@ -4,8 +4,7 @@
 //   Read     — node → bytes   (read)
 
 import { Vec } from "../vec.js";
-import { Sema, Space } from "../sema.js";
-import { Alphabet } from "../alphabet.js";
+import { Sema } from "../sema.js";
 import {
   bytesToTree,
   bytesToTreePyramid,
@@ -24,7 +23,7 @@ import type { Input, MindContext } from "./types.js";
  *  collision-free encoding.  Spans on the perception path are query-scale
  *  (windows, regions, candidate spans), so key construction is far cheaper
  *  than the river fold it deduplicates. */
-function latin1Key(bytes: Uint8Array): string {
+export function latin1Key(bytes: Uint8Array): string {
   // Batched String.fromCharCode — avoids the O(n²) cost of repeated += on
   // potentially-large query spans, and stays well under the ~65536 arg limit.
   const n = bytes.length;
@@ -36,12 +35,19 @@ function latin1Key(bytes: Uint8Array): string {
 }
 
 /** Perceive input into a content-defined tree (the river fold).
- *  Deterministic — identical bytes always produce an identical tree. */
+ *  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. */
 export function perceive(
   ctx: MindContext,
   input: Input,
   leafAt?: (i: number) => number | null,
   lookup?: (ids: number[]) => number | null,
+  boundaries?: readonly number[],
 ): Sema {
   if (typeof input === "string" || input instanceof Uint8Array) {
     const bytes = typeof input === "string"
@@ -57,11 +63,25 @@ export function perceive(
         const key = latin1Key(bytes);
         const hit = memo.get(key);
         if (hit !== undefined) return hit;
-        const tree = bytesToTree(ctx.space, ctx.alphabet, bytes);
+        const tree = bytesToTree(
+          ctx.space,
+          ctx.alphabet,
+          bytes,
+          undefined,
+          undefined,
+          boundaries,
+        );
         memo.set(key, tree);
         return tree;
       }
-      return bytesToTree(ctx.space, ctx.alphabet, bytes);
+      return bytesToTree(
+        ctx.space,
+        ctx.alphabet,
+        bytes,
+        undefined,
+        undefined,
+        boundaries,
+      );
     }
     return bytesToTree(ctx.space, ctx.alphabet, bytes, leafAt, lookup);
   }
@@ -136,11 +156,25 @@ export function foldTree(
   start: number,
   visit?: (n: Sema, start: number, end: number, node: number | null) => void,
 ): { end: number; node: number | null } {
+  // Fast path: subtree already resolved (from a previous conversation turn
+  // or an earlier recognition pass).  The pyramid reuses prefix subtrees as
+  // identical Sema objects, so this cache turns foldTree into O(suffix)
+  // instead of O(context) for multi-turn recognition.
+  const cached = ctx._resolvedSubtrees?.get(n);
+  if (cached !== undefined) {
+    const end = start + cached.len;
+    visit?.(n, start, end, cached.id);
+    return { end, node: cached.id };
+  }
+
   if (n.kids === null) {
     const b = n.leaf ?? new Uint8Array(0);
     const end = start + b.length;
     const node = ctx.store.findLeaf(b);
     visit?.(n, start, end, node);
+    if (node !== null && ctx._resolvedSubtrees) {
+      ctx._resolvedSubtrees.set(n, { id: node, len: b.length });
+    }
     return { end, node };
   }
   let pos = start;
@@ -154,6 +188,9 @@ export function foldTree(
   }
   const node = known ? ctx.store.findBranch(kids) : null;
   visit?.(n, start, pos, node);
+  if (node !== null && ctx._resolvedSubtrees) {
+    ctx._resolvedSubtrees.set(n, { id: node, len: pos - start });
+  }
   return { end: pos, node };
 }