@seanhogg/builderforce-memory-engine 2026.6.31 → 2026.6.35

package/README.md

@@ -7,6 +7,8 @@
 
 `@seanhogg/builderforce-memory-engine` is a **TypeScript-first** library that brings the Mamba family of State Space Models to the browser via WebGPU. It ships **Mamba-2** (SSD), **Mamba-3** (complex-valued MIMO + ET discretisation), and **hybrid attention** layers, while remaining fully backward-compatible with Mamba-1 checkpoints. It is the zero-runtime-dep engine consumed by [`@seanhogg/builderforce-memory`](../memory) (the runtime layer).
 
+> **Technical report & peer review.** The kernels and discretisations here are specified mathematically in the Evermind technical report ([`../../publication/evermind/`](../../publication/evermind)). Its adversarial [`PEER-REVIEW.md`](../../publication/evermind/PEER-REVIEW.md) flags engine-level items worth knowing before depending on them at scale: the "parallel" selective scan walks tiles sequentially, `softplus` is the unstable `log(1+exp(v))` form, int8 quantisation uses a single per-tensor scale (weights only), and GPU buffers are allocated per call (no pool). Tracked as `EVM-1/EVM-8`.
+
 ---
 
 ## What's New in v2.0.0

package/dist/bench/harness.d.ts

@@ -0,0 +1,37 @@
+/**
+ * bench/harness.ts — run a benchmark and A/B two models.
+ *
+ * The harness drives a model over held-out token sequences, scores next-token
+ * prediction with {@link metrics}, and produces a {@link BenchmarkReport}. It
+ * also offers a one-call {@link trainAndBenchmark} that builds a fresh
+ * `EvermindLM` from a corpus, holds out a slice, trains on the rest, and scores
+ * — the path the Studio uses to benchmark a model in the browser.
+ */
+import type { AsyncLogitsModel, BenchmarkOptions, BenchmarkReport, ComparisonReport, LogitsModel, TrainAndBenchmarkOptions, TrainAndBenchmarkResult } from "./types.js";
+/**
+ * Benchmark a model (synchronous forward) over held-out token sequences.
+ * Sequences shorter than 2 tokens have no prediction target and are skipped.
+ */
+export declare function benchmarkModel(model: LogitsModel, sequences: number[][], opts?: BenchmarkOptions): BenchmarkReport;
+/** Benchmark a model whose forward pass is asynchronous (e.g. a WebGPU backend). */
+export declare function benchmarkModelAsync(model: AsyncLogitsModel, sequences: number[][], opts?: BenchmarkOptions): Promise<BenchmarkReport>;
+/** A/B two models on the same eval set. Lower perplexity wins (the primary metric). */
+export declare function compareModels(candidate: LogitsModel, baseline: LogitsModel, sequences: number[][], opts?: BenchmarkOptions): ComparisonReport;
+/** Build a {@link ComparisonReport} from two already-computed scorecards. */
+export declare function compareReports(candidate: BenchmarkReport, baseline: BenchmarkReport): ComparisonReport;
+/** Split a corpus into next-token training sequences (one per sentence). */
+export declare function corpusToSequences(corpus: string, codec: {
+    encode(text: string): number[];
+}): number[][];
+/** Benchmark an existing model against a raw-text corpus (tokenized per sentence). */
+export declare function benchmarkText(model: LogitsModel, codec: {
+    encode(text: string): number[];
+}, corpus: string, opts?: BenchmarkOptions): BenchmarkReport;
+/**
+ * Train a fresh `EvermindLM` on a corpus and benchmark it on a held-out slice —
+ * the canonical "build + score a model from text" path. A real benchmark must
+ * score data the model never trained on, so `heldOutRatio` is clamped to leave
+ * at least one eval sequence and one train sequence.
+ */
+export declare function trainAndBenchmark(corpus: string, opts?: TrainAndBenchmarkOptions): TrainAndBenchmarkResult;
+//# sourceMappingURL=harness.d.ts.map

package/dist/bench/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../src/bench/harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAqCpB;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EAAE,EAAE,EACrB,IAAI,GAAE,gBAAqB,GAC1B,eAAe,CAgBjB;AAED,oFAAoF;AACpF,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,MAAM,EAAE,EAAE,EACrB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,eAAe,CAAC,CAgB1B;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAC3B,SAAS,EAAE,WAAW,EACtB,QAAQ,EAAE,WAAW,EACrB,SAAS,EAAE,MAAM,EAAE,EAAE,EACrB,IAAI,GAAE,gBAAqB,GAC1B,gBAAgB,CAElB;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,eAAe,GAAG,gBAAgB,CAiBtG;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;IAAE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAE,GAAG,MAAM,EAAE,EAAE,CAKvG;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE;IAAE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAE,EACzC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,gBAAqB,GAC1B,eAAe,CAEjB;AAaD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,wBAA6B,GAClC,uBAAuB,CA0CzB"}

package/dist/bench/harness.js

@@ -0,0 +1,171 @@
+/**
+ * bench/harness.ts — run a benchmark and A/B two models.
+ *
+ * The harness drives a model over held-out token sequences, scores next-token
+ * prediction with {@link metrics}, and produces a {@link BenchmarkReport}. It
+ * also offers a one-call {@link trainAndBenchmark} that builds a fresh
+ * `EvermindLM` from a corpus, holds out a slice, trains on the rest, and scores
+ * — the path the Studio uses to benchmark a model in the browser.
+ */
+import { EvermindLM, EvermindLMTrainer } from "../lm/evermind_lm.js";
+import { BPETokenizer } from "../tokenizer/bpe.js";
+import { SeededRng } from "../utils/rng.js";
+import { newAccumulator, scoreInto, perplexity, bitsPerToken } from "./metrics.js";
+/** A monotonic clock, preferring `performance.now()` when present. */
+function defaultNow() {
+    const g = globalThis;
+    return typeof g.performance?.now === "function" ? g.performance.now() : Date.now();
+}
+/** Next-token targets for a sequence: tokens[1..T-1] predicted from positions 0..T-2. */
+function nextTokenTargets(seq) {
+    return seq.slice(1);
+}
+function finalize(acc, sequences, topK, elapsedMs) {
+    const meanCe = acc.tokens > 0 ? acc.ceSum / acc.tokens : 0;
+    const report = {
+        sequences,
+        tokens: acc.tokens,
+        crossEntropy: meanCe,
+        perplexity: perplexity(meanCe),
+        bitsPerToken: bitsPerToken(meanCe),
+        top1Accuracy: acc.tokens > 0 ? acc.top1Hits / acc.tokens : 0,
+        topKAccuracy: acc.tokens > 0 ? acc.topKHits / acc.tokens : 0,
+        topK,
+    };
+    if (elapsedMs !== undefined) {
+        report.elapsedMs = elapsedMs;
+        report.tokensPerSecond = elapsedMs > 0 ? (acc.tokens / elapsedMs) * 1000 : 0;
+    }
+    return report;
+}
+/**
+ * Benchmark a model (synchronous forward) over held-out token sequences.
+ * Sequences shorter than 2 tokens have no prediction target and are skipped.
+ */
+export function benchmarkModel(model, sequences, opts = {}) {
+    const topK = opts.topK ?? 5;
+    const measure = opts.measureLatency ?? true;
+    const now = opts.now ?? defaultNow;
+    const acc = newAccumulator();
+    let scored = 0;
+    let elapsed = 0;
+    for (const seq of sequences) {
+        if (seq.length < 2)
+            continue;
+        const t0 = measure ? now() : 0;
+        const { logits } = model.forward(seq);
+        if (measure)
+            elapsed += now() - t0;
+        scoreInto(acc, logits, nextTokenTargets(seq), topK);
+        scored++;
+    }
+    return finalize(acc, scored, topK, measure ? elapsed : undefined);
+}
+/** Benchmark a model whose forward pass is asynchronous (e.g. a WebGPU backend). */
+export async function benchmarkModelAsync(model, sequences, opts = {}) {
+    const topK = opts.topK ?? 5;
+    const measure = opts.measureLatency ?? true;
+    const now = opts.now ?? defaultNow;
+    const acc = newAccumulator();
+    let scored = 0;
+    let elapsed = 0;
+    for (const seq of sequences) {
+        if (seq.length < 2)
+            continue;
+        const t0 = measure ? now() : 0;
+        const { logits } = await model.forward(seq);
+        if (measure)
+            elapsed += now() - t0;
+        scoreInto(acc, logits, nextTokenTargets(seq), topK);
+        scored++;
+    }
+    return finalize(acc, scored, topK, measure ? elapsed : undefined);
+}
+/** A/B two models on the same eval set. Lower perplexity wins (the primary metric). */
+export function compareModels(candidate, baseline, sequences, opts = {}) {
+    return compareReports(benchmarkModel(candidate, sequences, opts), benchmarkModel(baseline, sequences, opts));
+}
+/** Build a {@link ComparisonReport} from two already-computed scorecards. */
+export function compareReports(candidate, baseline) {
+    const perplexityDelta = candidate.perplexity - baseline.perplexity;
+    const perplexityRatio = baseline.perplexity > 0 ? candidate.perplexity / baseline.perplexity : Infinity;
+    const top1Delta = candidate.top1Accuracy - baseline.top1Accuracy;
+    // A small relative band counts as a tie so noise doesn't flip the verdict.
+    const tieBand = 0.005;
+    let winner;
+    if (Math.abs(perplexityRatio - 1) <= tieBand)
+        winner = "tie";
+    else
+        winner = perplexityDelta < 0 ? "candidate" : "baseline";
+    const pct = ((1 - perplexityRatio) * 100).toFixed(1);
+    const summary = winner === "tie"
+        ? `Tie: perplexity ${candidate.perplexity.toFixed(2)} vs ${baseline.perplexity.toFixed(2)}`
+        : winner === "candidate"
+            ? `Candidate wins: ${pct}% lower perplexity (${candidate.perplexity.toFixed(2)} vs ${baseline.perplexity.toFixed(2)})`
+            : `Baseline wins: candidate ${(-Number(pct)).toFixed(1)}% higher perplexity (${candidate.perplexity.toFixed(2)} vs ${baseline.perplexity.toFixed(2)})`;
+    return { candidate, baseline, perplexityDelta, perplexityRatio, top1Delta, winner, summary };
+}
+/** Split a corpus into next-token training sequences (one per sentence). */
+export function corpusToSequences(corpus, codec) {
+    return corpus
+        .split(/(?<=\.)\s+/)
+        .map((s) => codec.encode(s.trim()))
+        .filter((ids) => ids.length >= 2);
+}
+/** Benchmark an existing model against a raw-text corpus (tokenized per sentence). */
+export function benchmarkText(model, codec, corpus, opts = {}) {
+    return benchmarkModel(model, corpusToSequences(corpus, codec), opts);
+}
+/** Deterministic Fisher–Yates shuffle (in place) driven by a seeded RNG. */
+function shuffle(arr, rng) {
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(rng.next() * (i + 1));
+        const tmp = arr[i];
+        arr[i] = arr[j];
+        arr[j] = tmp;
+    }
+    return arr;
+}
+/**
+ * Train a fresh `EvermindLM` on a corpus and benchmark it on a held-out slice —
+ * the canonical "build + score a model from text" path. A real benchmark must
+ * score data the model never trained on, so `heldOutRatio` is clamped to leave
+ * at least one eval sequence and one train sequence.
+ */
+export function trainAndBenchmark(corpus, opts = {}) {
+    const seed = opts.seed ?? 7;
+    const tok = new BPETokenizer();
+    tok.train(corpus, { numMerges: opts.numMerges ?? 100 });
+    const all = corpusToSequences(corpus, tok);
+    if (all.length < 2) {
+        throw new Error(`corpus produced ${all.length} trainable sequence(s); need at least 2 to hold out an eval split (add more sentences)`);
+    }
+    // Deterministic split: shuffle by seed, reserve heldOutRatio for eval.
+    const order = shuffle([...all], new SeededRng((seed >>> 0) || 1));
+    const ratio = Math.min(0.9, Math.max(0.05, opts.heldOutRatio ?? 0.25));
+    let evalCount = Math.round(order.length * ratio);
+    evalCount = Math.max(1, Math.min(order.length - 1, evalCount));
+    const evalSeqs = order.slice(0, evalCount);
+    const trainSeqs = order.slice(evalCount);
+    const model = new EvermindLM({
+        vocabSize: tok.vocabSize,
+        dModel: opts.dModel ?? 32,
+        numLayers: opts.numLayers ?? 2,
+        hiddenDim: opts.hiddenDim ?? 48,
+        seed,
+    });
+    const epochs = opts.epochs ?? 30;
+    const history = new EvermindLMTrainer(model, { lr: opts.lr ?? 0.03, epochs }).fit(trainSeqs);
+    const report = benchmarkModel(model, evalSeqs, { topK: opts.topK ?? 5, measureLatency: true });
+    const sample = model.generateText(opts.prompt ?? "The", tok, { maxNewTokens: 8, temperature: 0 });
+    return {
+        ...report,
+        trainSequences: trainSeqs.length,
+        evalSequences: evalSeqs.length,
+        initialTrainLoss: history[0] ?? 0,
+        finalTrainLoss: history.at(-1) ?? 0,
+        vocabSize: tok.vocabSize,
+        sample,
+    };
+}
+//# sourceMappingURL=harness.js.map

package/dist/bench/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","sourceRoot":"","sources":["../../src/bench/harness.ts"],"names":[],"mappings":"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"}

package/dist/bench/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * bench — the Evermind benchmarking harness.
+ *
+ * Measures a trained model on held-out data (perplexity, bits-per-token,
+ * next-token accuracy, throughput), A/Bs two models, and offers a one-call
+ * train-and-score path the Studio drives in the browser.
+ */
+export { benchmarkModel, benchmarkModelAsync, benchmarkText, compareModels, compareReports, corpusToSequences, trainAndBenchmark, } from "./harness.js";
+export { argmax, topKIndices, perplexity, bitsPerToken, newAccumulator, scoreInto, LN2, } from "./metrics.js";
+export type { LogitsModel, AsyncLogitsModel, BenchmarkOptions, BenchmarkReport, ComparisonReport, TrainAndBenchmarkOptions, TrainAndBenchmarkResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/bench/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bench/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,MAAM,EACN,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,EACd,SAAS,EACT,GAAG,GACJ,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/bench/index.js

@@ -0,0 +1,10 @@
+/**
+ * bench — the Evermind benchmarking harness.
+ *
+ * Measures a trained model on held-out data (perplexity, bits-per-token,
+ * next-token accuracy, throughput), A/Bs two models, and offers a one-call
+ * train-and-score path the Studio drives in the browser.
+ */
+export { benchmarkModel, benchmarkModelAsync, benchmarkText, compareModels, compareReports, corpusToSequences, trainAndBenchmark, } from "./harness.js";
+export { argmax, topKIndices, perplexity, bitsPerToken, newAccumulator, scoreInto, LN2, } from "./metrics.js";
+//# sourceMappingURL=index.js.map

package/dist/bench/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bench/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,MAAM,EACN,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,EACd,SAAS,EACT,GAAG,GACJ,MAAM,cAAc,CAAC"}

package/dist/bench/metrics.d.ts

@@ -0,0 +1,36 @@
+/**
+ * bench/metrics.ts — pure scoring primitives over per-position logits.
+ *
+ * These are the building blocks the harness composes. They are exact, allocation
+ * -light, and numerically stable (cross-entropy reuses the engine's stable
+ * log-sum-exp). Nothing here trains or mutates the model — benchmarking is a
+ * read-only forward pass over held-out data.
+ */
+/** Natural log of 2 — used to convert nats → bits. */
+export declare const LN2: number;
+/**
+ * Indices of the `k` largest logits, descending. O(V·k) — fine for the small
+ * top-k used in accuracy scoring; avoids a full sort of the vocab per position.
+ */
+export declare function topKIndices(logits: Float32Array, k: number): number[];
+/** Index of the single largest logit (argmax). */
+export declare function argmax(logits: Float32Array): number;
+/** Perplexity from a mean cross-entropy (nats). */
+export declare function perplexity(meanCrossEntropy: number): number;
+/** Bits-per-token from a mean cross-entropy (nats). */
+export declare function bitsPerToken(meanCrossEntropy: number): number;
+/** Accumulator over predicted positions — cross-entropy + top-1/top-k hits. */
+export interface ScoreAccumulator {
+    tokens: number;
+    ceSum: number;
+    top1Hits: number;
+    topKHits: number;
+}
+export declare function newAccumulator(): ScoreAccumulator;
+/**
+ * Score one (logits, targets) pair into the accumulator. `logits[t]` predicts
+ * `targets[t]`; positions with an out-of-range target are skipped. The caller
+ * aligns logits/targets (next-token: logits[0..T-2] predict tokens[1..T-1]).
+ */
+export declare function scoreInto(acc: ScoreAccumulator, logits: Float32Array[], targets: number[], k: number): void;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/bench/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/bench/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,sDAAsD;AACtD,eAAO,MAAM,GAAG,QAAW,CAAC;AAE5B;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAqBrE;AAED,kDAAkD;AAClD,wBAAgB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAUnD;AAED,mDAAmD;AACnD,wBAAgB,UAAU,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,cAAc,IAAI,gBAAgB,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,EAAE,MAAM,EAAE,EACjB,CAAC,EAAE,MAAM,GACR,IAAI,CAWN"}

package/dist/bench/metrics.js

@@ -0,0 +1,83 @@
+/**
+ * bench/metrics.ts — pure scoring primitives over per-position logits.
+ *
+ * These are the building blocks the harness composes. They are exact, allocation
+ * -light, and numerically stable (cross-entropy reuses the engine's stable
+ * log-sum-exp). Nothing here trains or mutates the model — benchmarking is a
+ * read-only forward pass over held-out data.
+ */
+import { crossEntropyLoss } from "../training/autograd.js";
+/** Natural log of 2 — used to convert nats → bits. */
+export const LN2 = Math.LN2;
+/**
+ * Indices of the `k` largest logits, descending. O(V·k) — fine for the small
+ * top-k used in accuracy scoring; avoids a full sort of the vocab per position.
+ */
+export function topKIndices(logits, k) {
+    const n = logits.length;
+    const kk = Math.max(1, Math.min(k, n));
+    const idx = [];
+    const used = new Uint8Array(n);
+    for (let s = 0; s < kk; s++) {
+        let best = -1;
+        let bestVal = -Infinity;
+        for (let i = 0; i < n; i++) {
+            if (used[i])
+                continue;
+            const v = logits[i];
+            if (v > bestVal) {
+                bestVal = v;
+                best = i;
+            }
+        }
+        if (best < 0)
+            break;
+        used[best] = 1;
+        idx.push(best);
+    }
+    return idx;
+}
+/** Index of the single largest logit (argmax). */
+export function argmax(logits) {
+    let best = 0;
+    let bestVal = -Infinity;
+    for (let i = 0; i < logits.length; i++) {
+        if (logits[i] > bestVal) {
+            bestVal = logits[i];
+            best = i;
+        }
+    }
+    return best;
+}
+/** Perplexity from a mean cross-entropy (nats). */
+export function perplexity(meanCrossEntropy) {
+    return Math.exp(meanCrossEntropy);
+}
+/** Bits-per-token from a mean cross-entropy (nats). */
+export function bitsPerToken(meanCrossEntropy) {
+    return meanCrossEntropy / LN2;
+}
+export function newAccumulator() {
+    return { tokens: 0, ceSum: 0, top1Hits: 0, topKHits: 0 };
+}
+/**
+ * Score one (logits, targets) pair into the accumulator. `logits[t]` predicts
+ * `targets[t]`; positions with an out-of-range target are skipped. The caller
+ * aligns logits/targets (next-token: logits[0..T-2] predict tokens[1..T-1]).
+ */
+export function scoreInto(acc, logits, targets, k) {
+    const n = Math.min(logits.length, targets.length);
+    for (let t = 0; t < n; t++) {
+        const target = targets[t];
+        const lg = logits[t];
+        if (target < 0 || target >= lg.length)
+            continue;
+        acc.ceSum += crossEntropyLoss(lg, target);
+        if (argmax(lg) === target)
+            acc.top1Hits++;
+        if (topKIndices(lg, k).includes(target))
+            acc.topKHits++;
+        acc.tokens++;
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/bench/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/bench/metrics.ts"],"names":[],"mappings":"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"}

package/dist/bench/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * bench/types.ts — public types for the Evermind benchmarking harness.
+ *
+ * Benchmarking answers the question the marketplace (and the "beats a frozen
+ * LLM" thesis) actually rests on: *how good is this model?* The harness measures
+ * a trained model on held-out data with the standard language-model yardsticks —
+ * perplexity, bits-per-token, and next-token accuracy — plus generation
+ * throughput, and can A/B two models (e.g. a quantized vs full-precision build,
+ * or a freshly-adapted vs prior checkpoint).
+ *
+ * The metrics operate on any object that can produce per-position logits from a
+ * token sequence — the engine's `EvermindLM` satisfies {@link LogitsModel}
+ * directly — so the harness is model-agnostic and dependency-free.
+ */
+/** The minimal surface a model must expose to be benchmarked: per-position logits. */
+export interface LogitsModel {
+    /** Run the model over a token sequence; returns one logit vector per position. */
+    forward(tokens: number[]): {
+        logits: Float32Array[];
+    };
+}
+/** A model whose forward pass is asynchronous (e.g. a WebGPU backend). */
+export interface AsyncLogitsModel {
+    forward(tokens: number[]): Promise<{
+        logits: Float32Array[];
+    }>;
+}
+/** Knobs for a benchmark run. */
+export interface BenchmarkOptions {
+    /** k for top-k next-token accuracy. Default 5. */
+    topK?: number;
+    /** Measure forward throughput (tokens/sec). Default true. */
+    measureLatency?: boolean;
+    /**
+     * Monotonic clock in milliseconds, injectable for deterministic tests.
+     * Defaults to `performance.now()` when available, else `Date.now()`.
+     */
+    now?: () => number;
+}
+/** The scorecard a benchmark run produces. */
+export interface BenchmarkReport {
+    /** Number of evaluated sequences. */
+    sequences: number;
+    /** Number of predicted positions (next-token targets) scored. */
+    tokens: number;
+    /** Mean next-token cross-entropy, in nats. Lower is better. */
+    crossEntropy: number;
+    /** Perplexity = exp(crossEntropy). Lower is better; 1.0 is perfect. */
+    perplexity: number;
+    /** Bits per token = crossEntropy / ln(2). Lower is better. */
+    bitsPerToken: number;
+    /** Fraction of positions where the argmax prediction was correct (0..1). */
+    top1Accuracy: number;
+    /** Fraction of positions where the true token was in the top-k (0..1). */
+    topKAccuracy: number;
+    /** The k used for {@link topKAccuracy}. */
+    topK: number;
+    /** Forward throughput in tokens/sec, when {@link BenchmarkOptions.measureLatency}. */
+    tokensPerSecond?: number;
+    /** Wall-clock spent in the forward passes (ms), when measured. */
+    elapsedMs?: number;
+}
+/** The result of A/B-ing two models on the same eval set. */
+export interface ComparisonReport {
+    candidate: BenchmarkReport;
+    baseline: BenchmarkReport;
+    /** candidate.perplexity − baseline.perplexity (negative = candidate better). */
+    perplexityDelta: number;
+    /** candidate.perplexity / baseline.perplexity (<1 = candidate better). */
+    perplexityRatio: number;
+    /** candidate.top1Accuracy − baseline.top1Accuracy (positive = candidate better). */
+    top1Delta: number;
+    /** Which model won on perplexity (the primary metric). */
+    winner: "candidate" | "baseline" | "tie";
+    /** Human-readable one-liner. */
+    summary: string;
+}
+/** Options for {@link trainAndBenchmark}: train a fresh EvermindLM, then score it. */
+export interface TrainAndBenchmarkOptions {
+    /** BPE merges to learn for the tokenizer. Default 100. */
+    numMerges?: number;
+    /** Model channel dimension. Default 32. */
+    dModel?: number;
+    /** Number of (conv + MoE) blocks. Default 2. */
+    numLayers?: number;
+    /** MoE expert FFN hidden width. Default 48. */
+    hiddenDim?: number;
+    /** Training epochs. Default 30. */
+    epochs?: number;
+    /** AdamW learning rate. Default 0.03. */
+    lr?: number;
+    /** Deterministic seed (model init + held-out split). Default 7. */
+    seed?: number;
+    /**
+     * Fraction of sequences reserved for evaluation (never trained on). Default
+     * 0.25. A real benchmark must score held-out data, so this is enforced > 0.
+     */
+    heldOutRatio?: number;
+    /** k for top-k accuracy. Default 5. */
+    topK?: number;
+    /** Prompt used to capture a qualitative generation sample. Default "The". */
+    prompt?: string;
+}
+/** {@link trainAndBenchmark} result: the held-out scorecard plus training context. */
+export interface TrainAndBenchmarkResult extends BenchmarkReport {
+    /** Sequences used for training. */
+    trainSequences: number;
+    /** Held-out sequences used for evaluation. */
+    evalSequences: number;
+    /** Final-epoch mean training loss (nats). */
+    finalTrainLoss: number;
+    /** First-epoch mean training loss (nats) — pairs with final to show the drop. */
+    initialTrainLoss: number;
+    /** Learned tokenizer vocabulary size. */
+    vocabSize: number;
+    /** A short greedy generation from {@link TrainAndBenchmarkOptions.prompt}. */
+    sample: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/bench/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bench/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG;QAAE,MAAM,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;CACvD;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,eAAe,CAAC;IAC3B,QAAQ,EAAE,eAAe,CAAC;IAC1B,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC;IACzC,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sFAAsF;AACtF,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,sFAAsF;AACtF,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/bench/types.js

@@ -0,0 +1,16 @@
+/**
+ * bench/types.ts — public types for the Evermind benchmarking harness.
+ *
+ * Benchmarking answers the question the marketplace (and the "beats a frozen
+ * LLM" thesis) actually rests on: *how good is this model?* The harness measures
+ * a trained model on held-out data with the standard language-model yardsticks —
+ * perplexity, bits-per-token, and next-token accuracy — plus generation
+ * throughput, and can A/B two models (e.g. a quantized vs full-precision build,
+ * or a freshly-adapted vs prior checkpoint).
+ *
+ * The metrics operate on any object that can produce per-position logits from a
+ * token sequence — the engine's `EvermindLM` satisfies {@link LogitsModel}
+ * directly — so the harness is model-agnostic and dependency-free.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/bench/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/bench/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/export/gguf.d.ts

@@ -0,0 +1,23 @@
+/**
+ * export/gguf.ts — export weights to a GGUF v3 container (the llama.cpp format).
+ *
+ * Emits a spec-valid GGUF file: magic + version, KV metadata (architecture, dims,
+ * expert counts…), aligned tensor-info table, then aligned tensor data. ggml
+ * stores dimensions innermost-first, so row-major shapes are reversed here.
+ *
+ * NOTE: GGUF is a *container*. llama.cpp can only RUN a file whose
+ * `general.architecture` it has a graph for; "evermind" is custom, so this file
+ * is a valid, inspectable artifact (gguf tooling reads it) but won't execute in
+ * stock llama.cpp until the architecture is upstreamed. It exists so the same
+ * weights can travel through GGUF-native tooling. For an executable export use
+ * {@link ./onnx} or {@link ./safetensors}.
+ */
+import type { EvermindLM } from "../lm/evermind_lm.js";
+export interface GgufOptions {
+    name?: string;
+    /** Store tensors as float16 (ggml type F16). Default false (F32). */
+    fp16?: boolean;
+}
+/** Export a trained LM to GGUF bytes. */
+export declare function exportGguf(lm: EvermindLM, opts?: GgufOptions): Uint8Array;
+//# sourceMappingURL=gguf.d.ts.map

package/dist/export/gguf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gguf.d.ts","sourceRoot":"","sources":["../../src/export/gguf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAevD,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AA+DD,yCAAyC;AACzC,wBAAgB,UAAU,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,GAAE,WAAgB,GAAG,UAAU,CAqE7E"}