@hviana/sema 0.3.0 → 0.4.1

package/dist/src/mind/traverse.js

@@ -8,6 +8,49 @@
 import { cosine } from "../vec.js";
 import { gistOf, read } from "./primitives.js";
 const structCaches = new WeakMap();
+// ── The shared ancestor-reach memo ──────────────────────────────────────
+//
+// `edgeAncestors` is a pure function of (node, N) over a read-only store —
+// asking never writes — so its result is reusable for as long as the store
+// is not written to.  There used to be TWO memos and they never met: the
+// climb built a private one per call (computeAttention), while
+// `Precomputed.reachMemo` — documented as "one response-scoped memo serves
+// every mechanism that prices commonality" — was reached only by confluence.
+// The climb is by far the biggest consumer.
+//
+// Keyed off `ctx.climbMemo`'s OBJECT IDENTITY, exactly like the struct cache
+// above, which buys the right lifetime for free: a plain respond() has a
+// fresh climbMemo, so the memo is response-scoped; a conversation turn has
+// the conversation's persistent one, so it is conversation-scoped.  That
+// matters — the stable-prefix fold makes each turn's subtree independent of
+// what follows, so 59–70% of a later turn's climb regions are byte-identical
+// repeats of an earlier turn's (measured on a 4-turn session), and every one
+// of them used to re-climb from cold.
+//
+// Budgeted, not unbounded (AGENTS §2.12): past the cap the whole map is
+// dropped and re-derived, costing a cold climb and never a wrong answer.
+const REACH_MEMO_MAX = 100_000;
+const reachCaches = new WeakMap();
+/** The reach memo this response should use — see the note above.
+ *
+ *  A TRACED response always gets a fresh, empty one.  `AncestorReach`'s
+ *  `visited`/`maxDepth`/`saturation` fields are populated only when a trace
+ *  is attached, so an entry deposited by an untraced earlier turn would
+ *  silently black out the reach detail of a later traced one; and the trace's
+ *  reach payload is serialised by ITERATING this map, which must therefore
+ *  hold what THIS climb consulted, not the whole conversation's history.
+ *  Consistent with AGENTS §2.11: a traced response is a different machine —
+ *  never benchmark with a trace attached. */
+export function sharedReachMemo(ctx) {
+    if (ctx.trace !== null || ctx.climbMemo === null)
+        return new Map();
+    let m = reachCaches.get(ctx.climbMemo);
+    if (m === undefined)
+        reachCaches.set(ctx.climbMemo, m = new Map());
+    else if (m.size >= REACH_MEMO_MAX)
+        m.clear();
+    return m;
+}
 function getStructCache(ctx) {
     if (ctx.climbMemo === null)
         return null;
@@ -89,7 +132,7 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
     // is withdrawn.  On a small store the floor stays ≤ √N and the atom
     // climbs exactly as before, so single-letter facts keep working.
     if (id < 0 && atomIsHub(ctx, contextCount)) {
-        const bound0 = Math.ceil(Math.sqrt(Math.max(2, contextCount)));
+        const bound0 = boundFor(contextCount);
         const reach = {
             roots: [],
             contextsReached: 0,
@@ -110,7 +153,7 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
         memo?.set(id, reach);
         return reach;
     }
-    const bound = Math.ceil(Math.sqrt(contextCount));
+    const bound = boundFor(contextCount);
     const roots = [];
     const seen = new Set([id]);
     const ctxSeen = new Set();
@@ -162,6 +205,8 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
     let visitedCount = 0;
     let maxDepth = 0;
     const visit = (x) => {
+        if (ctx.meter)
+            ctx.meter.ancestorVisits++;
         if (depths) {
             visitedCount++;
             if (curDepth > maxDepth)
@@ -344,8 +389,7 @@ export function atomReach(ctx, contextCount) {
  *  atom votes and is recognised exactly as any stored form; above it the
  *  alphabet is scaffolding everywhere and abstains. */
 export function atomIsHub(ctx, contextCount) {
-    return atomReach(ctx, contextCount) >
-        Math.ceil(Math.sqrt(Math.max(2, contextCount)));
+    return atomReach(ctx, contextCount) > boundFor(contextCount);
 }
 /** Whether a node LEADS SOMEWHERE — it bears a continuation edge or a halo.
  *  The admission predicate recognition filters sites with (HOW_IT_WORKS
@@ -386,7 +430,16 @@ export function corpusN(ctx) {
  *  materialised list.  {@link hubCap} is the list-side reading of the same
  *  convention. */
 export function hubBound(ctx) {
-    return Math.ceil(Math.sqrt(corpusN(ctx)));
+    return boundFor(corpusN(ctx));
+}
+/** √N for an EXPLICIT context count — the ctx-free reading of {@link
+ *  hubBound}, for the callers inside this module that are handed a count
+ *  rather than a context ({@link edgeAncestors}, {@link atomIsHub}).  The
+ *  floor at 2 matches {@link corpusN}'s, so both readings agree for every
+ *  input: the two used to be spelled out inline, once WITH the floor and
+ *  once without, in the same function. */
+function boundFor(contextCount) {
+    return Math.ceil(Math.sqrt(Math.max(2, contextCount)));
 }
 /** Cap a candidate list at the hub bound √N (insertion order) — the ONE
  *  fan-out convention every walk and disambiguation uses (see HOW_IT_WORKS

package/dist/src/mind/types.d.ts

@@ -4,17 +4,16 @@ import type { BoundedMap, Store } from "../store.js";
 import type { Space } from "../sema.js";
 import type { Alphabet } from "../alphabet.js";
 import type { MindConfig } from "../config.js";
+import type { Meter } from "../meter.js";
 import type { GraphSearch, Leaf, Seg, Site } from "./graph-search.js";
 import type { Rationale } from "./rationale.js";
-import type { FoldPyramid, Grid, StableFold } from "../geometry.js";
+import type { Grid, StableFold } from "../geometry.js";
 /** One {@link MindContext._depositTrees} entry — see that field's doc. */
 export interface DepositCacheEntry {
     /** Turn boundaries accumulated over this content's deposit chain —
      *  strictly increasing proper offsets, each a previously-deposited
      *  whole-context length.  Empty for a first-seen (single-turn) input. */
     boundaries: number[];
-    /** Plain-fold pyramid (first-seen inputs only). */
-    pyramid?: FoldPyramid;
     /** Stable-prefix segment folds (grown-context inputs only). */
     stable?: StableFold;
     /** The continuation bytes this ctxInput was paired with in ingestPair, if
@@ -29,6 +28,10 @@ export type Input = string | Uint8Array | Grid | Grid[];
 /** The host capabilities GraphSearch consults during a cover.  MindContext
  *  extends this so the Mind can pass itself as the host. */
 export interface GraphSearchHost {
+    /** Work accumulator, or null/absent when nothing is profiling — see
+     *  src/meter.ts.  Declared here (not only on MindContext) so the graph
+     *  search can report its chart effort without importing mind code. */
+    readonly meter?: Meter | null;
     resolve(bytes: Uint8Array): number | null;
     recogniseSpan?(bytes: Uint8Array): {
         sites: ReadonlyArray<Site>;
@@ -132,6 +135,19 @@ export interface RegionVote {
      *  to "one region" just because it collapsed to one pooled axiom.
      *  Defaults to 1 when absent. */
     absorbed?: number;
+    /** The SEPARATE query places this vote's evidence occupies, when that is
+     *  more than the one contiguous run [start, end].  A cross-region junction
+     *  vote is pooled as a single synthetic region spanning its endpoints and
+     *  the gap between them, so `[start, end]` reads as ONE place — yet the
+     *  vote exists precisely because two non-adjacent regions each voted and
+     *  only their conjunction resolved.  Cluster counting (Attention.clusters)
+     *  asks "how many separate places in the query corroborate this?", and
+     *  answering it from the merged span makes every joint binding look like a
+     *  single local neighbourhood; fusion's dispersion gate then drops it
+     *  unless it also explains most of the whole query, which a binding inside
+     *  a MULTI-topic query structurally cannot.  Absent for an ordinary
+     *  per-region vote, where the merged span already is the truth. */
+    parts?: readonly (readonly [number, number])[];
 }
 /** The structural gate that first decided an {@link edgeAncestors} climb was
  *  saturated (an abstention, not a discriminative conclusion) — pure
@@ -190,6 +206,12 @@ export type AItem = {
 };
 export interface MindContext extends GraphSearchHost {
     store: Store;
+    /** The work accumulator for the inference call in flight, or null when
+     *  nothing is profiling — see src/meter.ts.  WRITE-ONLY from the engine's
+     *  point of view: no inference decision may read a counter, or the
+     *  determinism contract (AGENTS §2.1) is gone.  Every call site is
+     *  `ctx.meter?.x++`, so an unprofiled response allocates nothing. */
+    meter: Meter | null;
     space: Space;
     alphabet: Alphabet;
     cfg: MindConfig;
@@ -250,8 +272,9 @@ export interface MindContext extends GraphSearchHost {
      *  folds with the SAME stable-prefix fold query-time perception uses
      *  (structural train/inference agreement, load-bearing for recall),
      *  reusing every already-folded segment via `stable` (see StableFold) —
-     *  O(turn) per deposit instead of O(context).  A first-seen input keeps
-     *  the plain fold and caches its `pyramid` (see FoldPyramid).  Purely a
+     *  O(turn) per deposit instead of O(context).  A first-seen input takes the
+     *  same fold with no boundaries at all, and caches the segments it produced
+     *  so a later turn of the same conversation reuses them.  Purely a
      *  performance cache for the FOLD STATE; the boundaries are semantic but
      *  derived only from the deposit sequence itself (an evicted chain falls
      *  back to plain-fold behavior, exactly the pre-boundary shape). */

package/dist/src/store.d.ts

@@ -1,5 +1,6 @@
 import { Vec } from "./vec.js";
 import { type StoreConfig } from "./config.js";
+import type { Meter } from "./meter.js";
 /** A node id: a dense, non-negative integer assigned in creation order. */
 export type NodeId = number;
 /** A node in the graph. Exactly one of `leaf` / `kids` is set. */
@@ -62,6 +63,13 @@ export declare class BoundedMap<K, V> {
 }
 export interface Store {
     readonly D: number;
+    /** The work accumulator for the inference call in flight, or null.  The
+     *  Mind attaches one per profiled response and detaches it after (see
+     *  src/meter.ts).  A store MUST only ever write to it — no read may reach
+     *  a decision, or determinism is gone.  An adapter that adds reads of its
+     *  own should bump the matching counter; one that does not simply reports
+     *  less, never wrongly. */
+    meter: Meter | null;
     /** Insert a leaf, returning its content id. Idempotent. */
     putLeaf(bytes: Uint8Array, gist: Vec): Promise<NodeId>;
     /** Insert a branch over child ids, returning its content id. Idempotent. */
@@ -508,6 +516,10 @@ export declare abstract class AbstractStore implements Store {
      *  outlive their records — the read degrades safely to empty bytes, this
      *  counter is what keeps that degradation observable. */
     danglingReads: number;
+    /** {@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: Meter | null;
     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
@@ -517,6 +529,9 @@ export declare abstract class AbstractStore implements Store {
      *  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: NodeId, maxLen: number): Uint8Array;
+    /** {@link bytesPrefix}'s recursive body — uncharged; see the metering
+     *  boundary note there. */
+    private _prefix;
     contentLen(id: NodeId, cap?: number): number;
     findLeaf(bytes: Uint8Array): NodeId | null;
     findBranch(kids: NodeId[]): NodeId | null;

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.3.0",
+  "version": "0.4.1",
   "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,