@hviana/sema 0.4.4 → 0.4.7

package/dist/src/store.d.ts

@@ -41,14 +41,65 @@ export declare class BoundedMap<K, V> {
     readonly maxBytes: number;
     private readonly sizeOf;
     private readonly evict;
+    /** How a HIT records recency.
+     *
+     *  `"reorder"` (default) promotes the entry to most-recent by
+     *  `m.delete(k); m.set(k, v)` — exact LRU, and the only policy that is
+     *  safe for a cache whose CONTENTS are load-bearing rather than merely
+     *  warm.  `_depositTrees` (8 entries, feeds stablePrefixFoldIncremental)
+     *  is exactly that: which of its entries survives changes how the next
+     *  turn FOLDS, so test/13 D1 flips answer when the victim changes.
+     *
+     *  `"clock"` records recency as a BIT instead of as position, spent by
+     *  the eviction sweep (see `nextOldest`).  Correct only for a TRANSPARENT
+     *  cache — one where evicting the wrong entry costs a re-read and nothing
+     *  else.  Opt in deliberately, per cache. */
+    private readonly recency;
     private m;
     private _bytes;
     private _cursor;
     private _candidates;
-    constructor(maxBytes: number, sizeOf?: (v: V) => number, evict?: Evict);
+    private _used;
+    constructor(maxBytes: number, sizeOf?: (v: V) => number, evict?: Evict, 
+    /** How a HIT records recency.
+     *
+     *  `"reorder"` (default) promotes the entry to most-recent by
+     *  `m.delete(k); m.set(k, v)` — exact LRU, and the only policy that is
+     *  safe for a cache whose CONTENTS are load-bearing rather than merely
+     *  warm.  `_depositTrees` (8 entries, feeds stablePrefixFoldIncremental)
+     *  is exactly that: which of its entries survives changes how the next
+     *  turn FOLDS, so test/13 D1 flips answer when the victim changes.
+     *
+     *  `"clock"` records recency as a BIT instead of as position, spent by
+     *  the eviction sweep (see `nextOldest`).  Correct only for a TRANSPARENT
+     *  cache — one where evicting the wrong entry costs a re-read and nothing
+     *  else.  Opt in deliberately, per cache. */
+    recency?: "reorder" | "clock");
     /** Next key in insertion (≈ LRU) order, resuming where the last call left
      *  off; wraps to the front when exhausted. Undefined only when empty. */
     private nextOldest;
+    /** RECENCY WITHOUT MUTATING THE MAP (clock policy only).
+     *
+     *  The default `"reorder"` policy below is the textbook JS LRU
+     *  (`m.delete(k); m.set(k, v)`), and on the read path that idiom was
+     *  measured as the single largest CPU consumer in inference: 55% of
+     *  profiled self time, 14.6s of a 26.4s battery, over 6.4M gets — 5.3M of
+     *  them on `_bytesCache` alone at an 83% hit rate.  Every hit deletes and
+     *  reinserts a live key, and each delete leaves a hole in V8's ordered
+     *  backing store that is compacted only on rehash — the same O(size) cliff
+     *  the eviction cursor above already documents, paid here on the path taken
+     *  orders of magnitude more often.
+     *
+     *  Under `"clock"`, a hit sets a BIT that the eviction sweep spends.
+     *  `Set.add` of a key already present neither inserts nor rehashes, so hot
+     *  keys — the 83% — cost one hash probe and nothing else.  Measured on the
+     *  two transparent store caches, with every counter byte-identical
+     *  (nodeRecords 488,468 / byteReads 62,959 in both arms — the SAME entries
+     *  stayed cached): multi-turn think 11,399ms -> 2,022ms, its crossRegion
+     *  8,833ms -> 771ms; single-turn think 12,977ms -> 6,779ms.
+     *
+     *  It is NOT the default, because it is only sound where eviction costs a
+     *  re-read.  See the `recency` parameter. */
     get(k: K): V | undefined;
     /** Membership without touching LRU order — a pure peek, for callers that only
      *  need "is this key present?" and must not promote it to most-recent. */
@@ -567,6 +618,18 @@ export declare abstract class AbstractStore implements Store {
      *  A no-op when the node is already indexed or its gist is evicted from
      *  the pending cache — a future re-encounter will retry. */
     private promoteBridge;
+    /** Re-index a node under a DIFFERENT gist for the same content.
+     *
+     *  Normally a node's gist is a pure function of its id, so indexGist skips
+     *  anything already indexed.  Step 1b of {@link intern} breaks that: it
+     *  reuses an id for the same BYTES folded a different way, and the two
+     *  foldings have different gists.  The index holds one vector per id, so
+     *  the node must carry the gist a direct query of those bytes will present
+     *  — otherwise it is unreachable from exactly the query that names it.
+     *
+     *  A no-op when the gists agree, so the ordinary path pays one comparison
+     *  and nothing else. */
+    private recaptureGist;
     private intern;
     /** Whether the byte content under `kids` and the byte content of `targetId`
      *  are identical except for ONE local span of at most `W` bytes on each side

package/dist/src/store.js

@@ -74,6 +74,7 @@ export class BoundedMap {
     maxBytes;
     sizeOf;
     evict;
+    recency;
     m = new Map();
     _bytes = 0;
     // Persistent eviction cursor over the Map's insertion order. A fresh
@@ -86,32 +87,87 @@ export class BoundedMap {
     // "smallest" mode: oldest-entry candidates carried between evictions, fed
     // from the cursor, so the LRU window never rescans from the front.
     _candidates = [];
-    constructor(maxBytes, sizeOf = () => 1, evict = "lru") {
+    // SECOND-CHANCE (CLOCK) RECENCY BITS — see `get`.  Populated only under
+    // `recency: "clock"`; the default policy leaves this empty and unread.
+    _used = new Set();
+    constructor(maxBytes, sizeOf = () => 1, evict = "lru", 
+    /** How a HIT records recency.
+     *
+     *  `"reorder"` (default) promotes the entry to most-recent by
+     *  `m.delete(k); m.set(k, v)` — exact LRU, and the only policy that is
+     *  safe for a cache whose CONTENTS are load-bearing rather than merely
+     *  warm.  `_depositTrees` (8 entries, feeds stablePrefixFoldIncremental)
+     *  is exactly that: which of its entries survives changes how the next
+     *  turn FOLDS, so test/13 D1 flips answer when the victim changes.
+     *
+     *  `"clock"` records recency as a BIT instead of as position, spent by
+     *  the eviction sweep (see `nextOldest`).  Correct only for a TRANSPARENT
+     *  cache — one where evicting the wrong entry costs a re-read and nothing
+     *  else.  Opt in deliberately, per cache. */
+    recency = "reorder") {
         this.maxBytes = maxBytes;
         this.sizeOf = sizeOf;
         this.evict = evict;
+        this.recency = recency;
     }
     /** Next key in insertion (≈ LRU) order, resuming where the last call left
      *  off; wraps to the front when exhausted. Undefined only when empty. */
     nextOldest() {
+        // SECOND CHANCE (clock recency only): a key whose bit is set is not a
+        // victim — the bit is CLEARED and the sweep moves on, so it survives this
+        // pass but not the next unless `get` touches it again.  Each skip spends
+        // one bit and bits are only set by hits, so a sweep skips at most `size`
+        // times before finding a victim: amortised O(1), as before.
+        let skips = this.m.size;
         for (let wrapped = false;;) {
             if (this._cursor === null)
                 this._cursor = this.m.keys();
             const n = this._cursor.next();
-            if (!n.done)
+            if (!n.done) {
+                if (this._used.size > 0 && this._used.has(n.value) && skips-- > 0) {
+                    this._used.delete(n.value);
+                    continue;
+                }
                 return n.value;
+            }
             this._cursor = null;
             if (this.m.size === 0 || wrapped)
                 return undefined;
             wrapped = true;
         }
     }
+    /** RECENCY WITHOUT MUTATING THE MAP (clock policy only).
+     *
+     *  The default `"reorder"` policy below is the textbook JS LRU
+     *  (`m.delete(k); m.set(k, v)`), and on the read path that idiom was
+     *  measured as the single largest CPU consumer in inference: 55% of
+     *  profiled self time, 14.6s of a 26.4s battery, over 6.4M gets — 5.3M of
+     *  them on `_bytesCache` alone at an 83% hit rate.  Every hit deletes and
+     *  reinserts a live key, and each delete leaves a hole in V8's ordered
+     *  backing store that is compacted only on rehash — the same O(size) cliff
+     *  the eviction cursor above already documents, paid here on the path taken
+     *  orders of magnitude more often.
+     *
+     *  Under `"clock"`, a hit sets a BIT that the eviction sweep spends.
+     *  `Set.add` of a key already present neither inserts nor rehashes, so hot
+     *  keys — the 83% — cost one hash probe and nothing else.  Measured on the
+     *  two transparent store caches, with every counter byte-identical
+     *  (nodeRecords 488,468 / byteReads 62,959 in both arms — the SAME entries
+     *  stayed cached): multi-turn think 11,399ms -> 2,022ms, its crossRegion
+     *  8,833ms -> 771ms; single-turn think 12,977ms -> 6,779ms.
+     *
+     *  It is NOT the default, because it is only sound where eviction costs a
+     *  re-read.  See the `recency` parameter. */
     get(k) {
         const v = this.m.get(k);
-        if (v !== undefined) {
-            this.m.delete(k);
-            this.m.set(k, v);
+        if (v === undefined)
+            return v;
+        if (this.recency === "clock") {
+            this._used.add(k);
+            return v;
         }
+        this.m.delete(k);
+        this.m.set(k, v);
         return v;
     }
     /** Membership without touching LRU order — a pure peek, for callers that only
@@ -158,6 +214,7 @@ export class BoundedMap {
                 this._candidates.splice(bestI, 1);
                 this._bytes -= bestSz;
                 this.m.delete(bestK);
+                this._used.delete(bestK);
             }
             else {
                 const lru = this.nextOldest();
@@ -168,6 +225,7 @@ export class BoundedMap {
                     continue;
                 this._bytes -= this.sizeOf(lruv);
                 this.m.delete(lru);
+                this._used.delete(lru);
             }
         }
     }
@@ -184,6 +242,7 @@ export class BoundedMap {
             return;
         this._bytes -= this.sizeOf(v);
         this.m.delete(k);
+        this._used.delete(k);
     }
     /** Drop every entry (bulk invalidation) — O(1) amortised via fresh maps. */
     clear() {
@@ -193,6 +252,8 @@ export class BoundedMap {
         this._bytes = 0;
         this._cursor = null;
         this._candidates = [];
+        if (this._used.size > 0)
+            this._used = new Set();
     }
 }
 // ── Serialisation utilities (pure functions, no DB dependency) ───────────
@@ -477,9 +538,9 @@ export class AbstractStore {
         this.compactEveryNWrites = config.compactEveryNWrites;
         this._leafKey = new BoundedMap(config.dedupCacheMax);
         this._branchKey = new BoundedMap(config.dedupCacheMax);
-        this._bytesCache = new BoundedMap(config.bytesCacheMax, (v) => v.byteLength, "smallest");
+        this._bytesCache = new BoundedMap(config.bytesCacheMax, (v) => v.byteLength, "smallest", "clock");
         this._lenCache = new BoundedMap(config.bytesCacheMax, () => 16);
-        this._recCache = new BoundedMap(config.recCacheBytes, (r) => (r.leaf?.byteLength ?? 0) + (r.kids?.length ?? 0) * 4 + 12);
+        this._recCache = new BoundedMap(config.recCacheBytes, (r) => (r.leaf?.byteLength ?? 0) + (r.kids?.length ?? 0) * 4 + 12, "lru", "clock");
         this._pendingGist = new BoundedMap(config.pendingGistBytes, (v) => v.byteLength);
         this._haloExact = new BoundedMap(config.haloCacheBytes, (v) => v.byteLength);
         this._haloNorm = new BoundedMap(config.haloCacheBytes, (v) => v.byteLength);
@@ -894,6 +955,33 @@ export class AbstractStore {
         this.indexGist(id, false);
     }
     // ── Core interning: dedup → near-dedup → mint ──────────────────────────
+    /** Re-index a node under a DIFFERENT gist for the same content.
+     *
+     *  Normally a node's gist is a pure function of its id, so indexGist skips
+     *  anything already indexed.  Step 1b of {@link intern} breaks that: it
+     *  reuses an id for the same BYTES folded a different way, and the two
+     *  foldings have different gists.  The index holds one vector per id, so
+     *  the node must carry the gist a direct query of those bytes will present
+     *  — otherwise it is unreachable from exactly the query that names it.
+     *
+     *  A no-op when the gists agree, so the ordinary path pays one comparison
+     *  and nothing else. */
+    recaptureGist(id, gist) {
+        const v = normalize(copy(gist));
+        const current = this._pendingGist.get(id);
+        // Same direction — the ordinary case, where the bytes folded identically.
+        if (current !== undefined && dot(current, v) >= 1 - 1e-6)
+            return;
+        if (current === undefined && !this._indexedIds.has(id) &&
+            !this._vecContentHas(id)) {
+            this.captureIfUnindexed(id, gist);
+            return;
+        }
+        this._pendingGist.set(id, v);
+        this._indexedIds.set(id, true);
+        this._contentBuffer.push({ id, vector: v });
+        this._bufferedIds.add(id);
+    }
     async intern(leaf, kids, gist) {
         await this._ensureReady();
         // 1. Exact dedup — equal content → one id, no vector work. Primary
@@ -919,7 +1007,18 @@ export class AbstractStore {
             if (leafIds !== null) {
                 const flatHit = this.findBranch(leafIds);
                 if (flatHit !== null) {
-                    this.captureIfUnindexed(flatHit, gist);
+                    // The id is reused — same bytes, same node, as documented above.
+                    // But the GIST is not a pure function of the id here, which is the
+                    // assumption indexGist makes: these bytes fold one way standing
+                    // alone and another way embedded, because any bounded-memory cut
+                    // rule sees no context before a stream's first bytes.  Whichever
+                    // folding arrived first owned the index entry, and a query naming
+                    // exactly these bytes — which perceives the STANDALONE folding —
+                    // could not reach the node at all (test/02: express returned
+                    // nothing for a node whose bytes were right there).  Re-index with
+                    // the incoming gist, which is the standalone perception and so the
+                    // one a direct query will present.
+                    this.recaptureGist(flatHit, gist);
                     return flatHit;
                 }
             }

package/index.html

@@ -913,7 +913,7 @@
         <div class="cta">
           <a class="btn primary" href="https://github.com/hviana/sema"
           >View on GitHub</a>
-          <a class="btn ghost" href="mailto:rogernact@gmail.com">Contact</a>
+          <a class="btn ghost" href="mailto:reis.marcelo@gmail.com">Contact</a>
         </div>
       </div>
     </main>
@@ -942,8 +942,7 @@
       </div>
       <div>
         commercial licensing:
-        <a href="mailto:reis.marcelo@gmail.com">reis.marcelo@gmail.com</a> ·
-        <a href="mailto:rogernact@gmail.com">rogernact@gmail.com</a>
+        <a href="mailto:reis.marcelo@gmail.com">reis.marcelo@gmail.com</a>
       </div>
       <div class="lic">
         Released under the

package/package.json

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