@hviana/sema 0.4.1 → 0.4.2

package/dist/src/index.d.ts

@@ -1,17 +0,0 @@
-export * from "./bytes.js";
-export * from "./vec.js";
-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";
-export * from "./config.js";
-export * from "./extension.js";
-export * from "./canon.js";
-export * from "./ingest-cache.js";
-export { IvfIndex, Prng, RaBitQuantizer, VectorDatabase, } from "./rabitq-ivf/src/index.js";
-export type { DatabaseOptions, ExternalId, IvfConfig, IvfHit, QueryContext, QueryResult, RaBitQOptions, StorageStats, } from "./rabitq-ivf/src/index.js";
-export * from "./derive/src/index.js";

package/dist/src/index.js

@@ -1,19 +0,0 @@
-// sema — an elementary, recursive, weight-free multimodal mind.
-// One structure, one verb, one memory. See AGENTS.md for the full algorithm.
-export * from "./bytes.js";
-export * from "./vec.js";
-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";
-export * from "./config.js";
-export * from "./extension.js";
-export * from "./canon.js";
-export * from "./ingest-cache.js";
-// rabitq-ivf: the partitioned (IVF) vector index over 1-bit RaBitQ codes.
-export { IvfIndex, Prng, RaBitQuantizer, VectorDatabase, } from "./rabitq-ivf/src/index.js";
-export * from "./derive/src/index.js";

package/dist/src/ingest-cache.d.ts

@@ -1,41 +0,0 @@
-import { Mind } from "./mind/index.js";
-import { type Sema } from "./sema.js";
-import type { Input } from "./mind/index.js";
-/**
- * An ingest cache layered over a Mind.
- *
- * Usage (drop-in for mind.ingest in training loops):
- *   const ci = new CachedIngest(mind);
- *   await ci.ingest(ctx, cont);       // caches both sides
- *   await ci.ingest("some text");     // caches the single text
- *   await ci.ingest([[ctx, cont]]);   // array form
- *
- * All other Mind methods (respond, save, …) are accessed on `ci.mind`.
- */
-export declare class CachedIngest {
-    readonly mind: Mind;
-    /** One unified, content-addressed memo of interned inputs.  Each value holds
-     *  Float32 root vector (D·4 bytes) plus a small id array, so the byte budget
-     *  is spent on the inputs most worth remembering (LRU). */
-    private _memo;
-    hits: number;
-    misses: number;
-    constructor(mind: Mind);
-    private newMemo;
-    private keyOf;
-    ingest(input: Input | (Input | [Input, Input])[], second?: Input): Promise<(Sema & {
-        id: number;
-    }) | undefined>;
-    /** Resolve an input to its interned nodes, from the memo when its content has
-     *  been seen before, else by the Mind's OWN untracked {@link deposit}
-     *  (perceive + intern + sub-span/containment indexing — identical to the
-     *  direct path; those writes are durable and idempotent, so a later memo hit
-     *  legitimately skips them).  This is the single expensive operation both
-     *  ingest paths share; caching it here is what makes every repeated input —
-     *  in any role — cheap. */
-    private resolveInput;
-    private ingestPair;
-    private ingestOne;
-    clear(): void;
-    get size(): number;
-}

package/dist/src/ingest-cache.js

@@ -1,161 +0,0 @@
-// ingest-cache.ts — ingest-level cache for Mind.
-//
-// Wraps a Mind and memoises the expensive, content-determined half of ingestion:
-// turning ONE input (a context, a continuation, or a bare experience) into its
-// interned graph nodes.  Perception (riverFold) and interning are a PURE function
-// of the input bytes — the same bytes always cut the same way and hash-cons to
-// the same node ids — so the result can be cached by content and reused wherever
-// those same bytes appear again, in ANY role.
-//
-// This is why the cache keys on the single input, not on the (context,
-// continuation) pair: real training corpora repeat content at the INPUT level far
-// more than at the pair level — a shared system/tool preamble in front of every
-// row, a common answer ("Yes.", a refusal) under many questions, an accumulated
-// dialogue prefix, an exactly-duplicated row.  A pair-level key sees none of these
-// (the pair as a whole is almost always unique); the input-level key catches them
-// all, and a context that recurs as a continuation (or vice versa) hits too.
-//
-// On a cache hit only the cheap relational writes are replayed — the edge and the
-// two halo pours for a pair, or the part-chain links for a single — while the
-// perceive + internTree work (the dominant cost, and on a large store the dominant
-// VECTOR-INDEX cost too) is skipped entirely.  The interned node ids are stable
-// across eviction: a re-perceive of evicted content reproduces the same ids by
-// the store's hash-cons, so correctness never depends on a hit.
-//
-// DEPOSITION IS THE MIND'S OWN: every miss goes through the same
-// {@link deposit} the direct Mind.ingest path uses — perception, interning,
-// sub-span/window indexing, durable CONTAINMENT edges, whole-stream flat
-// branch, changed-node tracking against the Mind's `_prevSeen` — so a store
-// trained through this cache is structurally IDENTICAL to one trained by
-// calling mind.ingest() directly (this class used to re-implement the deposit
-// and drifted: no indexSubSpans/addContainer, wrong part-link stride).  Only
-// the memo layer lives here.  Behaviour is identical to mind.ingest() (links
-// and halos are reinforced on every call), just faster when content repeats.
-import { deposit, dispatchIngest, ingestOne as depositOne, } from "./mind/learning.js";
-import { bindSeat, companySignature } from "./sema.js";
-import { BoundedMap } from "./store.js";
-/**
- * An ingest cache layered over a Mind.
- *
- * Usage (drop-in for mind.ingest in training loops):
- *   const ci = new CachedIngest(mind);
- *   await ci.ingest(ctx, cont);       // caches both sides
- *   await ci.ingest("some text");     // caches the single text
- *   await ci.ingest([[ctx, cont]]);   // array form
- *
- * All other Mind methods (respond, save, …) are accessed on `ci.mind`.
- */
-export class CachedIngest {
-    mind;
-    /** One unified, content-addressed memo of interned inputs.  Each value holds
-     *  Float32 root vector (D·4 bytes) plus a small id array, so the byte budget
-     *  is spent on the inputs most worth remembering (LRU). */
-    _memo;
-    hits = 0;
-    misses = 0;
-    constructor(mind) {
-        this.mind = mind;
-        this._memo = this.newMemo();
-    }
-    newMemo() {
-        return new BoundedMap(this.mind.cfg.store.ingestCacheBytes, (c) => c.rootV.byteLength + c.partIds.length * 4 + 8 + c.keyBytes);
-    }
-    // ── cache key ───────────────────────────────────────────────────────────
-    // Content key for an input, or null when the input cannot be keyed reliably
-    // — in which case it BYPASSES the cache (recomputed every time) rather than
-    // risk a collision returning the wrong nodes.  A string is its own key; raw
-    // bytes hash by FNV-1a (+ length, so a hash collision still needs an equal
-    // length to alias); a Grid / Grid[] has no cheap stable key, so it bypasses.
-    keyOf(input) {
-        if (typeof input === "string")
-            return "S:" + input;
-        if (input instanceof Uint8Array) {
-            // FNV-1a — no spread onto the call stack, safe on large binary inputs.
-            let h = 0x811c9dc5 >>> 0;
-            for (let i = 0; i < input.length; i++) {
-                h ^= input[i];
-                h = Math.imul(h, 0x01000193) >>> 0;
-            }
-            return "B:" + (h >>> 0).toString(16) + ":" + input.length;
-        }
-        return null; // Grid / Grid[] — bypass the cache
-    }
-    // ── public API ────────────────────────────────────────────────────────
-    async ingest(input, second) {
-        // One shape-reading for both ingest paths — see {@link dispatchIngest}.
-        return dispatchIngest(input, second, (i) => this.ingestOne(i), (a, b) => this.ingestPair(a, b));
-    }
-    // ── the one cached step: perceive + intern + index ONE input ──────────────
-    /** Resolve an input to its interned nodes, from the memo when its content has
-     *  been seen before, else by the Mind's OWN untracked {@link deposit}
-     *  (perceive + intern + sub-span/containment indexing — identical to the
-     *  direct path; those writes are durable and idempotent, so a later memo hit
-     *  legitimately skips them).  This is the single expensive operation both
-     *  ingest paths share; caching it here is what makes every repeated input —
-     *  in any role — cheap. */
-    async resolveInput(input) {
-        const key = this.keyOf(input);
-        if (key !== null) {
-            const cached = this._memo.get(key);
-            if (cached) {
-                this.hits++;
-                return cached;
-            }
-        }
-        this.misses++;
-        // The full deposit, untracked (a continuation must not break the tracked
-        // deposit chain).  `partIds` are the root's immediate children, already
-        // interned by the deposit — free to capture.  Only the root vector and
-        // ids are retained; the tree is GC'd.
-        const { tree, rootId, ids } = await deposit(this.mind, input, false);
-        const partIds = tree.kids
-            ? tree.kids.map((k) => ids.get(k))
-            : [rootId];
-        const entry = {
-            rootV: tree.v,
-            rootId,
-            partIds,
-            // ~2 bytes per UTF-16 code unit — the key is retained by the map.
-            keyBytes: key !== null ? key.length * 2 : 0,
-        };
-        if (key !== null)
-            this._memo.set(key, entry);
-        return entry;
-    }
-    // ── pair ingest ───────────────────────────────────────────────────────
-    async ingestPair(ctx, cont) {
-        // The CONTEXT side is TRACKED (it continues the Mind's deposit chain and
-        // is the growing, unique-per-turn side — a cache miss anyway), via the
-        // same {@link deposit} the direct path uses; the continuation resolves
-        // through the memo.
-        const c = await deposit(this.mind, ctx, true);
-        const b = await this.resolveInput(cont);
-        // EDGE on the FULL context (disambiguates a shared pivot). HALO only on the
-        // CHANGED NODES — the coherent new subtrees this turn adds — so a recurring
-        // shared prefix never collects halo mass. (See Mind.ingestPair.)
-        await this.mind.store.link(c.rootId, b.rootId);
-        // Halos pour company SIGNATURES (identity), not gists (content) — see
-        // companySignature in sema.ts.
-        const contSeat = bindSeat(this.mind.space, companySignature(this.mind.space, b.rootId), 1);
-        for (const part of c.changed) {
-            const partId = c.ids.get(part);
-            await this.mind.store.pourHalo(partId, contSeat);
-            await this.mind.store.pourHalo(b.rootId, bindSeat(this.mind.space, companySignature(this.mind.space, partId), 0));
-        }
-    }
-    // ── one-side ingest ───────────────────────────────────────────────────
-    async ingestOne(input) {
-        // A bare experience is the direct path verbatim — tracked deposit, root
-        // marked a resonance target, part chain linked at the maxGroup stride.
-        // (The tracked side is a memo miss by design, so there is nothing for the
-        // cache to add here.)
-        return depositOne(this.mind, input);
-    }
-    // ── helpers ───────────────────────────────────────────────────────────
-    clear() {
-        this._memo = this.newMemo();
-    }
-    get size() {
-        return this._memo.size;
-    }
-}

package/dist/src/meter.d.ts

@@ -1,171 +0,0 @@
-/** 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;