@hviana/sema 0.9.0 → 0.9.2

package/src/alu/test/alu.test.ts

@@ -9,6 +9,7 @@ import assert from "node:assert/strict";
 import {
   addBits,
   Alu,
+  type AluHost,
   type AluResonance,
   asReal,
   compareBits,
@@ -579,6 +580,45 @@ test("conceptAnchors exposes the operation vocabulary for resonant recognition",
   }
 });
 
+test("a symbol's opposite is asked of the host only when the operation reads it", async () => {
+  // Only the polymorphic inverse reads an opposite.  Resolving every symbol
+  // operand's opposite up front paid one host call per operand for ANY
+  // operation — on SEMA a halo-index query each, 30-200 ms of a plain
+  // dialogue turn's parse that computed nothing.
+  const asked: string[] = [];
+  const host: AluHost = {
+    meaningOf: async () => null,
+    continuation: async (b) => {
+      asked.push(dec(b));
+      return dec(b) === "large" ? enc("small") : null;
+    },
+    segment: (bytes) => {
+      const runs: Array<{ i: number; j: number }> = [];
+      for (let i = 0; i < bytes.length;) {
+        if (bytes[i] === 32) {
+          i++;
+          continue;
+        }
+        let j = i;
+        while (j < bytes.length && bytes[j] !== 32) j++;
+        runs.push({ i, j });
+        i = j;
+      }
+      return runs;
+    },
+    reach: Number.POSITIVE_INFINITY,
+  };
+  const u = new Alu({}, host);
+  // An operation that does not read opposites: nothing computed, nothing asked.
+  assert.deepEqual(await u.parse(enc("sqrt large")), []);
+  assert.deepEqual(asked, []);
+  // The inverse reads it: asked once, and grounded exactly as before.
+  const out = await u.parse(enc("opposite large"));
+  assert.equal(out.length, 1);
+  assert.equal(dec(out[0].bytes), "small");
+  assert.deepEqual(asked, ["large"]);
+});
+
 test("prefetchRecognisedOps bridges async recognition to a sync map", async () => {
   // A stub host resonance: "the rate of change of" means a derivative.
   const stub: AluResonance = {

package/src/bytes.ts

@@ -35,11 +35,21 @@ export function concat2(a: Uint8Array, b: Uint8Array): Uint8Array {
   return out;
 }
 
-/** Latin-1 view of a byte span — a stable, lossless string key for chart
- *  memoization (every byte 0–255 maps to one code unit). */
+/** Latin-1 view of a byte span — ONE code unit per byte, so it is injective
+ *  and safe as an exact cache key (every byte 0–255 maps to one code unit).
+ *  Batched `String.fromCharCode`, chunked to stay within the engine's argument
+ *  limit on long spans; the one definition every content-keyed memo uses.
+ *  `apply` takes the typed array as its argument list directly — a spread
+ *  walks it through the iterator protocol first, ~2.7× slower per short key. */
 export function latin1(b: Uint8Array): string {
+  const n = b.length;
   let s = "";
-  for (let k = 0; k < b.length; k++) s += String.fromCharCode(b[k]);
+  for (let i = 0; i < n; i += 4096) {
+    s += String.fromCharCode.apply(
+      null,
+      b.subarray(i, Math.min(i + 4096, n)) as unknown as number[],
+    );
+  }
   return s;
 }
 

package/src/canon.ts

@@ -44,6 +44,12 @@ const enc = new TextEncoder();
  *  deliberately conservative: punctuation, digits and word order are content
  *  and pass through untouched. */
 export function textCanon(bytes: Uint8Array): Uint8Array {
+  if (isAscii(bytes)) return asciiCanon(bytes);
+  return unicodeCanon(bytes);
+}
+
+/** The general reading — the DEFINITION of {@link textCanon}. */
+function unicodeCanon(bytes: Uint8Array): Uint8Array {
   const s = dec
     .decode(bytes)
     .normalize("NFKC")
@@ -52,6 +58,40 @@ export function textCanon(bytes: Uint8Array): Uint8Array {
   return enc.encode(s);
 }
 
+function isAscii(bytes: Uint8Array): boolean {
+  for (let i = 0; i < bytes.length; i++) if (bytes[i] >= 0x80) return false;
+  return true;
+}
+
+/** {@link unicodeCanon} on ASCII input, byte for byte, without the string
+ *  round trip.  Exact, not approximate: NFKC is the identity on ASCII, the
+ *  lowercase of ASCII is A–Z → a–z, and the ASCII members of the regex's `\s`
+ *  are TAB, LF, VT, FF, CR and SPACE — so an interior run of them becomes one
+ *  space and an edge run stays verbatim, exactly as the regex rewrites it.
+ *  The canonicalizer runs once per probed span on the recognition and join
+ *  paths, so its constant is paid thousands of times per response; test/148
+ *  pins the agreement over random ASCII and over the edge cases. */
+function asciiCanon(bytes: Uint8Array): Uint8Array {
+  const n = bytes.length;
+  const out = new Uint8Array(n);
+  let o = 0;
+  const ws = (b: number) => b === 0x20 || (b >= 0x09 && b <= 0x0d);
+  for (let i = 0; i < n;) {
+    const b = bytes[i];
+    if (!ws(b)) {
+      out[o++] = b >= 0x41 && b <= 0x5a ? b + 0x20 : b;
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < n && ws(bytes[j])) j++;
+    if (i > 0 && j < n) out[o++] = 0x20;
+    else for (let k = i; k < j; k++) out[o++] = bytes[k];
+    i = j;
+  }
+  return o === n ? out : out.slice(0, o);
+}
+
 /** 32-bit FNV-1a over a canonical key — the integer the store's canon index
  *  is keyed on.  Same construction as the node table's content hash; a
  *  collision is resolved by verifying canon(stored) === key, never trusted. */

package/src/geometry.ts

@@ -204,16 +204,23 @@ export interface Grid {
 // groups of `maxGroup` adjacent items into one via permute-then-add
 // (positional seat binding), recursing until one root remains.
 //
-// FLAT per-level fold — one inline loop per level (foldSlice): no per-group
-// function calls, no Array.slice per group, the permute and add FUSED
-// (`gist[d] += v[seat[d]]`, no scratch buffer), and subtree byte lengths
-// carried incrementally on Folded (the old boundary scan re-walked subtrees
-// every level — O(n log n)).  The per-level SUPERPOSITION is byte-identical
-// to the original recursive foldGroup: the same FP additions in the same
-// order.
+// FLAT per-level fold — one loop per level (foldSlice), each group joined by
+// joinFlat with the permute and add FUSED (`gist[d] += v[seat[d]]`, no scratch
+// buffer), and subtree byte lengths carried incrementally on Folded (the old
+// boundary scan re-walked subtrees every level — O(n log n)).  The per-level
+// SUPERPOSITION is byte-identical to the original recursive foldGroup: the
+// same FP additions in the same order.
+//
+// THE SHAPE IS WRITTEN ONCE, OVER A FOLD ALGEBRA.  Which items group under
+// which parent is decided by the cut levels, the keyring and, inside an
+// over-long row, the items' content key — never by what an item IS.  So the
+// grouping (foldSlice, groupByLevel) takes the two things it needs from an
+// item, `join` and `key`, and runs unchanged over the vector fold (perception)
+// and over the identity fold ({@link contentIdentity}), which can therefore
+// never disagree about the tree.
 //
 // LINEAR fold — intermediate gists are NOT normalized; only the final root is
-// (riverFold's single normalize).  This is a deliberate change of similarity
+// (`rootOf`'s single normalize).  This is a deliberate change of similarity
 // semantics from the original per-group normalize, not a cached optimization:
 // the fold is now a pure linear operator — a superposition of positionally-
 // bound leaf vectors — so an interior node carries its span's natural
@@ -233,95 +240,28 @@ export interface Grid {
  *  each extra level applies another seat permutation to the whole gist —
  *  near-identical inputs straddling such a cliff read as orthogonal
  *  (measured: 33-byte-identical prefixes at cos ≈ 0). */
-function foldSlice(
-  space: Space,
-  items: Folded[],
+function foldSlice<T>(
+  alg: FoldAlgebra<T>,
+  mg: number,
+  items: T[],
   start: number,
   count: number,
-  out: Folded[],
+  out: T[],
   force: boolean,
 ): void {
-  const mg = space.maxGroup;
-  const D = space.D;
   const complete = count - (count % mg);
-
-  const foldAt = (at: number, size: number): void => {
-    const gist = new Float32Array(D);
-    const kids = new Array<Sema>(size);
-    let len = 0;
-    for (let k = 0; k < size; k++) {
-      const f = items[at + k];
-      const slot = twoEndedSeat(space.seats.length, size, k);
-      const seat = space.seats[slot].fwd;
-      const v = f.tree.v;
-      // Fused permute-and-accumulate — same FP ops, same order as the old
-      // permuteInto + addInto pair, with no scratch buffer.
-      for (let d = 0; d < D; d++) gist[d] += v[seat[d]];
-      kids[k] = f.tree;
-      len += f.len;
-    }
-    out.push({ tree: sema(gist, null, kids), len });
-  };
-
-  for (let i = 0; i < complete; i += mg) foldAt(start + i, mg);
-
+  for (let i = 0; i < complete; i += mg) {
+    out.push(alg.join(items.slice(start + i, start + i + mg)));
+  }
   const leftover = count - complete;
   if (leftover === 0) return;
-  if (force && leftover >= 2) foldAt(start + complete, leftover);
-  else for (let i = complete; i < count; i++) out.push(items[start + i]);
-}
-
-function riverFold(space: Space, row: Folded[], stableBytes: number): Folded {
-  if (row.length === 0) {
-    const z = new Float32Array(space.D);
-    return { tree: sema(z, new Uint8Array(0), null), len: 0 };
-  }
-  let level = row;
-  while (level.length > 1) {
-    // Find the item index where accumulated bytes reaches stableBytes.
-    let boundary = level.length;
-    if (stableBytes > 0) {
-      let acc = 0;
-      for (let i = 0; i < level.length; i++) {
-        acc += level[i].len;
-        if (acc >= stableBytes) {
-          boundary = i + 1;
-          break;
-        }
-      }
-    }
-
-    const next: Folded[] = [];
-    if (boundary < level.length) {
-      // Prefix folds independently of the suffix — structural stability.
-      foldSlice(space, level, 0, boundary, next, true);
-      foldSlice(space, level, boundary, level.length - boundary, next, true);
-    } else {
-      foldSlice(space, level, 0, level.length, next, true);
-    }
-    level = next;
-  }
-  // LINEAR fold — this root normalize is the ONLY normalize of the entire
-  // fold; every intermediate gist stays unnormalized (see the folding
-  // header).  Skipped for a single-leaf input: that root IS the shared
-  // alphabet vector (already unit), and normalizing in place would mutate the
-  // alphabet itself.
-  if (row.length > 1) normalize(level[0].tree.v);
-  return level[0];
+  if (force && leftover >= 2) {
+    out.push(alg.join(items.slice(start + complete, start + count)));
+  } else for (let i = complete; i < count; i++) out.push(items[start + i]);
 }
 
 // ---- public API ----
 
-function bytesToLeaves(
-  alphabet: Alphabet,
-  bytes: Uint8Array,
-): Folded[] {
-  return Array.from(bytes, (b, i) => {
-    const v = alphabet.vecs[b];
-    return { tree: sema(v, bytes.slice(i, i + 1), null), len: 1 };
-  });
-}
-
 /** CONTENT-DEFINED FOLD BOUNDARIES — where a byte stream segments, chosen by
  *  the bytes rather than by arithmetic.
  *
@@ -384,47 +324,11 @@ function bytesToLeaves(
  *  Levels are read from the hash the cut was ACCEPTED at, not recomputed, so
  *  they cost nothing beyond the divisions already being done. */
 
-// Cyclic-polynomial table for the bounded-window cut hash.  Derived once from
-// the fold's own mixing constant — no seed, no tuning.  A byte contributes
-// BUZ[b] on entering the window; the hash rotates by one per byte, so by the
-// time that byte leaves, its contribution has travelled k places and is
-// removed rotated by k.  The rotation is taken at the use site rather than
-// precomputed into a second table so the window width follows maxGroup
-// instead of being frozen at one value.
-const BUZ = new Uint32Array(256);
-{
-  let x = 0x9e3779b9 >>> 0;
-  for (let i = 0; i < 256; i++) {
-    x = Math.imul(x ^ (x >>> 15), 2654435761) >>> 0;
-    x = (x ^ (x >>> 13)) >>> 0;
-    BUZ[i] = x;
-  }
-}
-
-/** BUZ rotated by the window width — what a byte's contribution has become by
- *  the time it leaves.  Cached because the width follows `maxGroup`, which is
- *  fixed for a given space: built once, then a plain table lookup per byte. */
-let buzOutTable: Uint32Array | null = null;
-let buzOutWidth = -1;
-function buzOut(k: number): Uint32Array {
-  if (buzOutWidth !== k || buzOutTable === null) {
-    const t = new Uint32Array(256);
-    for (let i = 0; i < 256; i++) {
-      const v = BUZ[i];
-      t[i] = ((v << k) | (v >>> (32 - k))) >>> 0;
-    }
-    buzOutTable = t;
-    buzOutWidth = k;
-  }
-  return buzOutTable;
-}
-
 function contentLevels(
   space: Space,
   bytes: Uint8Array,
 ): { cuts: number[]; levels: number[] } {
   const W = space.maxGroup;
-  const minLen = W - 1;
   const maxLen = space.seats.length;
   // MEASURED AND REFUTED — making E[segment] equal W.  A segment is at least
   // `minLen` bytes and then cuts with probability p, so E[len] = minLen +
@@ -500,21 +404,20 @@ function contentLevels(
   //   old       0.870   0.902   0.492   0.879    0.888  0.441
   //   this      0.935   0.952   0.732   0.920    0.916  0.935
   //
-  // The cyclic polynomial (each byte enters as a table value, leaves rotated
-  // by the window width) has EXACTLY k bytes of memory and scrambles periodic
-  // input, so the threshold fires at content-chosen positions on a gradient
+  // The register (the last k raw bytes, `h = h << 8 | byte`, mixed by the
+  // two-round avalanche below) has EXACTLY k bytes of memory and scrambles
+  // periodic input, so the threshold fires at content-chosen positions on a gradient
   // just as it does on text — which is what leaves the `maxLen` fallback
   // rarely engaged instead of carrying the phase.  Segment lengths are
   // unchanged in distribution (mean 5.2-7.2 against the old 5.4-6.0), so the
   // mechanisms fitted to that distribution see the same scale.
   //
-  // Cost is the same shape as before: shifts, XORs and two table lookups per
-  // byte, no multiply and no auxiliary structure.  (An exact sliding-window
+  // Cost per byte: a shift, an OR and the avalanche's two multiplies — no
+  // table and no auxiliary structure.  (An exact sliding-window
   // minimum — winnowing — aligns slightly better still, 0.91-0.999, but its
   // deque costs 51 MB/s against this rule's 112 and buys nothing the
   // scrambling hash does not already give.)
   const k = W;
-  const OUT = buzOut(k);
   const cuts: number[] = [];
   const levels: number[] = [];
   const n = bytes.length;
@@ -716,7 +619,9 @@ function contentFoldSpan(
   for (let i = 0; i + 1 < edges.length; i++) {
     segs.push(flatFold(space, alphabet, span, edges[i], edges[i + 1]));
   }
-  if (segs.length > 1) return groupByLevel(space, segs, levels, 1);
+  if (segs.length > 1) {
+    return groupByLevel(vectorFold(space), space, segs, levels, 1);
+  }
   return segs[0];
 }
 
@@ -763,7 +668,7 @@ export interface ContentFold {
  *  streams.  Verifying the bytes here would cost O(prefix) and defeat the
  *  whole point, so the obligation sits with the caller, and every caller
  *  discharges it structurally rather than by care: `perceiveDeposit` looks the
- *  entry up under `latin1Key(bytes.subarray(0, L))` — the prefix's own bytes
+ *  entry up under `latin1(bytes.subarray(0, L))` — the prefix's own bytes
  *  ARE the cache key — and a conversation's fold state advances only by
  *  append.  A new caller that cannot make the same structural argument must
  *  pass no `prev` at all; the cold path is always correct.
@@ -792,7 +697,7 @@ export function contentFoldIncremental(
     segs.push(hit ?? flatFold(space, alphabet, bytes, edges[i], edges[i + 1]));
   }
   const folded = segs.length > 1
-    ? groupByLevel(space, segs, levels, 1)
+    ? groupByLevel(vectorFold(space), space, segs, levels, 1)
     : segs[0];
   // THE ROOT IS NORMALIZED IN PLACE, A CACHED SEGMENT NEVER IS.  With one
   // segment — or with a grouping that passes a lone item through — `folded`
@@ -826,23 +731,25 @@ export function contentFoldIncremental(
  *  the cut levels are uniformly 0 and carry no signal.  Identical subtrees
  *  fold to identical vectors, so the same items in the same order always
  *  choose the same split — the property the whole fold rests on. */
-function itemKey(v: Vec): number {
+const ITEM_KEY_COORDS = 8;
+function itemKey(v: ArrayLike<number>): number {
   let h = 0x811c9dc5;
-  for (let d = 0; d < 8; d++) {
+  for (let d = 0; d < ITEM_KEY_COORDS; d++) {
     h = Math.imul(h ^ ((v[d] * 8192) | 0), 0x01000193) >>> 0;
   }
   return h >>> 0;
 }
 
-function groupByLevel(
+function groupByLevel<T>(
+  alg: FoldAlgebra<T>,
   space: Space,
-  items: Folded[],
+  items: T[],
   levels: number[],
   level: number,
-): Folded {
+): T {
   if (items.length === 1) return items[0];
   const maxSeats = space.seats.length;
-  const groups: Folded[] = [];
+  const groups: T[] = [];
   const groupLevels: number[] = [];
   // Emit [from, to) as one group, splitting it at its STRONGEST interior cut
   // whenever it would exceed the keyring.
@@ -869,7 +776,7 @@ function groupByLevel(
         // equal — fall back to the ITEMS' own content.  A group's gist is
         // diverse where its cut level is not, so hashing it gives a
         // content-determined split point where the level array has none.
-        const key = itemKey(items[j].tree.v);
+        const key = alg.key(items[j]);
         if (
           levels[j] > bestLevel ||
           (levels[j] === bestLevel && key > bestKey)
@@ -880,12 +787,12 @@ function groupByLevel(
         }
       }
       const part = items.slice(at, best + 1);
-      groups.push(part.length === 1 ? part[0] : joinFlat(space, part));
+      groups.push(part.length === 1 ? part[0] : alg.join(part));
       groupLevels.push(levels[best]);
       at = best + 1;
     }
     const slice = items.slice(at, to);
-    groups.push(slice.length === 1 ? slice[0] : joinFlat(space, slice));
+    groups.push(slice.length === 1 ? slice[0] : alg.join(slice));
   };
   let start = 0;
   for (let i = 0; i <= levels.length; i++) {
@@ -898,10 +805,10 @@ function groupByLevel(
   if (groups.length === items.length) {
     // This level split nothing — climb rather than spin.
     return level < 24
-      ? groupByLevel(space, items, levels, level + 1)
-      : riverFoldRaw(space, items);
+      ? groupByLevel(alg, space, items, levels, level + 1)
+      : riverFold(alg, space, items);
   }
-  return groupByLevel(space, groups, groupLevels, level + 1);
+  return groupByLevel(alg, space, groups, groupLevels, level + 1);
 }
 
 /** Join a row of already-folded items as one unnormalized node — the same
@@ -924,6 +831,123 @@ function joinFlat(space: Space, items: Folded[]): Folded {
   return { tree: sema(gist, null, kids), len };
 }
 
+/** What the fold's SHAPE asks of the items it groups — see the note at the
+ *  top of the folding section.  `join` makes the parent of two or more items,
+ *  children bound in seat order; `key` is {@link itemKey} of the item's raw
+ *  gist, the one place the shape reads an item's content. */
+interface FoldAlgebra<T> {
+  join(items: T[]): T;
+  key(item: T): number;
+}
+
+/** The vector fold — perception's algebra. */
+const vectorFolds = new WeakMap<Space, FoldAlgebra<Folded>>();
+function vectorFold(space: Space): FoldAlgebra<Folded> {
+  let alg = vectorFolds.get(space);
+  if (alg === undefined) {
+    alg = {
+      join: (items) => joinFlat(space, items),
+      key: (item) => itemKey(item.tree.v),
+    };
+    vectorFolds.set(space, alg);
+  }
+  return alg;
+}
+
+/** An item of the identity fold: the node it names (null = names nothing),
+ *  the byte span it covers, and its raw gist read one coordinate at a time, on
+ *  demand. */
+interface IdentityItem {
+  id: number | null;
+  from: number;
+  to: number;
+  coord: (p: number) => number;
+  key?: number;
+}
+
+/** The raw gist coordinate `p` of a node whose children are `kids` — the
+ *  coordinate {@link flatFold}/{@link joinFlat} would have written: the same
+ *  float32 additions, in the same order, from a zero start. */
+function boundCoord(
+  space: Space,
+  n: number,
+  kid: (k: number, at: number) => number,
+  p: number,
+): number {
+  let acc = 0;
+  for (let k = 0; k < n; k++) {
+    const seat = space.seats[twoEndedSeat(space.seats.length, n, k)].fwd;
+    acc = Math.fround(acc + kid(k, seat[p]));
+  }
+  return acc;
+}
+
+/** The node a byte stream's content fold NAMES — `foldTree` over
+ *  {@link contentFoldSpan}'s tree, without building a single vector.
+ *
+ *  A fold names a node only when every child is named, so identity needs the
+ *  tree's SHAPE and the store's answer for each node — and the shape is a
+ *  function of the bytes (cuts and levels) plus, inside an over-long row, each
+ *  item's {@link itemKey}: eight coordinates of its raw gist.  Those are read
+ *  lazily through {@link boundCoord}, bit-identical to the coordinates the
+ *  vector fold computes, so the grouping (the SAME {@link groupByLevel}) cannot
+ *  differ.  `segment(from, to)` names a level-0 segment (one flat node over
+ *  single-byte atoms, or the atom itself); `branch(kids, from, to)` names the
+ *  group covering [from, to) — `kids` holds null for an unnamed child, because
+ *  the store names a branch by its BYTES when its children do not name it
+ *  (the write side's step 1b, store.ts `intern`), so an unnamed child does not
+ *  settle its ancestors.  Every item's grouping key is read from its content,
+ *  named or not, for the same reason.  An empty stream is the caller's: its
+ *  fold is the alphabet's zero-byte leaf, not a segment. */
+export function contentIdentity(
+  space: Space,
+  alphabet: Alphabet,
+  bytes: Uint8Array,
+  segment: (from: number, to: number) => number | null,
+  branch: (
+    kids: ReadonlyArray<number | null>,
+    from: number,
+    to: number,
+  ) => number | null,
+): number | null {
+  const { cuts, levels } = contentLevels(space, bytes);
+  const edges = [0, ...cuts, bytes.length];
+  const segs: IdentityItem[] = [];
+  for (let i = 0; i + 1 < edges.length; i++) {
+    const from = edges[i], n = edges[i + 1] - from;
+    segs.push({
+      id: segment(from, edges[i + 1]),
+      from,
+      to: edges[i + 1],
+      coord: n === 1 ? (p) => alphabet.vecs[bytes[from]][p] : (p) =>
+        boundCoord(
+          space,
+          n,
+          (k, at) => alphabet.vecs[bytes[from + k]][at],
+          p,
+        ),
+    });
+  }
+  if (segs.length === 1) return segs[0].id;
+  const alg: FoldAlgebra<IdentityItem> = {
+    join: (items) => {
+      const from = items[0].from, to = items[items.length - 1].to;
+      return {
+        id: branch(items.map((it) => it.id), from, to),
+        from,
+        to,
+        coord: (p) =>
+          boundCoord(space, items.length, (k, at) => items[k].coord(at), p),
+      };
+    },
+    key: (item) =>
+      item.key ??= itemKey(
+        Array.from({ length: ITEM_KEY_COORDS }, (_, d) => item.coord(d)),
+      ),
+  };
+  return groupByLevel(alg, space, segs, levels, 1).id;
+}
+
 /** One segment as a single unnormalized node: leaf per byte, each bound into
  *  a seat derived from its position relative to BOTH segment ends.
  *
@@ -971,14 +995,6 @@ function flatFold(
   return { tree: sema(gist, null, kids), len: n };
 }
 
-/* * The stable-prefix segmented fold (fold-contract.md).  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). */
 /** A fold's ROOT: ONE normalize per perception, at the root, exactly as
  *  riverFold did — the interior stays raw (the linear-fold contract).
  *
@@ -995,6 +1011,14 @@ function rootOf(f: Folded): Sema {
   return f.tree;
 }
 
+/** The stable-prefix segmented fold (fold-contract.md).  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,
@@ -1113,11 +1137,16 @@ export function riverFoldRaw(space: Space, row: Folded[]): Folded {
     const z = new Float32Array(space.D);
     return { tree: sema(z, new Uint8Array(0), null), len: 0 };
   }
-  if (row.length === 1) return row[0];
+  return riverFold(vectorFold(space), space, row);
+}
+
+/** The river's fixed-arity shape over any fold algebra: groups of maxGroup,
+ *  the trailing partial group forced, level after level to one root. */
+function riverFold<T>(alg: FoldAlgebra<T>, space: Space, row: T[]): T {
   let level = row;
   while (level.length > 1) {
-    const next: Folded[] = [];
-    foldSlice(space, level, 0, level.length, next, true);
+    const next: T[] = [];
+    foldSlice(alg, space.maxGroup, level, 0, level.length, next, true);
     level = next;
   }
   return level[0];