@hviana/sema 0.1.5 → 0.1.7

package/dist/src/vec.d.ts

@@ -14,21 +14,17 @@ export declare function normalize(v: Vec): Vec;
 export declare function cosine(a: Vec, b: Vec): number;
 /** Set vector epsilon thresholds. Called once by Mind at construction. */
 export declare function setVecConfig(cfg: {
-  normalizeEpsilon?: number;
-  cosineEpsilon?: number;
+    normalizeEpsilon?: number;
+    cosineEpsilon?: number;
 }): void;
 export interface Permutation {
-  fwd: Uint32Array;
-  inv: Uint32Array;
+    fwd: Uint32Array;
+    inv: Uint32Array;
 }
 /** The keyring: one independent permutation per seat.
  *  Independent keys do not commute, so an address in a tree is the
  *  path itself — "seat 2 inside seat 1" ≠ "seat 1 inside seat 2". */
-export declare function makeKeyring(
-  D: number,
-  seats: number,
-  rand: () => number,
-): Permutation[];
+export declare function makeKeyring(D: number, seats: number, rand: () => number): Permutation[];
 /** Apply permutation: out[i] = v[table[i]]. */
 export declare function permute(v: Vec, table: Uint32Array): Vec;
 /** Permute into existing buffer — zero allocation. */

package/dist/src/vec.js

@@ -4,49 +4,44 @@
 // No weights. No gradients.
 /** Deterministic PRNG (32-bit mixer). */
 export function rng(seed) {
-  let s = seed >>> 0;
-  return () => {
-    s = (s + 0x6d2b79f5) >>> 0;
-    let t = s;
-    t = Math.imul(t ^ (t >>> 15), t | 1);
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
+    let s = seed >>> 0;
+    return () => {
+        s = (s + 0x6d2b79f5) >>> 0;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
 }
 /** Standard normal sample (Box–Muller). */
 function gaussian(rand) {
-  let u = 0, v = 0;
-  while (u === 0) {
-    u = rand();
-  }
-  while (v === 0) {
-    v = rand();
-  }
-  return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+    let u = 0, v = 0;
+    while (u === 0)
+        u = rand();
+    while (v === 0)
+        v = rand();
+    return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
 }
 export const zeros = (D) => new Float32Array(D);
 export const copy = (v) => new Float32Array(v);
 /** Random point on the unit sphere. */
 export function randomUnit(D, rand) {
-  const v = zeros(D);
-  for (let i = 0; i < D; i++) {
-    v[i] = gaussian(rand);
-  }
-  return normalize(v);
+    const v = zeros(D);
+    for (let i = 0; i < D; i++)
+        v[i] = gaussian(rand);
+    return normalize(v);
 }
 /** target += src * scale (in place). */
 export function addInto(target, src, scale = 1) {
-  for (let i = 0; i < target.length; i++) {
-    target[i] += src[i] * scale;
-  }
-  return target;
+    for (let i = 0; i < target.length; i++)
+        target[i] += src[i] * scale;
+    return target;
 }
 export function dot(a, b) {
-  let s = 0;
-  for (let i = 0; i < a.length; i++) {
-    s += a[i] * b[i];
-  }
-  return s;
+    let s = 0;
+    for (let i = 0; i < a.length; i++)
+        s += a[i] * b[i];
+    return s;
 }
 const norm = (v) => Math.sqrt(dot(v, v));
 // Epsilon thresholds (settable once via setVecConfig).
@@ -54,68 +49,61 @@ let _normalizeEpsilon = 1e-12;
 let _cosineEpsilon = 1e-12;
 /** In-place normalization. */
 export function normalize(v) {
-  const n = norm(v);
-  if (n > _normalizeEpsilon) {
-    for (let i = 0; i < v.length; i++) {
-      v[i] /= n;
+    const n = norm(v);
+    if (n > _normalizeEpsilon) {
+        for (let i = 0; i < v.length; i++)
+            v[i] /= n;
     }
-  }
-  return v;
+    return v;
 }
 /** Resonance: 1 = same, 0 = unrelated. */
 export function cosine(a, b) {
-  const na = norm(a), nb = norm(b);
-  return na > _cosineEpsilon && nb > _cosineEpsilon ? dot(a, b) / (na * nb) : 0;
+    const na = norm(a), nb = norm(b);
+    return na > _cosineEpsilon && nb > _cosineEpsilon ? dot(a, b) / (na * nb) : 0;
 }
 /** Set vector epsilon thresholds. Called once by Mind at construction. */
 export function setVecConfig(cfg) {
-  if (cfg.normalizeEpsilon !== undefined) {
-    _normalizeEpsilon = cfg.normalizeEpsilon;
-  }
-  if (cfg.cosineEpsilon !== undefined) {
-    _cosineEpsilon = cfg.cosineEpsilon;
-  }
+    if (cfg.normalizeEpsilon !== undefined) {
+        _normalizeEpsilon = cfg.normalizeEpsilon;
+    }
+    if (cfg.cosineEpsilon !== undefined)
+        _cosineEpsilon = cfg.cosineEpsilon;
 }
 /** One fixed random permutation (Fisher–Yates). */
 function makePermutation(D, rand) {
-  const fwd = new Uint32Array(D);
-  for (let i = 0; i < D; i++) {
-    fwd[i] = i;
-  }
-  for (let i = D - 1; i > 0; i--) {
-    const j = Math.floor(rand() * (i + 1));
-    const t = fwd[i];
-    fwd[i] = fwd[j];
-    fwd[j] = t;
-  }
-  const inv = new Uint32Array(D);
-  for (let i = 0; i < D; i++) {
-    inv[fwd[i]] = i;
-  }
-  return { fwd, inv };
+    const fwd = new Uint32Array(D);
+    for (let i = 0; i < D; i++)
+        fwd[i] = i;
+    for (let i = D - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        const t = fwd[i];
+        fwd[i] = fwd[j];
+        fwd[j] = t;
+    }
+    const inv = new Uint32Array(D);
+    for (let i = 0; i < D; i++)
+        inv[fwd[i]] = i;
+    return { fwd, inv };
 }
 /** The keyring: one independent permutation per seat.
  *  Independent keys do not commute, so an address in a tree is the
  *  path itself — "seat 2 inside seat 1" ≠ "seat 1 inside seat 2". */
 export function makeKeyring(D, seats, rand) {
-  const ring = [];
-  for (let s = 0; s < seats; s++) {
-    ring.push(makePermutation(D, rand));
-  }
-  return ring;
+    const ring = [];
+    for (let s = 0; s < seats; s++)
+        ring.push(makePermutation(D, rand));
+    return ring;
 }
 /** Apply permutation: out[i] = v[table[i]]. */
 export function permute(v, table) {
-  const out = new Float32Array(v.length);
-  for (let i = 0; i < v.length; i++) {
-    out[i] = v[table[i]];
-  }
-  return out;
+    const out = new Float32Array(v.length);
+    for (let i = 0; i < v.length; i++)
+        out[i] = v[table[i]];
+    return out;
 }
 /** Permute into existing buffer — zero allocation. */
 export function permuteInto(out, v, table) {
-  for (let i = 0; i < v.length; i++) {
-    out[i] = v[table[i]];
-  }
-  return out;
+    for (let i = 0; i < v.length; i++)
+        out[i] = v[table[i]];
+    return out;
 }

package/example/train_base.ts

@@ -1610,20 +1610,23 @@ async function saveProgress(store: Store, p: SavedProgress): Promise<void> {
 // ═══════════════════════════════════════════════════════════════════════
 
 async function main(): Promise<void> {
-  // The vector indices' single memory knob (MiB) — sizes both the SQLite page
-  // cache and the decoded-code LRU of each index.  Training is HNSW-insert
-  // bound at scale (profiled at >80% of ingest wall-clock on a 5.5M-vector
-  // store, nearly all of it cache-missing code reads), and inserts walk the
-  // graph, so a cache that covers the indexed codes cuts wall-clock directly
-  // (measured ~1.6× at 1 GB vs 64 MB on a 2M-node store).  1 GB caches ~5.8M
-  // D=1024 codes — the whole content index of a 350 MB-corpus store — and is
-  // the default; override with VECTOR_CACHE_MB (e.g. 256 on a small-RAM
-  // machine, 64 for the library default).
-  const VECTOR_CACHE_MB = Math.max(0, Number(env("VECTOR_CACHE_MB", "1024")));
+  // The vector indices' memory knob (MiB) — each index's SQLite page cache.
+  // The IVF index routes inserts through a RAM-resident pivot table and
+  // appends to chunk blobs, so this cache mostly serves query-time cluster
+  // scans; 256 MiB comfortably covers the probed working set of a trained
+  // store.  Override with VECTOR_CACHE_MB (64 is the library default).
+  const VECTOR_CACHE_MB = Math.max(0, Number(env("VECTOR_CACHE_MB", "256")));
+  // Page cache for the MAIN DAG database (node/kid/edge/contain tables).
+  // Training issues millions of content-addressed point probes per session
+  // against a GB-scale file; the library default (64 MiB) is sized for a
+  // small machine — a training box affords more.  Override with
+  // SQLITE_CACHE_MB.
+  const SQLITE_CACHE_MB = Math.max(0, Number(env("SQLITE_CACHE_MB", "256")));
   const store = new SQliteStore({
     path: DB_PATH,
     D,
     vectorCacheMb: VECTOR_CACHE_MB,
+    sqliteCacheMb: SQLITE_CACHE_MB,
   });
 
   // The store IS the model: memories, progress, and metadata all persist in
@@ -1822,9 +1825,22 @@ async function main(): Promise<void> {
 
   /** Run index maintenance: compact (remove garbage) then repair (fill gaps).
    *  Both are idempotent — running twice produces the same result as once.
-   *  Compaction frees index space first; repair then adds back the bridges
-   *  whose gists were evicted before indexing, completing the coverage that
-   *  incremental bridge promotion alone cannot guarantee.
+   *  Compaction frees index space first; repair then adds back every
+   *  edge/halo-bearing node whose gist was evicted from the pending cache
+   *  before it reached the content index, completing the coverage that
+   *  incremental promotion alone cannot guarantee.
+   *
+   *  repair runs with minParents = 0, NOT the library default of 2.  The
+   *  default repairs only structural BRIDGES (≥2 parents), but this
+   *  trainer's fact deposits also leave answer-side DEPOSIT ROOTS with 0
+   *  structural parents ("The capital of France is Paris." as the dst of a
+   *  Q→A edge is a root of its own tree, contained in nothing).  Those are
+   *  resonance targets recall depends on — a trained store shipped without
+   *  them cannot ground statement-shaped queries against its own answers
+   *  (observed: 33 such roots missing after a full curriculum, including
+   *  high-traffic conversation replies).  minParents = 0 admits every
+   *  edge/halo bearer; the candidate set is still corpus-of-experiences-
+   *  sized, so the pass stays cheap.
    *
    *  Logs the number of entries removed/added so a run that silently degrades
    *  (growing compaction count, or repair never recovering anything) is
@@ -1846,10 +1862,12 @@ async function main(): Promise<void> {
       );
     }
     try {
-      const added = await mind.repairContentIndex();
+      const added = await mind.repairContentIndex(0);
       if (added > 0) {
         progress.log(
-          `  ${GRN}index repair: added ${int(added)} missing bridges${R}`,
+          `  ${GRN}index repair: added ${
+            int(added)
+          } missing resonance targets${R}`,
         );
       }
     } catch (err) {

package/index.html

@@ -52,6 +52,10 @@
         z-index: 0;
         overflow: hidden;
         background: var(--bg);
+        /* own stacking context + GPU layer: keeps the blend-mode orbs from
+           forcing full-page re-rasterization every frame on mobile */
+        isolation: isolate;
+        transform: translateZ(0);
       }
 
       /* — colour weather: two huge drifting orbs + aurora sweep — */
@@ -60,6 +64,7 @@
         border-radius: 50%;
         filter: blur(70px);
         mix-blend-mode: screen;
+        will-change: transform;
       }
       .orb.a {
         width: 75vmax;
@@ -130,6 +135,7 @@
           transparent 360deg
         );
         animation: spin 70s linear infinite;
+        will-change: transform;
       }
       @keyframes spin {
         to {
@@ -158,6 +164,7 @@
         );
         animation: drift 50s linear infinite alternate;
         opacity: 0.8;
+        will-change: transform;
       }
       @keyframes drift {
         to {
@@ -180,10 +187,12 @@
       .layerA {
         animation: sway 30s ease-in-out infinite alternate;
         transform-origin: 50% 50%;
+        will-change: transform;
       }
       .layerB {
         animation: sway 44s ease-in-out infinite alternate-reverse;
         transform-origin: 50% 50%;
+        will-change: transform;
       }
       @keyframes sway {
         from {
@@ -341,6 +350,7 @@
         opacity: 0.5;
         animation: spin 40s linear infinite;
         filter: drop-shadow(0 0 30px rgba(57, 230, 255, 0.3));
+        will-change: transform;
       }
       .hexring::before {
         content: "";
@@ -373,6 +383,7 @@
           transparent 70%
         );
         animation: breath 7s ease-in-out infinite;
+        will-change: transform, opacity;
       }
       @keyframes breath {
         0%, 100% {
@@ -423,6 +434,11 @@
         filter: drop-shadow(0 0 22px rgba(57, 230, 255, 0.35)) drop-shadow(
           0 8px 60px rgba(168, 120, 255, 0.25)
         );
+        /* gradient-clipped text flickers on iOS while its background animates
+           unless the element sits on its own composited layer */
+        -webkit-backface-visibility: hidden;
+        backface-visibility: hidden;
+        transform: translateZ(0);
       }
       @keyframes sheen {
         0%, 100% {
@@ -450,6 +466,7 @@
         color: transparent;
         -webkit-text-stroke: 1px rgba(57, 230, 255, 0.22);
         animation: echo 8s ease-in-out infinite;
+        will-change: transform, opacity;
       }
       @keyframes echo {
         0%, 100% {
@@ -594,6 +611,7 @@
         white-space: nowrap;
         width: max-content;
         animation: scroll 34s linear infinite;
+        will-change: transform;
       }
       .ticker span {
         padding: 0.72em 0;
@@ -652,6 +670,53 @@
         }
       }
 
+      /* ——————————————————— mobile / touch performance ——————————————————
+         Phones can't sustain the per-frame repaint work: SVG dash/scale
+         animations and background-position sheens repaint every frame, and
+         each pass runs through blur/drop-shadow filters. Strip the filters
+         and the repaint-driven animations; keep every compositor-friendly
+         transform/opacity animation so the page stays alive. */
+      @media (max-width: 820px), (pointer: coarse) {
+        .orb {
+          filter: blur(40px);
+        }
+        .aurora {
+          animation: none;
+        }
+        .grain {
+          display: none;
+        }
+        .wire,
+        .wire.v,
+        .wire.m,
+        .wire.g {
+          filter: none;
+          animation: none;
+          stroke-dasharray: none;
+          stroke-width: 1.2;
+          opacity: 0.75;
+        }
+        .layerA,
+        .layerB {
+          animation: none;
+        }
+        .ring {
+          animation-duration: 7s;
+        }
+        .hexring {
+          filter: none;
+        }
+        h1 {
+          animation: up 1s 0.2s cubic-bezier(0.2, 0.7, 0.2, 1) both;
+          background-position: 35% 50%;
+          filter: drop-shadow(0 0 22px rgba(57, 230, 255, 0.35));
+        }
+        .btn.primary {
+          animation: none;
+          background-position: 50% 50%;
+        }
+      }
+
       /* ————————————————————————— reduced motion ———————————————————————— */
       @media (prefers-reduced-motion: reduce) {
         *, *::before, *::after {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "type": "module",
   "main": "dist/src/index.js",

package/src/alu/README.md

@@ -15,7 +15,7 @@ search as authoritative axioms (at `STEP` cost, like a learned edge).
 
 It has no dependency on the rest of the codebase except the pure byte helpers in
 `../bytes.ts`, and is intended to be reused as a self-contained sublibrary in
-the spirit of `derive/` and `rabitq-hnsw/`.
+the spirit of `derive/` and `rabitq-ivf/`.
 
 ## The thesis: one tiny kernel, everything else is a rewrite
 

package/src/alu/src/index.ts

@@ -1,7 +1,7 @@
 // alu — the ALU sub-library: a tiny irreducible kernel from which arithmetic,
 // logic, and numerical computation are all DERIVED.
 //
-// Self-contained in the spirit of derive/ and rabitq-hnsw/: it imports only the
+// Self-contained in the spirit of derive/ and rabitq-ivf/: it imports only the
 // pure byte helpers (../../bytes.js) and nothing else from SEMA.  The host
 // reaches meaning (operator synonymy, the symbolic inverse) through the injected
 // AluResonance, pre-resolved into a synchronous snapshot before the search runs.

package/src/config.ts

@@ -39,18 +39,9 @@ export interface AlphabetConfig {
 
 export interface StoreConfig {
   minHaloMass: number;
-  m: number;
-  efConstruction: number;
-  /** Construction budget for REACH-ONLY interior gists — the ~90% of content
-   *  index inserts that exist so a partial query can resonate a sub-region
-   *  and climb, never as dedup targets.  Deposit roots and halo-bearing
-   *  targets always build with the full `efConstruction`.  A smaller budget
-   *  here is the one deliberate speed-for-quality trade in ingestion (an
-   *  interior's layer-0 wiring is built from a narrower candidate beam);
-   *  the recall suite (partial recall, multi-topic attention, counterfactual
-   *  anchoring) is the gate for its value.  Set equal to `efConstruction`
-   *  to disable the trade. */
-  efConstructionInterior: number;
+  /** Query breadth of the IVF vector indices: clusters probed per query =
+   *  ceil(efSearch / 4).  Inserts have no quality knob — the partitioned
+   *  index routes and appends, so ingestion cost is flat by construction. */
   efSearch: number;
   /** Compact the in-memory vector indices after this many vectors are written.
    *  Compaction rebuilds an index from its live codes to reclaim the slots left
@@ -58,7 +49,7 @@ export interface StoreConfig {
    *  (not on a flush count that goes quiet during repeat-heavy training) keeps
    *  the index dense and query cost bounded. */
   compactEveryNWrites: number;
-  /** Over-fetch factor for HNSW queries (ANN recall cushion). */
+  /** Over-fetch factor for vector-index queries (ANN recall cushion). */
   overfetch: number;
   /** Combined buffered-write ceiling before a flush of both vector indices
    *  (content + halo). Higher ⇒ fewer, larger flushes into the in-memory
@@ -91,14 +82,20 @@ export interface StoreConfig {
    *  round-trips through the quantizer. An eviction or a reopen reads the
    *  2-bit row — the fidelity every cross-session consumer already gets. */
   haloCacheBytes: number;
-  /** Size, in MiB, of each `rabitq-hnsw` `VectorDatabase`'s memory budget
-   *  (forwarded as its `cacheSizeMb`).  It is the index's SINGLE memory knob: it
-   *  sizes both SQLite's page cache and the derived immutable-code LRU.  A PURE
-   *  latency optimisation — the index reads codes from SQLite on demand, so its
-   *  correctness and its asymptotic per-operation storage-read count are identical
-   *  with the budget at 0.  Exposed so a scaling test can set it to 0 and measure
+  /** Size, in MiB, of each `rabitq-ivf` `VectorDatabase`'s memory budget
+   *  (forwarded as its `cacheSizeMb` — its SQLite page cache).  A PURE latency
+   *  optimisation — the index reads chunk blobs from SQLite on demand, so its
+   *  correctness and its per-operation storage-read count are identical with
+   *  the budget at 0.  Exposed so a scaling test can set it to 0 and measure
    *  the honest, cache-independent cost. */
   vectorCacheMb: number;
+  /** Size, in MiB, of the MAIN DAG database's SQLite page cache.  The node /
+   *  kid / edge / contain tables serve millions of point probes per training
+   *  session (content-addressed findLeaf/findBranch, parent probes, contain
+   *  appends); SQLite's default cache (~2 MiB) thrashes once the DB outgrows
+   *  it, so every probe pays a file read.  A PURE latency knob — correctness
+   *  and result identical at any value. */
+  sqliteCacheMb: number;
   /** Max entries in the skipped-interior LRU set.  Interiors that
    *  {@link Store.indexSubtree} has already visited (indexed or skipped) are
    *  remembered here so subsequent calls prune their subtrees.  Session-local
@@ -151,9 +148,6 @@ export const DEFAULT_CONFIG: MindConfig = {
   },
   store: {
     minHaloMass: 1,
-    m: 8,
-    efConstruction: 64,
-    efConstructionInterior: 16,
     efSearch: 64,
     compactEveryNWrites: 50_000,
     overfetch: 4,
@@ -165,6 +159,7 @@ export const DEFAULT_CONFIG: MindConfig = {
     pendingGistBytes: 16_000_000,
     haloCacheBytes: 16_000_000,
     vectorCacheMb: 64,
+    sqliteCacheMb: 64,
     coveredIdsMax: 100_000,
     chainCacheBytes: 16_000_000,
   },
@@ -194,11 +189,6 @@ export function resolveConfig(opts: Partial<MindConfig> = {}): MindConfig {
     },
     store: {
       minHaloMass: opts.store?.minHaloMass ?? DEFAULT_CONFIG.store.minHaloMass,
-      m: opts.store?.m ?? DEFAULT_CONFIG.store.m,
-      efConstruction: opts.store?.efConstruction ??
-        DEFAULT_CONFIG.store.efConstruction,
-      efConstructionInterior: opts.store?.efConstructionInterior ??
-        DEFAULT_CONFIG.store.efConstructionInterior,
       efSearch: opts.store?.efSearch ?? DEFAULT_CONFIG.store.efSearch,
       compactEveryNWrites: opts.store?.compactEveryNWrites ??
         DEFAULT_CONFIG.store.compactEveryNWrites,
@@ -218,6 +208,8 @@ export function resolveConfig(opts: Partial<MindConfig> = {}): MindConfig {
         DEFAULT_CONFIG.store.haloCacheBytes,
       vectorCacheMb: opts.store?.vectorCacheMb ??
         DEFAULT_CONFIG.store.vectorCacheMb,
+      sqliteCacheMb: opts.store?.sqliteCacheMb ??
+        DEFAULT_CONFIG.store.sqliteCacheMb,
       coveredIdsMax: opts.store?.coveredIdsMax ??
         DEFAULT_CONFIG.store.coveredIdsMax,
       chainCacheBytes: opts.store?.chainCacheBytes ??

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