@hviana/sema 0.8.1 → 0.8.2

package/dist/src/config.d.ts

@@ -100,6 +100,23 @@ export interface MindConfig {
     seed: number;
     recallQueryK: number;
     haloQueryK: number;
+    /** Corpus reading (see src/mind/corpus.ts): results per call, resolved
+     *  nodes climbed from, contexts requested per climb, probes used to stride
+     *  the id space when browsing, bytes of each side a preview keeps, and the
+     *  smallest deposited note browsing will show.  Capacities and budgets only —
+     *  the one material floor (a resolved node must account for W bytes) is
+     *  derived from the geometry, not declared here. */
+    corpusLimitMax: number;
+    corpusClimbs: number;
+    corpusContextsPerClimb: number;
+    corpusSampleProbes: number;
+    corpusPreviewBytes: number;
+    corpusSampleFloorBytes: number;
+    /** Items one rationale step may ITEMISE (the whole field is still counted in
+     *  the step's note).  A capacity of the rationale, not of recall: sharing
+     *  `recallQueryK` meant `new Mind({recallQueryK: 100000})` un-bounded the very
+     *  payload the bound exists for (found by an adversarial review). */
+    rationaleSampleK: number;
     normalizeEpsilon: number;
     cosineEpsilon: number;
     alu: AluConfig;

package/dist/src/config.js

@@ -5,6 +5,13 @@ export const DEFAULT_CONFIG = {
     seed: 42,
     recallQueryK: 12,
     haloQueryK: 12,
+    rationaleSampleK: 12,
+    corpusLimitMax: 24,
+    corpusClimbs: 24,
+    corpusContextsPerClimb: 6,
+    corpusSampleProbes: 6000,
+    corpusPreviewBytes: 220,
+    corpusSampleFloorBytes: 12,
     normalizeEpsilon: 1e-12,
     cosineEpsilon: 1e-12,
     alu: {
@@ -44,6 +51,17 @@ export function resolveConfig(opts = {}) {
         seed: opts.seed ?? DEFAULT_CONFIG.seed,
         recallQueryK: opts.recallQueryK ?? DEFAULT_CONFIG.recallQueryK,
         haloQueryK: opts.haloQueryK ?? DEFAULT_CONFIG.haloQueryK,
+        rationaleSampleK: opts.rationaleSampleK ?? DEFAULT_CONFIG.rationaleSampleK,
+        corpusLimitMax: opts.corpusLimitMax ?? DEFAULT_CONFIG.corpusLimitMax,
+        corpusClimbs: opts.corpusClimbs ?? DEFAULT_CONFIG.corpusClimbs,
+        corpusContextsPerClimb: opts.corpusContextsPerClimb ??
+            DEFAULT_CONFIG.corpusContextsPerClimb,
+        corpusSampleProbes: opts.corpusSampleProbes ??
+            DEFAULT_CONFIG.corpusSampleProbes,
+        corpusPreviewBytes: opts.corpusPreviewBytes ??
+            DEFAULT_CONFIG.corpusPreviewBytes,
+        corpusSampleFloorBytes: opts.corpusSampleFloorBytes ??
+            DEFAULT_CONFIG.corpusSampleFloorBytes,
         normalizeEpsilon: opts.normalizeEpsilon ?? DEFAULT_CONFIG.normalizeEpsilon,
         cosineEpsilon: opts.cosineEpsilon ?? DEFAULT_CONFIG.cosineEpsilon,
         alu: {

package/dist/src/meter.d.ts

@@ -152,6 +152,31 @@ export declare class Meter {
     mechanismRuns: number;
     /** Candidates the decider weighed. */
     candidates: number;
+    /** `deriveThrough` yielded — a fact was reached through the subject the query
+     *  never named. */
+    joinFired: number;
+    /** Refused: no key names the entity and the tail together.  (A key that
+     *  resolves but leads nowhere is not "refused" — it is not the relation, so
+     *  the scan simply moves on; there is no counter for a case the loop cannot
+     *  reach.) */
+    joinNoKey: number;
+    /** Refused: the fact contains no entity that leads anywhere. */
+    joinNoEntity: number;
+    /** Times the reasoner pivoted on a span its answer contains and stepped
+     *  across that fact. */
+    pivotSteps: number;
+    /** `bridge` calls the cover makes assembling connectors (pairwise + n-ary). */
+    coverBridges: number;
+    /** Continuations a CHAIN hop offered the search.  Bounded by the question
+     *  (`ceil(queryLen / W)`) rather than by the corpus's fan-out — measured on a
+     *  hub of degree 1083, offering every continuation grew the chart to 3113 outs
+     *  and cost a 270 MB peak / 256 MB OOM for a two-word question. */
+    chainOffers: number;
+    /** Σ byte-allowance the n-ary interior passes those bridges.  The allowance
+     *  is `middleBytes + (m + 1) * W` — every intermediate answer's bytes plus
+     *  one window of glue per joint — so it is the quantity that grows with a hub
+     *  query's answers, and the first thing to read when the peak moves. */
+    coverAllowanceBytes: number;
     private readonly _phases;
     private readonly _t0;
     /** Every work counter's current value, by name — the snapshot `time`

package/dist/src/meter.js

@@ -149,6 +149,50 @@ export class Meter {
     mechanismRuns = 0;
     /** Candidates the decider weighed. */
     candidates = 0;
+    // ── Graph search: the fact join (DIRECTION) ─────────────────────────────
+    //
+    // The join's outcome was observable ONLY through the rationale, and the
+    // rationale PERTURBS the search (measured: appending text to a refusal note
+    // changed a traced answer).  These four counters are the untraced view — the
+    // same surface every other work counter uses, incremented where the decision
+    // is made, never behind a trace guard.
+    /** `deriveThrough` yielded — a fact was reached through the subject the query
+     *  never named. */
+    joinFired = 0;
+    /** Refused: no key names the entity and the tail together.  (A key that
+     *  resolves but leads nowhere is not "refused" — it is not the relation, so
+     *  the scan simply moves on; there is no counter for a case the loop cannot
+     *  reach.) */
+    joinNoKey = 0;
+    /** Refused: the fact contains no entity that leads anywhere. */
+    joinNoEntity = 0;
+    // ── Mind: the multi-hop pivot (EXTENSION) ───────────────────────────────
+    //
+    // `pivotStep` was observable only through the rationale, and the rationale
+    // perturbs the search (measured).  How far the reasoner hopped is a
+    // BEHAVIOUR, so it needs an untraced view: one counter, incremented where the
+    // step is emitted.
+    /** Times the reasoner pivoted on a span its answer contains and stepped
+     *  across that fact. */
+    pivotSteps = 0;
+    // ── Mind: the cover's connector assembly (LIMIT) ────────────────────────
+    //
+    // The cover's `run` is 91% of a hub query's time (`"Hello."`: 2.7 s of 3.0 s)
+    // and holds its ~270 MB peak, and none of it was countable: `searchPushes`
+    // and `candidates` do not see the connector assembly.  These two counters are
+    // the untraced view of it.
+    /** `bridge` calls the cover makes assembling connectors (pairwise + n-ary). */
+    coverBridges = 0;
+    /** Continuations a CHAIN hop offered the search.  Bounded by the question
+     *  (`ceil(queryLen / W)`) rather than by the corpus's fan-out — measured on a
+     *  hub of degree 1083, offering every continuation grew the chart to 3113 outs
+     *  and cost a 270 MB peak / 256 MB OOM for a two-word question. */
+    chainOffers = 0;
+    /** Σ byte-allowance the n-ary interior passes those bridges.  The allowance
+     *  is `middleBytes + (m + 1) * W` — every intermediate answer's bytes plus
+     *  one window of glue per joint — so it is the quantity that grows with a hub
+     *  query's answers, and the first thing to read when the peak moves. */
+    coverAllowanceBytes = 0;
     // ── Phases ──────────────────────────────────────────────────────────────
     _phases = new Map();
     _t0 = performance.now();

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

@@ -0,0 +1,40 @@
+import type { MindContext } from "./types.js";
+/** One stored experience pair, as bytes. */
+export interface CorpusPair {
+    context: Uint8Array;
+    continuation: Uint8Array;
+    contextId: number;
+    continuationId: number;
+    /** Bytes of the query this pair was matched on — 0 when browsing. */
+    matchedBytes: number;
+    /** True when the stored bytes ran past the declared preview capacity. */
+    contextTruncated: boolean;
+    continuationTruncated: boolean;
+}
+/** Why a search produced no pairs.  A STATE, so a caller's own layer can say it
+ *  in its own words — the byte layer does not speak. */
+export type CorpusMiss = "matched" | "nothing-resolved" | "no-continuations";
+export interface CorpusResult {
+    pairs: CorpusPair[];
+    /** Query subtrees that content-addressed to a real stored node. */
+    resolved: number;
+    /** Distinct edge-bearing contexts the climb reached. */
+    reached: number;
+    /** Distinct contexts that carry a learnt continuation, store-wide. */
+    totalContexts: number;
+    /** True when these are browse samples rather than search results. */
+    browsed: boolean;
+    miss: CorpusMiss;
+}
+/** Which stored notes does this query reach?  BYTES in, BYTES out.
+ *
+ *  Exact content addressing through the machinery that already exists: the
+ *  query's recognised sites are the resolved subtrees, the climb goes up from
+ *  the biggest first, and a pair is a context that carries a continuation. */
+export declare function searchCorpus(ctx: MindContext, queryBytes: Uint8Array, limit?: number): CorpusResult;
+/** Browse real pairs, striding the id space so the sample is spread rather than
+ *  one local cluster.  DETERMINISTIC: `from` is the caller's own offset, so
+ *  browsing twice with different offsets shows different notes without a random
+ *  draw (the demo drew `Math.random()`, which the engine cannot do — same seed,
+ *  same order, same query must mean the same answer). */
+export declare function sampleCorpus(ctx: MindContext, limit?: number, from?: number): CorpusResult;

package/dist/src/mind/corpus.js

@@ -0,0 +1,149 @@
+// corpus.ts — read the trained memory back out of the DAG, AS DATA.
+//
+// A trained experience pair IS one continuation edge: `src` is the context that
+// was deposited, `dst` is what the mind learnt follows it.  Reading them back
+// uses the store's own structure and its own indexes — no auxiliary index is
+// built, nothing is written, and NOTHING HERE KNOWS ABOUT TEXT: this layer takes
+// bytes and returns bytes.  The text case is one helper on the Mind
+// (`searchCorpusText`), which encodes, calls this, and decodes.
+//
+// WHERE EACH STAGE COMES FROM (ported from the demo's `explore.ts`, which
+// hand-rolled its own resolution):
+//
+//   1. PERCEIVE, CONTENT-ADDRESS and ADMIT the query — `recognise()`, the SAME
+//      machinery an answer goes through.  It returns the sites: the query spans
+//      that content-addressed to a stored node that can lead somewhere.  The
+//      demo's own recursive `findLeaf`/`findBranch` walk was a second
+//      implementation of exactly this, and it is NOT ported.
+//   2. CLIMB the structural `kid` table from each resolved site to the
+//      edge-bearing contexts above it (`edgeAncestors`, traverse.ts), weighting
+//      each context by how much query content reached it.
+//   3. READ the continuation off the edge table (`nextFirst`).
+//
+// COST is set by how much of the QUERY resolves, never by the size of the
+// store: the sites are what recognition already found, the climb is bounded by
+// the declared `corpusClimbs`/`corpusContextsPerClimb`, and every store call is
+// a point probe or a capped read.  All work is accounted by the store's own
+// meter hooks when a response's meter is open — there is no second instrument.
+//
+// WHAT THIS IS NOT.  Exact content addressing, not fuzzy keyword search: a query
+// shares results with a stored note when it shares actual chunk-aligned content
+// with it.  An arbitrary mid-word fragment resolves to nothing, and the honest
+// answer there is "nothing matched" — which is why `sampleCorpus` exists, and
+// why the miss is reported as a STATE rather than as prose (the text helper
+// turns it into words).
+import { recognise } from "./recognition.js";
+import { edgeAncestors } from "./traverse.js";
+/** A context node as a pair, or null when it carries no continuation. */
+function pairOf(ctx, id, matchedBytes) {
+    const outs = ctx.store.nextFirst(id, 1);
+    if (outs.length === 0)
+        return null;
+    const cap = ctx.cfg.corpusPreviewBytes;
+    const context = ctx.store.bytesPrefix(id, cap + 1);
+    const continuation = ctx.store.bytesPrefix(outs[0], cap + 1);
+    const contextTruncated = context.length > cap;
+    const continuationTruncated = continuation.length > cap;
+    return {
+        context: contextTruncated ? context.subarray(0, cap) : context,
+        continuation: continuationTruncated
+            ? continuation.subarray(0, cap)
+            : continuation,
+        contextId: id,
+        continuationId: outs[0],
+        matchedBytes,
+        contextTruncated,
+        continuationTruncated,
+    };
+}
+/** Which stored notes does this query reach?  BYTES in, BYTES out.
+ *
+ *  Exact content addressing through the machinery that already exists: the
+ *  query's recognised sites are the resolved subtrees, the climb goes up from
+ *  the biggest first, and a pair is a context that carries a continuation. */
+export function searchCorpus(ctx, queryBytes, limit) {
+    const store = ctx.store;
+    const want = Math.max(1, Math.min(limit ?? ctx.cfg.corpusContextsPerClimb, ctx.cfg.corpusLimitMax));
+    // A resolved subtree must account for at least one window (W): a single
+    // character resolves against almost any store and means nothing.  W is the
+    // mind's own line between chance and evidence — derived, never declared.
+    const floor = ctx.space.maxGroup;
+    const resolved = recognise(ctx, queryBytes).sites
+        .map((s) => ({ id: s.payload, len: store.contentLen(s.payload, 512) }))
+        .filter((r) => r.len >= floor);
+    // Biggest first, lowest id breaking ties: a clause is evidence, a character is
+    // noise, and equal evidence must not be decided by iteration order.
+    const byLength = resolved
+        .sort((a, b) => b.len - a.len || a.id - b.id)
+        .slice(0, ctx.cfg.corpusClimbs);
+    // Weight each context by how much query content reached it.
+    const weight = new Map();
+    for (const { id, len } of byLength) {
+        for (const root of edgeAncestors(ctx, id, ctx.cfg.corpusContextsPerClimb).roots) {
+            weight.set(root, (weight.get(root) ?? 0) + len);
+        }
+    }
+    const pairs = [];
+    const ranked = [...weight.entries()].sort((a, b) => b[1] - a[1] || a[0] - b[0]);
+    for (const [id, w] of ranked) {
+        if (pairs.length >= want)
+            break;
+        const pair = pairOf(ctx, id, w);
+        if (pair)
+            pairs.push(pair);
+    }
+    return {
+        pairs,
+        resolved: byLength.length,
+        reached: weight.size,
+        totalContexts: store.edgeSourceCount(),
+        browsed: false,
+        miss: pairs.length > 0
+            ? "matched"
+            : weight.size === 0
+                ? "nothing-resolved"
+                : "no-continuations",
+    };
+}
+/** Browse real pairs, striding the id space so the sample is spread rather than
+ *  one local cluster.  DETERMINISTIC: `from` is the caller's own offset, so
+ *  browsing twice with different offsets shows different notes without a random
+ *  draw (the demo drew `Math.random()`, which the engine cannot do — same seed,
+ *  same order, same query must mean the same answer). */
+export function sampleCorpus(ctx, limit, from = 0) {
+    const store = ctx.store;
+    const want = Math.max(1, Math.min(limit ?? ctx.cfg.corpusContextsPerClimb, ctx.cfg.corpusLimitMax));
+    const total = store.nodeCount();
+    const probes = ctx.cfg.corpusSampleProbes;
+    const floorBytes = ctx.cfg.corpusSampleFloorBytes;
+    const pairs = [];
+    // EACH CONTEXT AT MOST ONCE.  Striding the id space revisits ids when the
+    // store is small relative to the probe budget (measured: a 160-node store
+    // returned the SAME pair six times for `limit: 6`), and a browse that repeats
+    // itself is not a browse.  The demo had the same hole; it is invisible only on
+    // a store far larger than the probe budget.
+    const seen = new Set();
+    for (let i = 0; i < probes && pairs.length < want && total > 0; i++) {
+        const slot = (i / probes + from) % 1;
+        const id = Math.floor(slot * total);
+        if (seen.has(id))
+            continue;
+        if (!store.has(id) || !store.hasNext(id))
+            continue;
+        if (store.contentLen(id, floorBytes) < floorBytes)
+            continue;
+        const pair = pairOf(ctx, id, 0);
+        if (pair) {
+            seen.add(id);
+            pairs.push(pair);
+        }
+    }
+    return {
+        pairs,
+        resolved: 0,
+        reached: pairs.length,
+        totalContexts: store.edgeSourceCount(),
+        browsed: true,
+        miss: pairs.length > 0 ? "matched" : "no-continuations",
+    };
+}

package/dist/src/mind/graph-search.d.ts

@@ -162,6 +162,13 @@ export declare class GraphSearch {
      *  recursive completion), and chooseNext (distributional-evidence edge
      *  disambiguation when a recognised form has multiple continuations). */
     host: GraphSearchHost);
+    /** The nodes the QUERY canonically names — the same identity the store's keys
+     *  were written through.  A byte-exact test is not enough: the query writes
+     *  `Eiffel Tower country` and the deposited node is `eiffel tower country`, so
+     *  a join that filters the query's own subject by RAW bytes re-admits it —
+     *  measured: that is the trap's wrong answer (`The capital of Eiffel Tower
+     *  country is Berlin.`).  Cached by query identity, because the search is
+     *  reused across responses. */
     private hubBound;
     /** Explore the Sema graph for the lightest cover of the query and return its
      *  chosen spans left-to-right — WITH the derivation's total weight (the g