@hviana/sema 0.2.9 → 0.4.0

package/dist/src/geometry.js

@@ -242,6 +242,163 @@ function bytesToLeaves(alphabet, bytes) {
         return { tree: sema(v, bytes.slice(i, i + 1), null), len: 1 };
     });
 }
+/** CONTENT-DEFINED FOLD BOUNDARIES — where a byte stream segments, chosen by
+ *  the bytes rather than by arithmetic.
+ *
+ *  `riverFold` groups FIXED arity from byte 0 and permutes item k by
+ *  `seats[k]`, k = index mod W, so a byte's contribution is a function of its
+ *  ABSOLUTE OFFSET: the same byte run is a different vector at a different
+ *  position, and the same content is a different SUBTREE.  W's size has nothing
+ *  to do with it — any fixed modulus does this, and identity must not depend on
+ *  W at all.
+ *
+ *  A rolling hash removes the dependence without touching the fold's arity: the
+ *  cut lands where the hash of the recent bytes vanishes mod W, so a change
+ *  upstream moves only the cut it falls inside — every downstream boundary, and
+ *  therefore every downstream segment, is unchanged.  Because
+ *  {@link stablePrefixFold} folds each segment independently from its own slot
+ *  0, byte-identical content then produces byte-identical subtrees, and
+ *  hash-consing makes it the SAME NODE ID wherever it appears.  That — not the
+ *  root cosine, which should and does still move when content is added — is
+ *  what recognition, cover and resolve need.
+ *
+ *  Measured over 400 real deposits, shifts of 1..7 bytes, downstream cuts
+ *  preserved / segments byte-identical:
+ *
+ *      content-defined, deposit text        99.7% / 98.4%   mean seg 6.61 B
+ *      content-defined, non-Latin scripts   99.6% / 98.3%   mean seg 6.43 B
+ *      content-defined, random binary       99.9% / 99.2%   mean seg 6.92 B
+ *      the arithmetic grid, same corpus     14.3%           (only the k≡0 mod W
+ *                                                           shifts survive)
+ *
+ *  The three content-defined rows agreeing is the load-bearing part: this reads
+ *  BYTES, never text.  Mind is not a text engine — the same fold carries grids
+ *  and any other modality — so a boundary rule justified by where words or
+ *  sentences fall would be importing an assumption the architecture rejects.
+ *  Random binary must, and does, behave exactly like prose.
+ *
+ *  Every constant is derived (§2.2): the cut mask is W, so a cut is offered once
+ *  per quantum of bytes — which, composed with the minimum below, puts the
+ *  expected segment at minLen + W − 1 ≈ 6 B rather than at W, deliberately (see
+ *  the refutation recorded at `cutRate` in {@link contentLevels}: a segment is
+ *  the flat PHRASE-scale unit the W-ary groups are built from, not a group of W
+ *  children, and forcing E[len] = W costs 15 tests).  The minimum is W−1, `canonicalWindows`'s
+ *  straddle neighbour and the write side's own floor for a unit; and the maximum
+ *  is the KEYRING's seat count, because a segment folds as ONE flat node and
+ *  `fold` has exactly that many seats to bind children into.  Capping there is
+ *  what keeps the fold light: a segment of 3..seats leaves is a single node,
+ *  where splitting it into W-groups plus a remainder would cost two or three
+ *  and the remainders barely share (measured: partial-arity nodes 504 → 3,590,
+ *  and total distinct nodes 8,142 → 9,712, when segments folded as [W][rest]). */
+/** {@link contentBoundaries} plus, for each cut, its LEVEL — how deep in the
+ *  tree that cut reaches.
+ *
+ *  One rolling hash serves every scale.  A cut is level 0 when its hash vanishes
+ *  mod W, level 1 when mod W², and so on: level-L cuts are by construction a
+ *  subset of level-(L−1) cuts, which is exactly the nesting a tree needs.  The
+ *  expected span of a level-L node is therefore W^(L+1) bytes — the same growth
+ *  the grid fold had, but with boundaries the content chose, so a shift moves
+ *  one node at each level instead of all of them.
+ *
+ *  Levels are read from the hash the cut was ACCEPTED at, not recomputed, so
+ *  they cost nothing beyond the divisions already being done. */
+function contentLevels(space, bytes) {
+    const W = space.maxGroup;
+    const minLen = W - 1;
+    const maxLen = space.seats.length;
+    // MEASURED AND REFUTED — making E[segment] equal W.  A segment is at least
+    // `minLen` bytes and then cuts with probability p, so E[len] = minLen +
+    // (1−p)/p; with `h % W === 0` that is minLen + W − 1 = 6 for W = 4 (measured
+    // mean 6.61 B on real deposits), half again coarser than the fold's own
+    // arity, and the doc above used to claim the mask made the two equal.  It
+    // does not, and the mismatch looked like the cause of a real deficit: the
+    // climb perceives one region per segment, so on `Michelangelo is to sculpture
+    // as who is to literature?` it sees 9 regions where the grid saw 19, reaches
+    // one ranked anchor instead of two, and CAST's weave never includes the
+    // writing-domain exemplar it needs (test/29 A2, C1).
+    //
+    // Fixing the rate to hit E[len] = W (a threshold `h % W < W − minLen + 1` on
+    // the same rolling value, keeping the two bytes of history) does exactly what
+    // it says — mean segment 3.60 B on text, 3.93 B on random binary, 14 segments
+    // on that query instead of 9 — and takes the suite from 3 failures to 18,
+    // across think, universality, scaling, decomposition, bridge, generalization,
+    // saturation, audit and recognition. The coarser-than-arity scale is
+    // load-bearing: W is the arity `riverFold` groups CHILDREN at, and a segment
+    // is not a group of W children but the flat unit those groups are built from
+    // — a phrase-scale unit, and the mechanisms above all read it that way.
+    // Do not re-derive the rate from W.
+    //
+    // MEASURED AND REFUTED — reading the hash's HIGH bits instead of its low
+    // ones.  The accumulator shifts LEFT, so `h % W` is the part the mixing has
+    // had no chance to reach: with `h = (h << 1) + byte·K` and K odd, `h mod 4`
+    // reduces to `(2·(prev mod 2) + byte) mod 4` — two bytes of history, and only
+    // their parity.  It reads like a hash test that is really a byte-parity test,
+    // and it shows: on `Michelangelo is to sculpture as who is to literature?`
+    // the segments come out 8,8,8,8,8,7,4,2 — almost every boundary the FORCED
+    // one at maxLen, which is the one offset-dependent cut in the rule.
+    //
+    // Testing the top bits instead (`h < 2^32 / W`, the same 1/W rate, with the
+    // level test falling out as `h < 2^32 / W^(L+1)` — cleaner nesting than
+    // divisibility) takes the suite from 2 failures to 21 AND breaks the
+    // invariance floor in test/59.  The reason is the whole point: in a
+    // shift-accumulator the LOW bits have a short effective window and the HIGH
+    // bits a long one, so a disturbance upstream perturbs the high bits for the
+    // next ~32 bytes while the low bits re-sync within two.  The narrow window is
+    // not a defect in this hash — it IS the invariance.  A boundary rule here is
+    // choosing how far a change may propagate, not how well the bits mix.
+    //
+    // MEASURED AND REFUTED — normalized chunking, to shrink the forced cut.  The
+    // hard cut at maxLen is the ONE offset-dependent boundary left in the rule,
+    // and it is not rare: 32% of segments on a mixed sample end there, five of
+    // the eight in the query above, so for those streams the fold IS a grid of 2W
+    // with all of the grid's phase.  The standard remedy applies cleanly here —
+    // past a target length, relax the mask by one power of the same radix
+    // (W → W/2), still content-defined and so still invariant, just coarser
+    // evidence for a boundary; both quantities are already in the rule, nothing
+    // introduced.  It works as advertised: forced cuts fall from 32% to 8.3% and
+    // test/59's invariance floors still hold.
+    //
+    // And the suite goes from 2 failures to 5 relaxing at the expected length
+    // (minLen + W − 1), or to 6 relaxing at the last opportunity (maxLen − 1) —
+    // 22-multihop, 24-generalization, 29, 36.  Taken with the two results above
+    // (changing the rate costs 15 tests; changing which bits are read costs 19),
+    // the reading is that the segment DISTRIBUTION is what the mechanisms
+    // downstream are fitted to, not the purity of the rule that produces it.  The
+    // forced cut is part of that distribution.  Do not tidy it away without
+    // re-measuring everything that reads a region.
+    const cuts = [];
+    const levels = [];
+    let h = 0;
+    let last = 0;
+    for (let i = 0; i < bytes.length; i++) {
+        h = (((h << 1) >>> 0) + Math.imul(bytes[i], 2654435761)) >>> 0;
+        if (i + 1 >= bytes.length)
+            break;
+        const hit = h % W === 0;
+        if (i - last >= minLen && (hit || i - last + 1 >= maxLen)) {
+            cuts.push(i + 1);
+            // How many further powers of W divide the hash — 0 for a forced cut.
+            let lvl = 0;
+            if (hit) {
+                let m = W;
+                while (lvl < 24 && m <= 0x40000000 && h % (m * W) === 0) {
+                    lvl++;
+                    m *= W;
+                }
+            }
+            levels.push(lvl);
+            last = i + 1;
+        }
+    }
+    return { cuts, levels };
+}
+export function contentBoundaries(space, bytes) {
+    // ONE implementation of the rule.  This used to carry its own copy of the
+    // rolling-hash loop, which is exactly how a write side and a read side drift
+    // apart without a type error; the levels are computed from the hash the cut
+    // was accepted at, so asking for them costs nothing but an array.
+    return contentLevels(space, bytes).cuts;
+}
 /** Find the longest prefix of `bytes` whose leaf-id signature matches a
  *  known branch via `lookup`.  Returns the byte-length of that prefix, or 0. */
 export function knownPrefixLength(bytes, leafAt, lookup) {
@@ -283,11 +440,144 @@ export function bytesToTree(space, alphabet, bytes, leafAt, lookup, boundaries)
     if (bytes.length === 0) {
         return sema(alphabet.vecs[0], new Uint8Array(0), null);
     }
-    if (boundaries !== undefined && boundaries.length > 0) {
-        return stablePrefixFold(space, alphabet, bytes, boundaries);
-    }
+    // WHERE A STREAM SEGMENTS IS DECIDED BY ITS BYTES ({@link contentBoundaries}),
+    // and the segments then fold BALANCED, W-ary, like any other row of items.
+    //
+    // The two must not be confused.  Content cuts are what make identity
+    // offset-free: a segment folds from its own slot 0, so the same bytes give the
+    // same subtree wherever they sit.  The shape ABOVE the segments is a separate
+    // question, and it must stay the river's own — grouping W at a time, depth
+    // log_W(n).  Joining segments left-nested instead (as the stable-prefix fold
+    // does, for its own good reason) costs a node per segment on a single spine:
+    // at a cut every ~6.6 B a 3 KB deposit becomes a 450-deep spine of 450 fresh
+    // D-vectors, ~1.8 MB for one deposit, and every walker above inherits the
+    // depth.  That is an implementation blunder, not a property of content-defined
+    // folding, and it is what riverFold below avoids.
+    //
+    // Caller-supplied boundaries stay left-nested (see stablePrefixFold): there are
+    // a handful of them, one per conversation turn, and the cumulative-context-root
+    // contract depends on that shape.  Each SPAN between them content-folds.
     const sb = (leafAt && lookup) ? knownPrefixLength(bytes, leafAt, lookup) : 0;
-    return riverFold(space, bytesToLeaves(alphabet, bytes), sb > 0 ? sb : bytes.length).tree;
+    const outer = new Set();
+    if (boundaries !== undefined) {
+        for (const b of boundaries)
+            outer.add(b);
+    }
+    if (sb > 0)
+        outer.add(sb);
+    if (outer.size === 0) {
+        return rootOf(contentFoldSpan(space, alphabet, bytes, 0, bytes.length));
+    }
+    return stablePrefixFold(space, alphabet, bytes, [...outer].sort((a, b) => a - b));
+}
+/** One span, folded over its own content cuts — AT EVERY LEVEL.
+ *
+ *  A segment becomes ONE FLAT NODE: every leaf bound into its own seat and
+ *  summed, arity = the segment's length.  `contentBoundaries` caps a segment at
+ *  the keyring's seat count so this is always possible, and the flat form is
+ *  both lighter (one node per segment instead of a [W][remainder] pair) and the
+ *  natural unit — a segment IS the smallest thing the cuts claim is a unit.
+ *
+ *  Above the segments the cutting RECURSES rather than reverting to the grid.
+ *  Grouping segment roots W-at-a-time from index 0 would reintroduce the very
+ *  bug content cuts exist to remove, one level up: a form spanning segments
+ *  12..17 straddles the [12-15] and [16-17] groups and is no node at all, so
+ *  recognition can only reach it by an alignment accident (test/44 pins exactly
+ *  this — at HEAD the grid happened to put a node one byte before the target).
+ *  {@link contentLevels} assigns each cut a level from how divisible its hash
+ *  is, so level-L cuts are a subset of level-(L−1) cuts and every node at every
+ *  scale is delimited by content.  Identity is then offset-free at all scales,
+ *  which is the whole requirement — it must not depend on W. */
+function contentFoldSpan(space, alphabet, bytes, from, to) {
+    const span = bytes.subarray(from, to);
+    const { cuts, levels } = contentLevels(space, span);
+    const edges = [0, ...cuts, span.length];
+    const segs = [];
+    for (let i = 0; i + 1 < edges.length; i++) {
+        segs.push(flatFold(space, alphabet, span, edges[i], edges[i + 1]));
+    }
+    if (segs.length > 1)
+        return groupByLevel(space, segs, levels, 1);
+    return segs[0];
+}
+/** Group a row of items by the level of the cut BETWEEN them: items separated
+ *  by a cut of level < L belong to the same parent, and a cut of level ≥ L ends
+ *  it.  Recurses upward until one root remains, so the shape at every level is
+ *  the content's, not an index's.  `levels[i]` is the level of the cut that
+ *  precedes item i+1 (there are items.length − 1 of them).
+ *
+ *  A level that fails to split (every cut below L) or that would exceed the
+ *  keyring falls through to the plain river fold for that row — the fold stays
+ *  total on any input, and the fallback is rare enough not to reintroduce a
+ *  systematic alignment. */
+function groupByLevel(space, items, levels, level) {
+    if (items.length === 1)
+        return items[0];
+    const maxSeats = space.seats.length;
+    const groups = [];
+    const groupLevels = [];
+    let start = 0;
+    for (let i = 0; i <= levels.length; i++) {
+        const atEnd = i === levels.length;
+        const cutHere = atEnd || levels[i] >= level;
+        const wouldOverflow = i - start + 1 >= maxSeats;
+        if (!cutHere && !wouldOverflow)
+            continue;
+        const slice = items.slice(start, i + 1);
+        groups.push(slice.length === 1 ? slice[0] : joinFlat(space, slice));
+        if (!atEnd)
+            groupLevels.push(levels[i]);
+        start = i + 1;
+    }
+    if (groups.length === items.length) {
+        // This level split nothing — climb rather than spin.
+        return level < 24
+            ? groupByLevel(space, items, levels, level + 1)
+            : riverFoldRaw(space, items);
+    }
+    return groupByLevel(space, groups, groupLevels, level + 1);
+}
+/** Join a row of already-folded items as one unnormalized node — the same
+ *  seat-bound accumulate `flatFold` does for bytes, one level up. */
+function joinFlat(space, items) {
+    const gist = new Float32Array(space.D);
+    const kids = new Array(items.length);
+    let len = 0;
+    for (let k = 0; k < items.length; k++) {
+        const v = items[k].tree.v;
+        const seat = space.seats[k].fwd;
+        for (let d = 0; d < space.D; d++)
+            gist[d] += v[seat[d]];
+        kids[k] = items[k].tree;
+        len += items[k].len;
+    }
+    return { tree: sema(gist, null, kids), len };
+}
+/** One segment as a single unnormalized node: leaf per byte, each bound into
+ *  seat k, summed.  Same FP ops and same seat order as foldSlice's group fold —
+ *  only the arity is the segment's own length rather than a fixed W.  Never
+ *  normalizes: the linear-fold contract keeps every interior gist raw and
+ *  normalizes once at the root. */
+function flatFold(space, alphabet, bytes, from, to) {
+    const n = to - from;
+    if (n === 1) {
+        const b = bytes[from];
+        return {
+            tree: sema(alphabet.vecs[b], bytes.slice(from, to), null),
+            len: 1,
+        };
+    }
+    const gist = new Float32Array(space.D);
+    const kids = new Array(n);
+    for (let k = 0; k < n; k++) {
+        const b = bytes[from + k];
+        const v = alphabet.vecs[b];
+        const seat = space.seats[k].fwd;
+        for (let d = 0; d < space.D; d++)
+            gist[d] += v[seat[d]];
+        kids[k] = sema(v, bytes.slice(from + k, from + k + 1), null);
+    }
+    return { tree: sema(gist, null, kids), len: n };
 }
 /** The stable-prefix segmented fold (§10.3).  Each segment between
  *  consecutive boundaries folds PLAINLY and independently; segment roots
@@ -297,6 +587,22 @@ export function bytesToTree(space, alphabet, bytes, leafAt, lookup, boundaries)
  *  boundary, so the left-nested join reproduces every intermediate learnt
  *  root ((s₀·s₁) IS the root the store learnt for the first two segments'
  *  bytes, and so on). */
+/** A fold's ROOT: ONE normalize per perception, at the root, exactly as
+ *  riverFold did — the interior stays raw (the linear-fold contract).
+ *
+ *  Normalizes EXCEPT when the whole stream folded to a single
+ *  leaf: a leaf's vector IS the alphabet's own, shared by every occurrence of
+ *  that byte, and `normalize` writes in place.  Every fold entry point returns
+ *  through here, because the guard is exactly the kind that gets written at one
+ *  site and missed at the next two — which is what had happened: only
+ *  {@link bytesToTree} carried it, while `stablePrefixFold` and its incremental
+ *  twin normalized unconditionally, reachable by a one-byte stream whose only
+ *  boundary is its own length. */
+function rootOf(f) {
+    if (f.tree.kids !== null)
+        normalize(f.tree.v);
+    return f.tree;
+}
 function stablePrefixFold(space, alphabet, bytes, boundaries) {
     const cuts = [];
     let prev = 0;
@@ -307,19 +613,17 @@ function stablePrefixFold(space, alphabet, bytes, boundaries) {
         }
     }
     if (cuts.length === 0) {
-        return riverFold(space, bytesToLeaves(alphabet, bytes), bytes.length).tree;
+        return rootOf(contentFoldSpan(space, alphabet, bytes, 0, bytes.length));
     }
     const edges = [0, ...cuts, bytes.length];
     const segs = [];
     for (let i = 0; i + 1 < edges.length; i++) {
-        const seg = bytes.subarray(edges[i], edges[i + 1]);
-        segs.push(riverFoldRaw(space, bytesToLeaves(alphabet, seg)));
+        segs.push(contentFoldSpan(space, alphabet, bytes, edges[i], edges[i + 1]));
     }
     let cur = segs[0];
     for (let i = 1; i < segs.length; i++)
         cur = fold2(space, cur, segs[i]);
-    normalize(cur.tree.v);
-    return cur.tree;
+    return rootOf(cur);
 }
 /** {@link stablePrefixFold} with incremental segment reuse — same cuts, same
  *  segment folds, same left-nested join, same single root normalize; `prev`
@@ -342,19 +646,30 @@ export function stablePrefixFoldIncremental(space, alphabet, bytes, boundaries,
             prev.edges[i + 1] === edges[i + 1]
             ? prev.segs[i]
             : undefined;
-        segs.push(hit ??
-            riverFoldRaw(space, bytesToLeaves(alphabet, bytes.subarray(edges[i], edges[i + 1]))));
+        segs.push(hit ?? contentFoldSpan(space, alphabet, bytes, edges[i], edges[i + 1]));
     }
     if (segs.length === 1) {
-        // Degenerate boundary set — the plain fold, as stablePrefixFold does.
-        const tree = riverFold(space, bytesToLeaves(alphabet, bytes), bytes.length).tree;
+        // Degenerate boundary set — one span, which IS the whole stream, and it was
+        // just folded (or reused from `prev`) right above.  It cannot go through
+        // `rootOf`: the ROOT is normalized, a cached SEGMENT never is (a later turn
+        // reuses it as one), and `normalize` writes in place.  Re-folding `bytes`
+        // to get a separate object is what this used to do — and a first-seen
+        // deposit has no boundaries, so it always lands here, paying the fold
+        // twice.  Copying the gist is the same result for one vector copy.  A
+        // single LEAF needs neither: its vector is the shared alphabet entry and
+        // must not be written at all.
+        const only = segs[0].tree;
+        const tree = only.kids === null
+            ? only
+            : sema(Float32Array.from(only.v), null, only.kids);
+        if (tree.kids !== null)
+            normalize(tree.v);
         return { tree, fold: { edges, segs } };
     }
     let cur = segs[0];
     for (let i = 1; i < segs.length; i++)
         cur = fold2(space, cur, segs[i]);
-    normalize(cur.tree.v);
-    return { tree: cur.tree, fold: { edges, segs } };
+    return { tree: rootOf(cur), fold: { edges, segs } };
 }
 /** Join two folded items as one 2-kid branch — the top-level join of the
  *  stable-prefix fold, identical FP ops to foldSlice's seat-bound
@@ -419,73 +734,6 @@ export function composeStructuralGist(space, parts) {
     normalize(result);
     return result;
 }
-/** Plain bytes→tree (identical to capability-less {@link bytesToTree}) that
- *  also RETURNS its pyramid, reusing `prev` — the pyramid of a PROPER
- *  prefix of `bytes` (caller guarantees content match and
- *  prev.bytes < bytes.length). */
-export function bytesToTreePyramid(space, alphabet, bytes, prev) {
-    if (bytes.length === 0) {
-        return {
-            tree: sema(alphabet.vecs[0], new Uint8Array(0), null),
-            pyramid: { levels: [], bytes: 0 },
-        };
-    }
-    // ZERO GROWTH: the previous pyramid already covers every byte — its top
-    // level holds the finished, normalized root.  Refolding here would not
-    // only waste the work: when the whole span is one full block, the refold's
-    // top item is a REUSED raw interior of `prev`, and the final normalize
-    // below would mutate that shared raw block in place, corrupting every
-    // later incremental fold built on `prev`.
-    if (prev && prev.bytes === bytes.length && prev.levels.length > 0) {
-        return {
-            tree: prev.levels[prev.levels.length - 1][0].tree,
-            pyramid: prev,
-        };
-    }
-    const mg = space.maxGroup;
-    const reusable = (L) => {
-        // prev's TOPMOST level holds its normalized ROOT — reusable blocks must
-        // be raw interiors, so the top level is always excluded.
-        if (!prev || L > prev.levels.length - 2)
-            return null;
-        return prev.levels[L];
-    };
-    // Level 0: reuse the prefix's leaf items wholesale (all are full blocks).
-    const lv0 = reusable(0);
-    const row = lv0
-        ? [...lv0, ...bytesToLeaves(alphabet, bytes.subarray(prev.bytes))]
-        : bytesToLeaves(alphabet, bytes);
-    const levels = [row];
-    let level = row;
-    let L = 0;
-    while (level.length > 1) {
-        let next = [];
-        // Reuse the leading FULL blocks of prev's level L+1 (len == mg^(L+1),
-        // wholly inside the prefix); the rule below folds the rest from this
-        // level's items exactly as the from-scratch fold would.
-        const blockLen = mg ** (L + 1);
-        let reused = 0;
-        const cand = reusable(L + 1);
-        if (cand) {
-            const maxFull = Math.floor(prev.bytes / blockLen);
-            while (reused < maxFull && reused < cand.length &&
-                cand[reused].len === blockLen)
-                reused++;
-            for (let i = 0; i < reused; i++)
-                next.push(cand[i]);
-        }
-        foldSlice(space, level, reused * mg, level.length - reused * mg, next, true);
-        levels.push(next);
-        level = next;
-        L++;
-    }
-    if (row.length > 1)
-        normalize(level[0].tree.v);
-    return {
-        tree: level[0].tree,
-        pyramid: { levels, bytes: bytes.length },
-    };
-}
 // ---- n-D Hilbert curve ----
 function gridDims(grid) {
     if (grid.dims && grid.dims.length > 0)

package/dist/src/index.d.ts

@@ -4,6 +4,7 @@ export * from "./sema.js";
 export * from "./alphabet.js";
 export * from "./geometry.js";
 export * from "./store.js";
+export * from "./meter.js";
 export * from "./mind/rationale.js";
 export * from "./mind/index.js";
 export * from "./store-sqlite.js";

package/dist/src/index.js

@@ -6,6 +6,7 @@ export * from "./sema.js";
 export * from "./alphabet.js";
 export * from "./geometry.js";
 export * from "./store.js";
+export * from "./meter.js";
 export * from "./mind/rationale.js";
 export * from "./mind/index.js";
 export * from "./store-sqlite.js";

package/dist/src/meter.d.ts

@@ -0,0 +1,171 @@
+/** Per-phase accumulation — one entry per mechanism `floor`/`run` and per
+ *  named stage.
+ *
+ *  PHASES NEST, AND ARE NOT DISJOINT.  `think` contains every mechanism
+ *  phase; a mechanism's `floor` contains whatever shared analysis it
+ *  first-touched (`attention`, `weave`); `recall.run` contains
+ *  `substitutionBridge`, which contains `recall.exhaustiveResonate`.  Read a
+ *  phase as "wall-clock spent inside this, inclusive" — never sum them and
+ *  expect the total.  `CostReport.elapsedMs` is the only whole.
+ *
+ *  Shared analyses are charged to THEMSELVES, not to the mechanism that
+ *  first-touched them: the first toucher pays the wall clock, but every
+ *  later consumer gets the result free, so blaming it would misread which
+ *  work is expensive.  (Before this, the profile read "cast.floor costs
+ *  2.9 s"; what actually cost 2.7 s of that was the consensus climb, which
+ *  cast merely paid for on everyone's behalf.) */
+export interface PhaseCost {
+    /** How many times the phase ran. */
+    calls: number;
+    /** Wall-clock milliseconds spent inside it (non-deterministic). */
+    ms: number;
+    /** Work counters accrued INSIDE this phase — the same names as
+     *  {@link CostReport.counters}, differenced across the phase's entry and
+     *  exit, summed over its calls.  Deterministic, unlike `ms`, and the field
+     *  that answers "which phase did those 75,000 byte reads?" — a question a
+     *  whole-response counter total cannot.  Inclusive, like `ms`: a nested
+     *  phase's work is counted in its parent too. */
+    counters: Record<string, number>;
+}
+/** A snapshot of one inference call's computational usage.  Plain data —
+ *  JSON-serialisable, diffable between runs. */
+export interface CostReport {
+    version: 1;
+    /** Wall-clock milliseconds of the whole call (non-deterministic). */
+    elapsedMs: number;
+    /** Query length in bytes — the scale every other number is read against. */
+    queryBytes: number;
+    /** Deterministic work counters, by layer. */
+    counters: Record<string, number>;
+    /** Per-phase call counts and millisecond totals, insertion-ordered.
+     *  NESTED — see {@link PhaseCost}; do not sum. */
+    phases: Record<string, PhaseCost>;
+}
+/** The mutable accumulator.  One is created per profiled inference call and
+ *  handed to every layer through `ctx.meter` / `store.meter`. */
+export declare class Meter {
+    /** `store.get` — one node record materialised (cache hit or DB row). */
+    nodeRecords: number;
+    /** `store.bytes` / `store.bytesPrefix` — one reconstruction request. */
+    byteReads: number;
+    /** Bytes actually handed back by those reads — the real I/O volume, and
+     *  the number that exposes an unbounded read (AGENTS §2.8) that a call
+     *  count alone hides. */
+    bytesRead: number;
+    /** `store.contentLen`. */
+    lenReads: number;
+    /** `store.findLeaf`. */
+    leafLookups: number;
+    /** `store.findBranch`. */
+    branchLookups: number;
+    /** `store.canonFind` — equivalence-class candidate proposal. */
+    canonLookups: number;
+    /** `parents` + `parentsFirst` — materialising parent reads. */
+    parentReads: number;
+    /** `hasParents` — indexed existence probe. */
+    parentProbes: number;
+    /** `chainRun` — one bounded transparent-chain climb. */
+    chainRuns: number;
+    /** `containers` + `containersSlice`. */
+    containerReads: number;
+    /** `hasContainers` — indexed existence probe. */
+    containerProbes: number;
+    /** `next` + `nextFirst`. */
+    edgeReads: number;
+    /** `hasNext` — indexed existence probe. */
+    edgeProbes: number;
+    /** `prev` + `prevFirst`. */
+    prevReads: number;
+    /** `prevCount` — indexed count probe. */
+    prevProbes: number;
+    /** `halo` — one halo vector decoded. */
+    haloReads: number;
+    /** `hasHalo` + `haloMass` — probes that never decode a vector. */
+    haloProbes: number;
+    /** `resonate` calls that descended the content index. */
+    annQueries: number;
+    /** `resonate` calls served from the per-flush read cache. */
+    annCacheHits: number;
+    /** Stored vectors the content index actually scored — the dominant cost of
+     *  a query on a large store, and the one counter that grows with N when a
+     *  budget is missing. */
+    annVectorReads: number;
+    /** `resonateHalo` calls. */
+    haloQueries: number;
+    /** `perceive` calls that actually folded (memo misses only). */
+    perceptions: number;
+    /** Bytes folded by those perceptions — perception is O(bytes), so this is
+     *  its true cost, and it is what a multi-turn regression shows up in first
+     *  (re-folding the whole context instead of the new turn). */
+    perceivedBytes: number;
+    /** `perceive` calls served from the per-response / conversation memo. */
+    perceiveHits: number;
+    /** `recognise` calls that actually ran. */
+    recognitions: number;
+    /** Bytes recognised by those calls. */
+    recognisedBytes: number;
+    /** `recognise` calls served from the memo. */
+    recogniseHits: number;
+    /** `resolve` — whole-span content-addressed identity requests. */
+    resolves: number;
+    /** `climbAttentionAll` calls that actually climbed. */
+    climbs: number;
+    /** `climbAttentionAll` calls served from `climbMemo`. */
+    climbHits: number;
+    /** Query regions the climb voted on, summed over climbs. */
+    climbRegions: number;
+    /** Nodes popped and examined by `edgeAncestors` ascents — the climb's
+     *  inner loop, and the thing `hubBound` is supposed to be bounding. */
+    ancestorVisits: number;
+    /** `alignGraded` / `alignRuns` invocations. */
+    alignments: number;
+    /** Σ (query bytes × context bytes) over those alignments — the alignment
+     *  family is quadratic, so this is the honest unit. */
+    alignCells: number;
+    /** `junctionContainersFrom` ascents started — the cross-region ladder's
+     *  and the bridge's shared "which learnt whole contains these two forms?"
+     *  walk. */
+    junctionWalks: number;
+    /** Nodes popped by those ascents, against their √N·W budget — the counter
+     *  that shows whether the walks are deciding early or burning the budget. */
+    junctionPops: number;
+    /** `lightestDerivation` searches started. */
+    searches: number;
+    /** Chart items popped by those searches. */
+    searchPops: number;
+    /** Chart items pushed by those searches. */
+    searchPushes: number;
+    /** `floor()` calls that returned a bound (the mechanism could fire). */
+    mechanismFloors: number;
+    /** `floor()` calls that returned null (structurally impossible). */
+    mechanismSkips: number;
+    /** `run()` calls — the ones the floor pruning let through. */
+    mechanismRuns: number;
+    /** Candidates the decider weighed. */
+    candidates: number;
+    /** Candidates refused before the competition for explaining less than 1/W
+     *  of the query — the honesty-density floor (see pipeline.ts `consider`). */
+    thinRejects: number;
+    private readonly _phases;
+    private readonly _t0;
+    /** Every work counter's current value, by name — the snapshot `time`
+     *  differences to attribute work to a phase. */
+    private snapshot;
+    /** Charge `ms`, one call, and a counter delta to a named phase.
+     *  Insertion-ordered, so a report reads in execution order. */
+    charge(phase: string, ms: number, delta?: Record<string, number>): void;
+    /** Time one async phase and attribute the work done inside it.  Returns
+     *  the awaited value untouched — a meter never changes what a layer
+     *  computes, only what is known about it. */
+    time<T>(phase: string, fn: () => Promise<T>): Promise<T>;
+    /** The finished report.  Zero-valued counters are dropped: a report should
+     *  show what a query DID, not the whole vocabulary of what it might have. */
+    report(queryBytes: number): CostReport;
+}
+/** Sum a set of reports into one — for aggregating a battery of probes or a
+ *  multi-turn session.  `elapsedMs` and `queryBytes` add; counters and phases
+ *  merge by key. */
+export declare function sumReports(reports: readonly CostReport[]): CostReport;
+/** A human-readable rendering of a report — the shape a profiling run prints.
+ *  Pure formatting; no ANSI, so it is safe to log anywhere. */
+export declare function formatReport(r: CostReport): string;