@hviana/sema 0.7.2 → 0.7.3

package/dist/src/store.d.ts

@@ -570,9 +570,6 @@ export declare abstract class AbstractStore implements Store {
     nodeCount(): number;
     size(): Promise<number>;
     get(id: NodeId): NodeRec | null;
-    /** Reconstruct the bytes a node spans by traversing the DAG bottom-up.
-     *  Iterative post-order on an explicit stack — the call stack never sees the
-     *  tree depth, so even an adversarial chain of nodes stays safe. */
     /** How many reads hit a MISSING node record this session (a dangling edge
      *  or kid id).  Zero in a healthy store; a growing count means references
      *  outlive their records — the read degrades safely to empty bytes, this
@@ -582,6 +579,25 @@ export declare abstract class AbstractStore implements Store {
      *  nothing is profiling.  Every read below bumps it through `?.`, so an
      *  unprofiled store pays one null check per read and allocates nothing. */
     meter: Meter | null;
+    /** Reconstruct the bytes a node spans by traversing the DAG bottom-up.
+     *  Iterative post-order on an explicit stack — the call stack never sees the
+     *  tree depth, so even an adversarial chain of nodes stays safe.
+     *
+     *  TERMINATION.  The walk memoizes into a LOCAL map, and `_bytesCache` is
+     *  consulted only as a warm hint whose hit is immediately promoted into that
+     *  map.  It used to use `_bytesCache` itself as the memo, which is not a
+     *  memo at all: it EVICTS, and its `"smallest"` policy prefers precisely the
+     *  freshly-resolved small children that the pending parents on the stack are
+     *  waiting for.  A parent then finds them uncached again, re-pushes them,
+     *  they are re-resolved, re-inserted, re-evicted — the loop makes no
+     *  progress and never exits.  Latent until the cache saturates, then
+     *  unconditional: observed in the wild at 19.9M nodes with the 20 MB cache
+     *  pinned at 19,999,962/20,000,000 bytes, spinning 8h45m on a node whose
+     *  whole content was 124 bytes (5 kids, 2 of them perpetually re-evicted).
+     *  Because the loop is synchronous, no timer could fire — the trainer's stall
+     *  watchdog never got a turn either.  A local map resolves each node at most
+     *  once per call, so the walk terminates by construction and `_bytesCache`
+     *  goes back to being a pure speed hint. */
     bytes(id: NodeId): Uint8Array;
     /** First `maxLen` bytes of a node.  Walks only the leftmost branch,
      *  stopping at `maxLen` — so a 1 MB document root costs the same as a
@@ -665,7 +681,20 @@ export declare abstract class AbstractStore implements Store {
      *  common-prefix / common-suffix trim: whatever remains after both trims is
      *  the single differing span (substitution, insertion or deletion), and both
      *  remainders must fit the budget.  Scattered differences leave a wide
-     *  middle and are rejected. */
+     *  middle and are rejected.
+     *
+     *  Every read here is CAPPED (§2.8).  It used to open with
+     *  `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the
+     *  full materialising `bytes()` read — on the deposit hot path, and only
+     *  then compare lengths.  So a candidate the length test was about to reject
+     *  had already been reconstructed byte for byte.  The LENGTHS decide first
+     *  instead, from the `contentLen` memo the interning order has already built
+     *  bottom-up, and the target's length is itself read under a cap: a target
+     *  longer than `la + W` is rejected without touching one of its bytes.
+     *  Same semantics — the old capped `b` read would have produced
+     *  `a.length + W + 1` here and failed the very same test — strictly fewer
+     *  byte reads.  The `+ 1` on each byte cap keeps `_prefix`'s
+     *  "complete reconstruction" test true, so the results still cache. */
     private differsByOneWindow;
     putLeaf(bytes: Uint8Array, gist: Vec): Promise<NodeId>;
     putBranch(kids: NodeId[], gist: Vec): Promise<NodeId>;

package/dist/src/store.js

@@ -591,9 +591,6 @@ export class AbstractStore {
             this._recCache.set(id, rec);
         return rec;
     }
-    /** Reconstruct the bytes a node spans by traversing the DAG bottom-up.
-     *  Iterative post-order on an explicit stack — the call stack never sees the
-     *  tree depth, so even an adversarial chain of nodes stays safe. */
     /** How many reads hit a MISSING node record this session (a dangling edge
      *  or kid id).  Zero in a healthy store; a growing count means references
      *  outlive their records — the read degrades safely to empty bytes, this
@@ -603,6 +600,25 @@ export class AbstractStore {
      *  nothing is profiling.  Every read below bumps it through `?.`, so an
      *  unprofiled store pays one null check per read and allocates nothing. */
     meter = null;
+    /** Reconstruct the bytes a node spans by traversing the DAG bottom-up.
+     *  Iterative post-order on an explicit stack — the call stack never sees the
+     *  tree depth, so even an adversarial chain of nodes stays safe.
+     *
+     *  TERMINATION.  The walk memoizes into a LOCAL map, and `_bytesCache` is
+     *  consulted only as a warm hint whose hit is immediately promoted into that
+     *  map.  It used to use `_bytesCache` itself as the memo, which is not a
+     *  memo at all: it EVICTS, and its `"smallest"` policy prefers precisely the
+     *  freshly-resolved small children that the pending parents on the stack are
+     *  waiting for.  A parent then finds them uncached again, re-pushes them,
+     *  they are re-resolved, re-inserted, re-evicted — the loop makes no
+     *  progress and never exits.  Latent until the cache saturates, then
+     *  unconditional: observed in the wild at 19.9M nodes with the 20 MB cache
+     *  pinned at 19,999,962/20,000,000 bytes, spinning 8h45m on a node whose
+     *  whole content was 124 bytes (5 kids, 2 of them perpetually re-evicted).
+     *  Because the loop is synchronous, no timer could fire — the trainer's stall
+     *  watchdog never got a turn either.  A local map resolves each node at most
+     *  once per call, so the walk terminates by construction and `_bytesCache`
+     *  goes back to being a pure speed hint. */
     bytes(id) {
         if (this.meter) {
             this.meter.byteReads++;
@@ -619,10 +635,22 @@ export class AbstractStore {
             return hit;
         const stack = [id];
         const cache = this._bytesCache;
+        // The walk's own memo.  Entries are the same shared arrays `_bytesCache`
+        // holds (no extra copy), and it lives exactly as long as this call.
+        const done = new Map();
         while (stack.length > 0) {
             const nid = stack[stack.length - 1]; // peek
-            // Already resolved by an earlier traversal.
-            if (cache.get(nid)) {
+            // Already resolved by this walk — the ONLY authority the readiness test
+            // below trusts, because it cannot be evicted underneath us.
+            if (done.has(nid)) {
+                stack.pop();
+                continue;
+            }
+            // Warm hint: a hit is promoted into `done` in the same step, so from
+            // here on the entry is pinned for the rest of the walk.
+            const warm = cache.get(nid);
+            if (warm !== undefined) {
+                done.set(nid, warm);
                 stack.pop();
                 continue;
             }
@@ -634,21 +662,26 @@ export class AbstractStore {
                 // The cache makes the empty read permanent for the session; the
                 // counter survives as the visible trace.
                 this.danglingReads++;
+                done.set(nid, _ZERO);
                 cache.set(nid, _ZERO);
                 stack.pop();
                 continue;
             }
             if (rec.leaf) {
-                cache.set(nid, new Uint8Array(rec.leaf));
+                // COPY before caching: rec.leaf is the node record's own buffer, and
+                // handing it out would let one mutating caller corrupt the record.
+                const leaf = new Uint8Array(rec.leaf);
+                done.set(nid, leaf);
+                cache.set(nid, leaf);
                 stack.pop();
                 continue;
             }
-            // Branch — push any uncached children (reverse order so they resolve
-            // left-to-right).  If every child is already cached, concatenate now.
+            // Branch — push any unresolved children (reverse order so they resolve
+            // left-to-right).  If every child is resolved, concatenate now.
             const kids = rec.kids ?? [];
             let ready = true;
             for (let i = kids.length - 1; i >= 0; i--) {
-                if (!cache.get(kids[i])) {
+                if (!done.has(kids[i])) {
                     stack.push(kids[i]);
                     ready = false;
                 }
@@ -656,10 +689,11 @@ export class AbstractStore {
             if (!ready)
                 continue;
             stack.pop();
-            const out = concat(kids.map((k) => cache.get(k)));
+            const out = concat(kids.map((k) => done.get(k)));
+            done.set(nid, out);
             cache.set(nid, out);
         }
-        const out = cache.get(id) ?? _ZERO;
+        const out = done.get(id) ?? _ZERO;
         if (this.meter)
             this.meter.bytesRead += out.length;
         return out;
@@ -1189,10 +1223,33 @@ export class AbstractStore {
      *  common-prefix / common-suffix trim: whatever remains after both trims is
      *  the single differing span (substitution, insertion or deletion), and both
      *  remainders must fit the budget.  Scattered differences leave a wide
-     *  middle and are rejected. */
+     *  middle and are rejected.
+     *
+     *  Every read here is CAPPED (§2.8).  It used to open with
+     *  `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the
+     *  full materialising `bytes()` read — on the deposit hot path, and only
+     *  then compare lengths.  So a candidate the length test was about to reject
+     *  had already been reconstructed byte for byte.  The LENGTHS decide first
+     *  instead, from the `contentLen` memo the interning order has already built
+     *  bottom-up, and the target's length is itself read under a cap: a target
+     *  longer than `la + W` is rejected without touching one of its bytes.
+     *  Same semantics — the old capped `b` read would have produced
+     *  `a.length + W + 1` here and failed the very same test — strictly fewer
+     *  byte reads.  The `+ 1` on each byte cap keeps `_prefix`'s
+     *  "complete reconstruction" test true, so the results still cache. */
     differsByOneWindow(kids, targetId, W) {
-        const a = concat(kids.map((k) => this.bytesPrefix(k, Number.MAX_SAFE_INTEGER)));
-        const b = this.bytesPrefix(targetId, a.length + W + 1);
+        const lens = kids.map((k) => this.contentLen(k));
+        let la = 0;
+        for (const n of lens)
+            la += n;
+        const cap = la + W + 1;
+        // `contentLen` under a cap returns a clamped LOWER BOUND once the partial
+        // sum reaches it, so `>= cap` is exactly "longer than la + W".
+        const lb = this.contentLen(targetId, cap);
+        if (lb >= cap || Math.abs(la - lb) > W)
+            return false;
+        const a = concat(kids.map((k, i) => this.bytesPrefix(k, lens[i] + 1)));
+        const b = this.bytesPrefix(targetId, lb + 1);
         if (Math.abs(a.length - b.length) > W)
             return false;
         const n = Math.min(a.length, b.length);

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@hviana/sema",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "exports": "./src/index.ts"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "repository": {
     "type": "git",

package/src/store.ts

@@ -1133,9 +1133,6 @@ export abstract class AbstractStore implements Store {
     return rec;
   }
 
-  /** Reconstruct the bytes a node spans by traversing the DAG bottom-up.
-   *  Iterative post-order on an explicit stack — the call stack never sees the
-   *  tree depth, so even an adversarial chain of nodes stays safe. */
   /** How many reads hit a MISSING node record this session (a dangling edge
    *  or kid id).  Zero in a healthy store; a growing count means references
    *  outlive their records — the read degrades safely to empty bytes, this
@@ -1147,6 +1144,25 @@ export abstract class AbstractStore implements Store {
    *  unprofiled store pays one null check per read and allocates nothing. */
   meter: Meter | null = null;
 
+  /** Reconstruct the bytes a node spans by traversing the DAG bottom-up.
+   *  Iterative post-order on an explicit stack — the call stack never sees the
+   *  tree depth, so even an adversarial chain of nodes stays safe.
+   *
+   *  TERMINATION.  The walk memoizes into a LOCAL map, and `_bytesCache` is
+   *  consulted only as a warm hint whose hit is immediately promoted into that
+   *  map.  It used to use `_bytesCache` itself as the memo, which is not a
+   *  memo at all: it EVICTS, and its `"smallest"` policy prefers precisely the
+   *  freshly-resolved small children that the pending parents on the stack are
+   *  waiting for.  A parent then finds them uncached again, re-pushes them,
+   *  they are re-resolved, re-inserted, re-evicted — the loop makes no
+   *  progress and never exits.  Latent until the cache saturates, then
+   *  unconditional: observed in the wild at 19.9M nodes with the 20 MB cache
+   *  pinned at 19,999,962/20,000,000 bytes, spinning 8h45m on a node whose
+   *  whole content was 124 bytes (5 kids, 2 of them perpetually re-evicted).
+   *  Because the loop is synchronous, no timer could fire — the trainer's stall
+   *  watchdog never got a turn either.  A local map resolves each node at most
+   *  once per call, so the walk terminates by construction and `_bytesCache`
+   *  goes back to being a pure speed hint. */
   bytes(id: NodeId): Uint8Array {
     if (this.meter) {
       this.meter.byteReads++;
@@ -1162,12 +1178,25 @@ export abstract class AbstractStore implements Store {
 
     const stack: NodeId[] = [id];
     const cache = this._bytesCache;
+    // The walk's own memo.  Entries are the same shared arrays `_bytesCache`
+    // holds (no extra copy), and it lives exactly as long as this call.
+    const done = new Map<NodeId, Uint8Array>();
 
     while (stack.length > 0) {
       const nid = stack[stack.length - 1]; // peek
 
-      // Already resolved by an earlier traversal.
-      if (cache.get(nid)) {
+      // Already resolved by this walk — the ONLY authority the readiness test
+      // below trusts, because it cannot be evicted underneath us.
+      if (done.has(nid)) {
+        stack.pop();
+        continue;
+      }
+
+      // Warm hint: a hit is promoted into `done` in the same step, so from
+      // here on the entry is pinned for the rest of the walk.
+      const warm = cache.get(nid);
+      if (warm !== undefined) {
+        done.set(nid, warm);
         stack.pop();
         continue;
       }
@@ -1180,22 +1209,27 @@ export abstract class AbstractStore implements Store {
         // The cache makes the empty read permanent for the session; the
         // counter survives as the visible trace.
         this.danglingReads++;
+        done.set(nid, _ZERO);
         cache.set(nid, _ZERO);
         stack.pop();
         continue;
       }
       if (rec.leaf) {
-        cache.set(nid, new Uint8Array(rec.leaf));
+        // COPY before caching: rec.leaf is the node record's own buffer, and
+        // handing it out would let one mutating caller corrupt the record.
+        const leaf = new Uint8Array(rec.leaf);
+        done.set(nid, leaf);
+        cache.set(nid, leaf);
         stack.pop();
         continue;
       }
 
-      // Branch — push any uncached children (reverse order so they resolve
-      // left-to-right).  If every child is already cached, concatenate now.
+      // Branch — push any unresolved children (reverse order so they resolve
+      // left-to-right).  If every child is resolved, concatenate now.
       const kids = rec.kids ?? [];
       let ready = true;
       for (let i = kids.length - 1; i >= 0; i--) {
-        if (!cache.get(kids[i])) {
+        if (!done.has(kids[i])) {
           stack.push(kids[i]);
           ready = false;
         }
@@ -1203,11 +1237,12 @@ export abstract class AbstractStore implements Store {
       if (!ready) continue;
 
       stack.pop();
-      const out = concat(kids.map((k) => cache.get(k)!));
+      const out = concat(kids.map((k) => done.get(k)!));
+      done.set(nid, out);
       cache.set(nid, out);
     }
 
-    const out = cache.get(id) ?? _ZERO;
+    const out = done.get(id) ?? _ZERO;
     if (this.meter) this.meter.bytesRead += out.length;
     return out;
   }
@@ -1730,16 +1765,35 @@ export abstract class AbstractStore implements Store {
    *  common-prefix / common-suffix trim: whatever remains after both trims is
    *  the single differing span (substitution, insertion or deletion), and both
    *  remainders must fit the budget.  Scattered differences leave a wide
-   *  middle and are rejected. */
+   *  middle and are rejected.
+   *
+   *  Every read here is CAPPED (§2.8).  It used to open with
+   *  `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the
+   *  full materialising `bytes()` read — on the deposit hot path, and only
+   *  then compare lengths.  So a candidate the length test was about to reject
+   *  had already been reconstructed byte for byte.  The LENGTHS decide first
+   *  instead, from the `contentLen` memo the interning order has already built
+   *  bottom-up, and the target's length is itself read under a cap: a target
+   *  longer than `la + W` is rejected without touching one of its bytes.
+   *  Same semantics — the old capped `b` read would have produced
+   *  `a.length + W + 1` here and failed the very same test — strictly fewer
+   *  byte reads.  The `+ 1` on each byte cap keeps `_prefix`'s
+   *  "complete reconstruction" test true, so the results still cache. */
   private differsByOneWindow(
     kids: NodeId[],
     targetId: NodeId,
     W: number,
   ): boolean {
-    const a = concat(
-      kids.map((k) => this.bytesPrefix(k, Number.MAX_SAFE_INTEGER)),
-    );
-    const b = this.bytesPrefix(targetId, a.length + W + 1);
+    const lens = kids.map((k) => this.contentLen(k));
+    let la = 0;
+    for (const n of lens) la += n;
+    const cap = la + W + 1;
+    // `contentLen` under a cap returns a clamped LOWER BOUND once the partial
+    // sum reaches it, so `>= cap` is exactly "longer than la + W".
+    const lb = this.contentLen(targetId, cap);
+    if (lb >= cap || Math.abs(la - lb) > W) return false;
+    const a = concat(kids.map((k, i) => this.bytesPrefix(k, lens[i] + 1)));
+    const b = this.bytesPrefix(targetId, lb + 1);
     if (Math.abs(a.length - b.length) > W) return false;
     const n = Math.min(a.length, b.length);
     let i = 0;

package/test/96-bytes-walk-termination.test.mjs

@@ -0,0 +1,115 @@
+// 96-bytes-walk-termination.test.mjs — `bytes()` must TERMINATE when its
+// traversal memo cannot hold the reconstruction's working set.
+//
+// `bytes()` is an iterative post-order walk: it peeks the top of an explicit
+// stack, pushes any child that is not yet resolved, and concatenates once every
+// child is.  Its termination argument needs a memo that only ever GROWS.  It
+// used `_bytesCache` — a byte-accounted BoundedMap that EVICTS, and whose
+// `"smallest"` policy deliberately prefers the cheapest-to-rebuild entries,
+// i.e. exactly the small, freshly-resolved children the parents still sitting
+// on the stack are waiting for.  The parent finds them unresolved again,
+// re-pushes them, they are re-resolved, re-inserted and re-evicted.  No
+// progress.  The loop never exits.
+//
+// It stayed hidden because it needs the cache to be SATURATED, which only a
+// long run reaches.  OBSERVED IN THE FIELD: a training run at 19.9M nodes with
+// the 20 MB cache pinned at 19,999,962 bytes spun for 8h45m of 100% CPU on one
+// node — whose entire content was 124 bytes, with 5 kids, 2 of them
+// perpetually re-evicted.  Sampled 45s apart through the V8 inspector, the
+// walk's root id, the node's length and the cache's byte count were all
+// identical; only the stack depth oscillated between 1 and 2.
+//
+// And the loop is SYNCHRONOUS, so nothing could observe it: the trainer's
+// 15-minute stall watchdog is a timer, and a timer cannot fire while the
+// microtask/JS stack is occupied.  The run looked alive for 9 hours.
+//
+// The fix makes the walk memoize into a LOCAL map (`_bytesCache` demoted to a
+// warm hint whose hit is promoted into that map immediately), so each node
+// resolves at most once per call and termination is structural.
+//
+// This test does NOT depend on the eviction cursor's position — the field case
+// reached the defect stochastically, via the cursor sweeping the map's
+// recently-inserted tail.  Here the subtree's children simply sum to more bytes
+// than the ceiling, so no cursor position can save it: pre-fix this file hangs
+// forever, and `node --test` reports it only as a timeout.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const D = 64;
+const gist = () => {
+  const v = new Float32Array(D);
+  v[0] = 1;
+  return v;
+};
+
+test("bytes() terminates when its memo cannot hold the working set", async () => {
+  // A ceiling small enough to saturate in milliseconds.  The mechanism is
+  // scale-free: this is the only thing scaled down from the field case.
+  const CEILING = 4096;
+  const store = new SQliteStore({
+    D,
+    bytesCacheMax: CEILING,
+    path: ":memory:",
+  });
+
+  // One ordinary 9,600-byte form: 300 distinct 32-byte children under a root.
+  const KIDS = 300, WIDTH = 32;
+  const kids = [];
+  for (let b = 0; b < KIDS; b++) {
+    const buf = new Uint8Array(WIDTH);
+    for (let i = 0; i < WIDTH; i++) buf[i] = (b * 131 + i * 17) & 0xff;
+    kids.push(await store.putLeaf(buf, gist()));
+  }
+  const root = await store.putBranch(kids, gist());
+  const expected = store.contentLen(root);
+  assert.equal(expected, KIDS * WIDTH);
+
+  // Churn the subtree out of the memo and leave it AT its ceiling — the steady
+  // state every long run reaches.
+  for (let k = 0; k < 4000; k++) {
+    const buf = new Uint8Array(48);
+    for (let i = 0; i < 48; i++) buf[i] = (k * 7919 + i * 251) & 0xff;
+    await store.putLeaf(buf, gist());
+  }
+
+  // The premise the guard rests on: the memo genuinely cannot hold the working
+  // set.  If a future change grows the ceiling or shrinks the fixture, this
+  // assertion fails LOUDLY rather than letting the test pass vacuously.
+  assert.ok(
+    KIDS * WIDTH > CEILING,
+    `fixture must exceed the memo ceiling (${KIDS * WIDTH} vs ${CEILING})`,
+  );
+
+  // Pre-fix this call never returns.  Post-fix it is sub-millisecond.
+  const out = store.bytes(root);
+  assert.equal(out.length, expected);
+  for (let b = 0; b < KIDS; b++) {
+    for (let i = 0; i < WIDTH; i++) {
+      assert.equal(out[b * WIDTH + i], (b * 131 + i * 17) & 0xff);
+    }
+  }
+});
+
+test("differsByOneWindow's reads are capped — no ALL-sentinel read on deposit", async () => {
+  // §2.8: the near-dedup byte check used to open with
+  // `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, which routes
+  // to the full materialising `bytes()` — and only THEN compare lengths.  A
+  // candidate the length test was about to reject had already been rebuilt byte
+  // for byte, and that read is what dragged the deposit path into the walk
+  // above.  Lengths now decide first, from the `contentLen` memo.
+  const src = await import("node:fs").then((fs) =>
+    fs.readFileSync(new URL("../src/store.ts", import.meta.url), "utf8")
+  );
+  const body = src.slice(src.indexOf("private differsByOneWindow"));
+  const end = body.indexOf("\n  }\n");
+  const fn = body.slice(0, end);
+  assert.ok(
+    !fn.includes("MAX_SAFE_INTEGER"),
+    "differsByOneWindow must not read with the ALL sentinel",
+  );
+  assert.ok(
+    fn.includes("this.contentLen("),
+    "differsByOneWindow must decide on lengths before reading bytes",
+  );
+});