@hviana/sema 0.2.0 → 0.2.2

package/src/mind/mind.ts

@@ -14,8 +14,6 @@ import { bindSeat, fold, Sema, Space } from "../sema.js";
 import { Alphabet } from "../alphabet.js";
 import {
   bytesToTree,
-  bytesToTreePyramid,
-  type FoldPyramid,
   Grid,
   gridToTree,
   hilbertBytes,
@@ -109,7 +107,7 @@ export interface Conversation {
  *  foldTree returns their ids immediately — O(suffix) instead of
  *  O(context) for every tree walk. */
 interface ConversationData {
-  pyramid: FoldPyramid;
+  tree: Sema;
   bytes: Uint8Array;
   boundaries: number[];
   perceiveMemo: Map<string, Sema>;
@@ -244,9 +242,10 @@ export class Mind implements MindContext {
   // bounded: a pyramid costs ~KB per content byte (one D-float gist per
   // interior node), and only the few live conversation chains need to stay
   // warm, so 8 entries is the honest budget.
-  _depositTrees = new BoundedMap<string, import("../geometry.js").FoldPyramid>(
-    8,
-  );
+  _depositTrees = new BoundedMap<
+    string,
+    import("./types.js").DepositCacheEntry
+  >(8);
   _depositLens = new Set<number>();
   _internIds = new WeakMap<import("../sema.js").Sema, number>();
 
@@ -513,18 +512,20 @@ export class Mind implements MindContext {
    *  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(
+    const initBoundaries = state?.boundaries ? [...state.boundaries] : [];
+    const tree = bytesToTree(
       this.space,
       this.alphabet,
       initBytes,
+      undefined,
+      undefined,
+      initBoundaries.length > 0 ? initBoundaries : undefined,
     );
     this._conversations.set(id, {
-      pyramid,
+      tree,
       bytes: initBytes,
-      boundaries: state?.boundaries ? [...state.boundaries] : [],
+      boundaries: initBoundaries,
       perceiveMemo: new Map(),
       recogniseMemo: new Map(),
       climbMemo: new Map(),
@@ -572,25 +573,23 @@ export class Mind implements MindContext {
    *  place a context grows ({@link addTurn} and {@link respondTurn} both
    *  come through here), so the append semantics cannot drift. */
   private _growContext(data: ConversationData, turnBytes: Uint8Array): Sema {
-    const prevLen = data.pyramid.bytes;
+    const prevLen = data.bytes.length;
     // An empty turn neither grows the context nor marks a boundary —
     // boundaries are documented strictly increasing, and a zero-length
-    // "turn" is no turn.  The pyramid's zero-growth shortcut makes the
-    // refold below O(1), so the existing tree is returned unchanged.
+    // "turn" is no turn.  Nothing changed, so the existing tree stands.
     const grow = turnBytes.length > 0;
-    const grown = !grow
-      ? data.bytes
-      : prevLen > 0
-      ? concat2(data.bytes, turnBytes)
-      : turnBytes;
-    if (grow && prevLen > 0) data.boundaries.push(prevLen);
-    const { tree, pyramid } = bytesToTreePyramid(
+    if (!grow) return data.tree;
+    const grown = prevLen > 0 ? concat2(data.bytes, turnBytes) : turnBytes;
+    if (prevLen > 0) data.boundaries.push(prevLen);
+    const tree = bytesToTree(
       this.space,
       this.alphabet,
       grown,
-      data.pyramid,
+      undefined,
+      undefined,
+      data.boundaries.length > 0 ? data.boundaries : undefined,
     );
-    data.pyramid = pyramid;
+    data.tree = tree;
     data.bytes = grown;
     data.perceiveMemo.set(latin1Key(grown), tree);
     return tree;
@@ -644,6 +643,15 @@ export class Mind implements MindContext {
     this.canonMemo = this.canon ? new Map() : null;
 
     try {
+      // No recognise-memo pre-seeding here: that used to be necessary
+      // because the flat/positional fold lost visibility into an earlier
+      // turn's own structure once later bytes shifted its position
+      // (foldTree no longer visited the turn's root node).  The
+      // STABLE-PREFIX fold (see {@link ConversationData}) makes every
+      // turn's subtree independent of what follows it by construction, so
+      // recognise() finds it correctly on its own, first-touch, exactly
+      // once per turn — no workaround needed, and none pre-empting
+      // recognise()'s own memo with a partial result.
       const top = this.trace?.enter("respondTurn", [
         rItem(newContext, "query"),
       ]);

package/src/mind/primitives.ts

@@ -8,16 +8,16 @@ import { Sema } from "../sema.js";
 import {
   bytesToTree,
   bytesToTreePyramid,
-  type FoldPyramid,
   Grid,
   gridToTree,
   hilbertBytes,
+  stablePrefixFoldIncremental,
   stackGrids,
 } from "../geometry.js";
 import { canonHash } from "../canon.js";
 import { bytesEqual } from "../bytes.js";
 import { ALL } from "./types.js";
-import type { Input, MindContext } from "./types.js";
+import type { DepositCacheEntry, Input, MindContext } from "./types.js";
 
 // ── Address: bytes → node ──────────────────────────────────────────────
 
@@ -93,34 +93,76 @@ export function perceive(
   return gridToTree(ctx.space, ctx.alphabet, input as Grid);
 }
 
-/** The DEPOSIT-shaped perceive: the PLAIN fold (bit-identical to inference
- *  perception — that structural train/inference agreement is load-bearing
- *  for exact recall), computed INCREMENTALLY via the fold's level pyramid
- *  ({@link bytesToTreePyramid}).  An accumulated context (a conversation)
- *  grows by suffixes: the previous context's pyramid is cached by CONTENT
- *  (ctx._depositTrees), and this deposit refolds only the right edge of
- *  each level — O(turn) instead of O(context) per turn.  Purely a cache:
- *  the produced tree never depends on cache state. */
-export function perceiveDeposit(ctx: MindContext, bytes: Uint8Array): Sema {
-  let prev: FoldPyramid | undefined;
-  // Longest cached PROPER prefix first.
-  const lens = [...ctx._depositLens]
-    .filter((L) => L >= 2 && L < bytes.length)
-    .sort((a, b) => b - a);
-  for (const L of lens) {
-    const hit = ctx._depositTrees.get(latin1Key(bytes.subarray(0, L)));
-    if (hit !== undefined) {
-      prev = hit;
-      break;
+/** The DEPOSIT-shaped perceive.  A FIRST-SEEN input takes the PLAIN fold
+ *  (bit-identical to inference perception of a standalone query — that
+ *  structural train/inference agreement is load-bearing for exact recall),
+ *  computed incrementally via the fold's level pyramid
+ *  ({@link bytesToTreePyramid}).  An input that EXTENDS a previously
+ *  deposited one is a conversation context grown by one turn — the cached
+ *  prefix length IS the turn boundary (derived from the deposit sequence
+ *  itself, never from content conventions) — and takes the STABLE-PREFIX
+ *  fold over the accumulated boundaries, bit-identical to the boundary
+ *  fold query-time conversation perception uses, so the trained context
+ *  node and the query's context subtree are the SAME node.  Segment folds
+ *  reuse across deposits ({@link stablePrefixFoldIncremental}) — O(turn)
+ *  instead of O(context) per turn.  The fold state is purely a cache; the
+ *  boundary accumulation is what an evicted chain loses (falling back to
+ *  the plain fold, the pre-boundary shape — a warm replay restores it). */
+export function perceiveDeposit(
+  ctx: MindContext,
+  bytes: Uint8Array,
+  conversational = false,
+): Sema {
+  let prev: DepositCacheEntry | undefined;
+  let prefixLen = 0;
+  // Cache consult (both boundary lookup and stable-prefix reuse) is scoped
+  // to conversational deposits only — a bare, unrelated fact whose bytes
+  // happen to extend an earlier deposit is NOT a conversation turn, and
+  // must keep the plain fold so it shares structure with ITS OWN prior
+  // deposits, not fragment against a coincidental byte-prefix.
+  if (conversational) {
+    // Longest cached PROPER prefix first.
+    const lens = [...ctx._depositLens]
+      .filter((L) => L >= 2 && L < bytes.length)
+      .sort((a, b) => b - a);
+    for (const L of lens) {
+      const hit = ctx._depositTrees.get(latin1Key(bytes.subarray(0, L)));
+      // The suffix must bytes-equal the hit's OWN recorded continuation —
+      // proof this deposit is that turn's actual next turn, not a fact
+      // that coincidentally shares its byte prefix.
+      if (
+        hit !== undefined && hit.nextBytes !== undefined &&
+        bytesEqual(hit.nextBytes, bytes.subarray(L))
+      ) {
+        prev = hit;
+        prefixLen = L;
+        break;
+      }
     }
   }
-  const { tree, pyramid } = bytesToTreePyramid(
-    ctx.space,
-    ctx.alphabet,
-    bytes,
-    prev,
-  );
-  if (bytes.length >= 2) {
+  let tree: Sema;
+  let entry: DepositCacheEntry;
+  if (prev !== undefined) {
+    const boundaries = [...prev.boundaries, prefixLen];
+    const folded = stablePrefixFoldIncremental(
+      ctx.space,
+      ctx.alphabet,
+      bytes,
+      boundaries,
+      prev.stable,
+    );
+    tree = folded.tree;
+    entry = { boundaries, stable: folded.fold };
+  } else {
+    const plain = bytesToTreePyramid(ctx.space, ctx.alphabet, bytes);
+    tree = plain.tree;
+    entry = { boundaries: [], pyramid: plain.pyramid };
+  }
+  // Only a conversational deposit writes the cache too — otherwise a bare
+  // fact's plain fold could later be misread as a conversation's turn-zero
+  // boundary by an unrelated conversational deposit that happens to extend
+  // its bytes.
+  if (conversational && bytes.length >= 2) {
     // The lengths set drifts as the map evicts; past the probe budget the
     // drift itself becomes the cost (each stale length is an O(len) key
     // build), so both reset together — losing only warm-up on live chains.
@@ -128,7 +170,7 @@ export function perceiveDeposit(ctx: MindContext, bytes: Uint8Array): Sema {
       ctx._depositLens.clear();
       ctx._depositTrees.clear();
     }
-    ctx._depositTrees.set(latin1Key(bytes), pyramid);
+    ctx._depositTrees.set(latin1Key(bytes), entry);
     ctx._depositLens.add(bytes.length);
   }
   return tree;

package/src/mind/types.ts

@@ -19,7 +19,26 @@ import type {
   Site,
 } from "./graph-search.js";
 import type { Rationale } from "./rationale.js";
-import type { FoldPyramid, Grid } from "../geometry.js";
+import type { FoldPyramid, Grid, StableFold } from "../geometry.js";
+
+/** One {@link MindContext._depositTrees} entry — see that field's doc. */
+export interface DepositCacheEntry {
+  /** Turn boundaries accumulated over this content's deposit chain —
+   *  strictly increasing proper offsets, each a previously-deposited
+   *  whole-context length.  Empty for a first-seen (single-turn) input. */
+  boundaries: number[];
+  /** Plain-fold pyramid (first-seen inputs only). */
+  pyramid?: FoldPyramid;
+  /** Stable-prefix segment folds (grown-context inputs only). */
+  stable?: StableFold;
+  /** The continuation bytes this ctxInput was paired with in ingestPair, if
+   *  any — the ONLY thing that makes a later, longer ctxInput a genuine next
+   *  TURN of the same conversation rather than an unrelated fact that
+   *  happens to share this one's byte prefix (e.g. "2+2" vs. "2+2=5").  A
+   *  later deposit only takes this entry as its stable-prefix `prev` when
+   *  its own suffix bytes-equal this exactly. */
+  nextBytes?: Uint8Array;
+}
 import { concatBytes } from "../bytes.js";
 import { dominates } from "../geometry.js";
 
@@ -189,15 +208,19 @@ export interface MindContext extends GraphSearchHost {
    *  never invalidated.  Bounded LRU (byte-sized); a miss only re-perceives,
    *  never a correctness risk. */
   _gistCache: BoundedMap<number, Vec>;
-  /** DEPOSIT-path stable-prefix tree cache: content key (latin1) of a
-   *  deposited input → its plain-fold level PYRAMID, so the NEXT deposit
-   *  whose prefix it is (a conversation's accumulated context) reuses every
-   *  full aligned block and refolds only the right edge of each level —
-   *  O(turn) per deposit instead of O(context), with the tree BIT-IDENTICAL
-   *  to a from-scratch fold (see FoldPyramid).  Purely a performance cache.
-   *  Entry-count bounded (a pyramid is ~KB/byte of content; only the few
-   *  live conversation chains matter). */
-  _depositTrees: BoundedMap<string, FoldPyramid>;
+  /** DEPOSIT-path perception cache: content key (latin1) of a deposited
+   *  input → its accumulated turn BOUNDARIES plus reusable fold state.  A
+   *  deposit whose content extends a cached entry IS a conversation context
+   *  grown by one turn — the cached length is the new boundary — so it
+   *  folds with the SAME stable-prefix fold query-time perception uses
+   *  (structural train/inference agreement, load-bearing for recall),
+   *  reusing every already-folded segment via `stable` (see StableFold) —
+   *  O(turn) per deposit instead of O(context).  A first-seen input keeps
+   *  the plain fold and caches its `pyramid` (see FoldPyramid).  Purely a
+   *  performance cache for the FOLD STATE; the boundaries are semantic but
+   *  derived only from the deposit sequence itself (an evicted chain falls
+   *  back to plain-fold behavior, exactly the pre-boundary shape). */
+  _depositTrees: BoundedMap<string, DepositCacheEntry>;
   /** The byte lengths present in {@link _depositTrees} — the candidate
    *  prefix lengths probed (longest first).  Drifts on eviction (a stale
    *  length only costs a miss); cleared with the map when it outgrows the