@hviana/sema 0.7.1 → 0.7.3

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",
+  );
+});