@hviana/sema 0.2.9 → 0.4.0

package/dist/src/store.js

@@ -516,6 +516,8 @@ export class AbstractStore {
     }
     // ── DAG traversal ──────────────────────────────────────────────────────
     get(id) {
+        if (this.meter)
+            this.meter.nodeRecords++;
         // Byte leaves are implicit — fabricate from the id.
         if (id < 0) {
             return { id, leaf: new Uint8Array([-(id + 1)]), kids: null };
@@ -536,7 +538,20 @@ export class AbstractStore {
      *  outlive their records — the read degrades safely to empty bytes, this
      *  counter is what keeps that degradation observable. */
     danglingReads = 0;
+    /** {@link Store.meter} — the per-response work accumulator, or null when
+     *  nothing is profiling.  Every read below bumps it through `?.`, so an
+     *  unprofiled store pays one null check per read and allocates nothing. */
+    meter = null;
     bytes(id) {
+        if (this.meter) {
+            this.meter.byteReads++;
+            // Charged BEFORE the fast path returns, and from the cache entry when
+            // there is one: the volume a caller pulled through is the cost signal
+            // (an unbounded read is unbounded whether or not it was cached).
+            const c = this._bytesCache.get(id);
+            if (c)
+                this.meter.bytesRead += c.length;
+        }
         // Fast path.
         const hit = this._bytesCache.get(id);
         if (hit)
@@ -583,7 +598,10 @@ export class AbstractStore {
             const out = concat(kids.map((k) => cache.get(k)));
             cache.set(nid, out);
         }
-        return cache.get(id) ?? _ZERO;
+        const out = cache.get(id) ?? _ZERO;
+        if (this.meter)
+            this.meter.bytesRead += out.length;
+        return out;
     }
     /** 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
@@ -593,8 +611,6 @@ export class AbstractStore {
      *  may be shared with the byte cache and with other callers — treat them
      *  as read-only.  Mutating one would corrupt every subsequent read. */
     bytesPrefix(id, maxLen) {
-        if (maxLen <= 0)
-            return _ZERO;
         // A FULL read (the ALL sentinel) routes through bytes(), whose
         // reconstruction enters the byte-budget cache.  Without this, the mind's
         // read() — which always passes ALL — re-walked the DAG and re-concatenated
@@ -602,6 +618,23 @@ export class AbstractStore {
         // exists precisely for those reconstructions.
         if (maxLen >= 0x7fffffff)
             return this.bytes(id);
+        // METERING BOUNDARY: this public entry point is charged ONCE per logical
+        // read; the walk below recurses through `_prefix`, which is not charged.
+        // Counting the recursion instead made a single read of an N-byte branch
+        // report as N reads (one per node descended), so `byteReads` measured
+        // tree size rather than read requests — it read as ~1 byte per read.
+        if (this.meter)
+            this.meter.byteReads++;
+        const out = this._prefix(id, maxLen);
+        if (this.meter)
+            this.meter.bytesRead += out.length;
+        return out;
+    }
+    /** {@link bytesPrefix}'s recursive body — uncharged; see the metering
+     *  boundary note there. */
+    _prefix(id, maxLen) {
+        if (maxLen <= 0)
+            return _ZERO;
         // Full-cache hit: bytes() already reconstructed the whole node.
         const full = this._bytesCache.get(id);
         if (full)
@@ -625,13 +658,15 @@ export class AbstractStore {
         for (const k of kids) {
             if (got >= maxLen)
                 break;
-            const child = this.bytesPrefix(k, maxLen - got);
+            const child = this._prefix(k, maxLen - got);
             parts.push(child);
             got += child.length;
         }
         return concat(parts);
     }
     contentLen(id, cap = Infinity) {
+        if (this.meter)
+            this.meter.lenReads++;
         if (id < 0)
             return 1; // implicit single-byte leaf
         const hit = this._lenCache.get(id);
@@ -661,6 +696,8 @@ export class AbstractStore {
     }
     // ── Content-addressed lookup ───────────────────────────────────────────
     findLeaf(bytes) {
+        if (this.meter)
+            this.meter.leafLookups++;
         if (bytes.length === 1)
             return -(bytes[0] + 1);
         const key = keyOf(bytes);
@@ -673,6 +710,8 @@ export class AbstractStore {
         return id;
     }
     findBranch(kids) {
+        if (this.meter)
+            this.meter.branchLookups++;
         const key = kids.join(",");
         const cached = this._branchKey.get(key);
         if (cached !== undefined)
@@ -693,15 +732,23 @@ export class AbstractStore {
     }
     // ── Structural parents ─────────────────────────────────────────────────
     parents(id) {
+        if (this.meter)
+            this.meter.parentReads++;
         return this._dbGetParents(id);
     }
     parentsFirst(id, limit) {
+        if (this.meter)
+            this.meter.parentReads++;
         return this._dbGetParentsFirst(id, limit);
     }
     hasParents(id) {
+        if (this.meter)
+            this.meter.parentProbes++;
         return this._dbGetParentsFirst(id, 1).length > 0;
     }
     chainRun(id) {
+        if (this.meter)
+            this.meter.chainRuns++;
         const hit = this._chainMemo.get(id);
         if (hit !== undefined)
             return hit;
@@ -736,12 +783,16 @@ export class AbstractStore {
         set.add(parent);
     }
     hasContainers(child) {
+        if (this.meter)
+            this.meter.containerProbes++;
         if (this._dbContainExists(child))
             return true;
         const buf = this._containBuf.get(child);
         return buf !== undefined && buf.size > 0;
     }
     containersSlice(child, offset, limit) {
+        if (this.meter)
+            this.meter.containerReads++;
         const out = this._dbGetContainParentsSlice(child, offset, limit);
         if (out.length >= limit)
             return out;
@@ -765,6 +816,8 @@ export class AbstractStore {
         return out;
     }
     containers(child) {
+        if (this.meter)
+            this.meter.containerReads++;
         const stored = this._dbGetContainParents(child);
         const buf = this._containBuf.get(child);
         if (stored.length === 0)
@@ -1152,9 +1205,14 @@ export class AbstractStore {
         const cache = this._resonateCache;
         if (cache) {
             const hit = cache.get(rk);
-            if (hit !== undefined)
+            if (hit !== undefined) {
+                if (this.meter)
+                    this.meter.annCacheHits++;
                 return hit;
+            }
         }
+        if (this.meter)
+            this.meter.annQueries++;
         const clusters = this._vecContentClusterCount();
         const results = this._vecContentQuery(normalize(copy(v)), k * this.overfetch, 
         // Exhaustive: probe every cluster (ef ≥ 4·clusters guarantees the
@@ -1169,6 +1227,10 @@ export class AbstractStore {
             if (out.length >= k)
                 break;
         }
+        // Vectors the index actually scored for THIS descent — the counter that
+        // exposes a query whose ANN cost is growing with the corpus.
+        if (this.meter)
+            this.meter.annVectorReads += this._vecContentLastReads();
         const rc = this._resonateCache ??= new Map();
         if (rc.size >= RESONATE_CACHE_MAX)
             rc.clear();
@@ -1390,24 +1452,36 @@ export class AbstractStore {
         this._dbInsertEdge(from, to);
     }
     next(id) {
+        if (this.meter)
+            this.meter.edgeReads++;
         return this._dbGetNextEdges(id);
     }
     /** {@link Store.hasNext} — one indexed point probe, never a range read. */
     hasNext(id) {
+        if (this.meter)
+            this.meter.edgeProbes++;
         return this._dbEdgeSrcExists(id);
     }
     prev(id) {
+        if (this.meter)
+            this.meter.prevReads++;
         return this._dbGetPrevEdges(id);
     }
     nextFirst(id, limit) {
+        if (this.meter)
+            this.meter.edgeReads++;
         return this._dbGetNextEdgesFirst(id, limit);
     }
     prevFirst(id, limit) {
+        if (this.meter)
+            this.meter.prevReads++;
         return this._dbGetPrevEdgesFirst(id, limit);
     }
     /** {@link Store.prevCount}.  Subclasses with an indexed reverse-edge count
      *  should override; this default materialises (correct, not optimal). */
     prevCount(id) {
+        if (this.meter)
+            this.meter.prevProbes++;
         return this._dbGetPrevEdges(id).length;
     }
     edgeSourceCount() {
@@ -1422,10 +1496,14 @@ export class AbstractStore {
     }
     // ── Halos ──────────────────────────────────────────────────────────────
     haloMass(id) {
+        if (this.meter)
+            this.meter.haloProbes++;
         const r = this._dbGetHalo(id);
         return r ? r.mass : 0;
     }
     halo(id) {
+        if (this.meter)
+            this.meter.haloReads++;
         const cached = this._haloNorm.get(id);
         if (cached !== undefined)
             return copy(cached);
@@ -1440,6 +1518,8 @@ export class AbstractStore {
     /** {@link Store.hasHalo} — MUST mirror {@link halo}'s null condition
      *  exactly (row present AND mass ≥ minHaloMass), minus the decode. */
     hasHalo(id) {
+        if (this.meter)
+            this.meter.haloProbes++;
         const r = this._dbGetHalo(id);
         return r !== null && r.mass >= this.minHaloMass;
     }
@@ -1473,9 +1553,14 @@ export class AbstractStore {
         const cache = this._resonateHaloCache;
         if (cache) {
             const hit = cache.get(rk);
-            if (hit !== undefined)
+            if (hit !== undefined) {
+                if (this.meter)
+                    this.meter.annCacheHits++;
                 return hit;
+            }
         }
+        if (this.meter)
+            this.meter.haloQueries++;
         const results = this._vecHaloQuery(normalize(copy(v)), k * this.overfetch, this.efFor(this._vecHaloClusterCount()));
         const out = [];
         for (const r of results) {

package/package.json

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

package/src/derive/src/deduction.ts

@@ -128,12 +128,25 @@ export interface Derivation<I> {
   premises: Array<Derivation<I>>;
 }
 
+/** Optional search-effort read-out, filled in place while the search runs.
+ *  A plain structural record so the sublibrary stays firewalled (it imports
+ *  nothing from Sema, and Sema copies these into its own accounting).  Purely
+ *  observational: the search never reads it back. */
+export interface SearchStats {
+  /** Agenda entries popped, stale lazy-deletion entries included — the chart
+   *  work actually done. */
+  pops: number;
+  /** Agenda entries pushed by a successful relaxation. */
+  pushes: number;
+}
+
 /**
  * Find a lightest derivation of a goal item, or `null` if none exists.
  * `cost` on the returned root is the total derivation cost.
  */
 export function lightestDerivation<I>(
   system: DeductionSystem<I>,
+  stats?: SearchStats,
 ): Derivation<I> | null {
   const g = new Map<string, number>(); // best known cost per item
   const proof = new Map<string, Rule<I> | null>(); // producing rule per item
@@ -177,6 +190,7 @@ export function lightestDerivation<I>(
       g.set(key, cost);
       proof.set(key, rule);
       items.set(key, item);
+      if (stats) stats.pushes++;
       agenda.push(cost + h(item, key), { key, g: cost });
     }
   };
@@ -185,6 +199,7 @@ export function lightestDerivation<I>(
 
   while (agenda.size > 0) {
     const { value } = agenda.pop() as { value: { key: string; g: number } };
+    if (stats) stats.pops++;
     const key = value.key;
     // Lazy deletion: an entry is stale if a cheaper derivation has since been
     // recorded for the same item.

package/src/derive/src/index.ts

@@ -7,6 +7,7 @@
 // symbolic-rewriting mechanism. See ./../README.md for the design.
 
 export { lightestDerivation } from "./deduction.js";
+export type { SearchStats } from "./deduction.js";
 export type {
   DeductionSystem,
   Derivation,