@seanhogg/builderforce-memory-engine 2026.7.12 → 2026.9.27

package/dist/kernels/selective_scan.js.map

@@ -1 +1 @@
-{"version":3,"file":"selective_scan.js","sourceRoot":"","sources":["../../src/kernels/selective_scan.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,qEAAqE;AACrE,4EAA4E;AAC5E,EAAE;AACF,2BAA2B;AAC3B,oCAAoC;AACpC,8BAA8B;AAC9B,EAAE;AACF,qEAAqE;AAErE,MAAM,CAAC,MAAM,2BAA2B,GAAW,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2N5D,CAAC;AAEF,gDAAgD;AAChD,uEAAuE;AAEvE,MAAM,CAAC,MAAM,4BAA4B,GAAW,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6H7D,CAAC"}
+{"version":3,"file":"selective_scan.js","sourceRoot":"","sources":["../../src/kernels/selective_scan.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,qEAAqE;AACrE,4EAA4E;AAC5E,EAAE;AACF,2BAA2B;AAC3B,oCAAoC;AACpC,8BAA8B;AAC9B,EAAE;AACF,qEAAqE;AAErE,MAAM,CAAC,MAAM,2BAA2B,GAAW,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiO5D,CAAC;AAEF,gDAAgD;AAChD,uEAAuE;AAEvE,MAAM,CAAC,MAAM,4BAA4B,GAAW,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6H7D,CAAC"}

package/dist/kernels/slice.d.ts

@@ -0,0 +1,26 @@
+/**
+ * slice.ts — strided COLUMN slice of a row-major (rows, stride) tensor.
+ *
+ * Every block in this engine projects into one fused tensor and then splits it:
+ * Mamba-1 into (x, z) and (Δ, B, C), Mamba-2/3 into (x, Δ) and (x, B, C),
+ * attention into (Q, K, V). `LINEAR_FORWARD_WGSL` writes its output `(M, N)`
+ * ROW-major, so each of those parts is a contiguous range of COLUMNS **within
+ * every row** — not a contiguous range of the buffer.
+ *
+ * Splitting them with `copyBufferToBuffer` therefore took whole ROWS instead: it
+ * is only the right answer when `M == 1` (batch × seq_len), and for any real
+ * sequence it silently handed the block the wrong tensor. This kernel is the one
+ * correct implementation; every block uses it.
+ */
+export declare const COL_SLICE_WGSL: string;
+/** Entry point name of {@link COL_SLICE_WGSL}. */
+export declare const COL_SLICE_ENTRY = "col_slice";
+/**
+ * `dst[r, 0..width) = src[r, offset..offset+width)` for every row.
+ *
+ * @param pipeline a pipeline built from {@link COL_SLICE_WGSL} / {@link COL_SLICE_ENTRY}
+ * @param rows     batch * seqLen
+ * @param stride   source row width (the fused projection's output features)
+ */
+export declare function dispatchColumnSlice(device: GPUDevice, pipeline: GPUComputePipeline, src: GPUBuffer, dst: GPUBuffer, rows: number, stride: number, offset: number, width: number): void;
+//# sourceMappingURL=slice.d.ts.map

package/dist/kernels/slice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slice.d.ts","sourceRoot":"","sources":["../../src/kernels/slice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,eAAO,MAAM,cAAc,EAAE,MAoB5B,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,eAAe,cAAc,CAAC;AAE3C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACd,IAAI,CAKN"}

package/dist/kernels/slice.js

@@ -0,0 +1,52 @@
+/**
+ * slice.ts — strided COLUMN slice of a row-major (rows, stride) tensor.
+ *
+ * Every block in this engine projects into one fused tensor and then splits it:
+ * Mamba-1 into (x, z) and (Δ, B, C), Mamba-2/3 into (x, Δ) and (x, B, C),
+ * attention into (Q, K, V). `LINEAR_FORWARD_WGSL` writes its output `(M, N)`
+ * ROW-major, so each of those parts is a contiguous range of COLUMNS **within
+ * every row** — not a contiguous range of the buffer.
+ *
+ * Splitting them with `copyBufferToBuffer` therefore took whole ROWS instead: it
+ * is only the right answer when `M == 1` (batch × seq_len), and for any real
+ * sequence it silently handed the block the wrong tensor. This kernel is the one
+ * correct implementation; every block uses it.
+ */
+import { createBindGroup, createUniformBuffer, dispatchKernel, cdiv } from '../utils/gpu_utils.js';
+export const COL_SLICE_WGSL = /* wgsl */ `
+struct SliceParams {
+    rows   : u32,
+    stride : u32,   // source row width
+    offset : u32,   // first column to take
+    width  : u32,   // number of columns to take
+};
+@group(0) @binding(0) var<uniform>             p   : SliceParams;
+@group(0) @binding(1) var<storage, read>       src : array<f32>;
+@group(0) @binding(2) var<storage, read_write> dst : array<f32>;
+
+// Dispatch: (ceil(rows * width / 256), 1, 1)
+@compute @workgroup_size(256)
+fn col_slice(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let i = gid.x;
+    if (i >= p.rows * p.width) { return; }
+    let r = i / p.width;
+    let c = i % p.width;
+    dst[i] = src[r * p.stride + p.offset + c];
+}
+`;
+/** Entry point name of {@link COL_SLICE_WGSL}. */
+export const COL_SLICE_ENTRY = 'col_slice';
+/**
+ * `dst[r, 0..width) = src[r, offset..offset+width)` for every row.
+ *
+ * @param pipeline a pipeline built from {@link COL_SLICE_WGSL} / {@link COL_SLICE_ENTRY}
+ * @param rows     batch * seqLen
+ * @param stride   source row width (the fused projection's output features)
+ */
+export function dispatchColumnSlice(device, pipeline, src, dst, rows, stride, offset, width) {
+    const pBuf = createUniformBuffer(device, new Uint32Array([rows, stride, offset, width]).buffer);
+    const bg = createBindGroup(device, pipeline, [pBuf, src, dst]);
+    dispatchKernel(device, pipeline, bg, [cdiv(rows * width, 256), 1, 1]);
+    pBuf.destroy();
+}
+//# sourceMappingURL=slice.js.map

package/dist/kernels/slice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slice.js","sourceRoot":"","sources":["../../src/kernels/slice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAEnG,MAAM,CAAC,MAAM,cAAc,GAAW,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;CAoB/C,CAAC;AAEF,kDAAkD;AAClD,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAC/B,MAAiB,EACjB,QAA4B,EAC5B,GAAc,EACd,GAAc,EACd,IAAY,EACZ,MAAc,EACd,MAAc,EACd,KAAa;IAEb,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,EAAE,IAAI,WAAW,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAChG,MAAM,EAAE,GAAG,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC/D,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACtE,IAAI,CAAC,OAAO,EAAE,CAAC;AACnB,CAAC"}

package/dist/kernels/weight_update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"weight_update.d.ts","sourceRoot":"","sources":["../../src/kernels/weight_update.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,kBAAkB,EAAE,MAmEhC,CAAC;AAIF,eAAO,MAAM,cAAc,EAAE,MAyD5B,CAAC"}
+{"version":3,"file":"weight_update.d.ts","sourceRoot":"","sources":["../../src/kernels/weight_update.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,kBAAkB,EAAE,MAmEhC,CAAC;AAkBF,eAAO,MAAM,cAAc,EAAE,MAqE5B,CAAC"}

package/dist/kernels/weight_update.js

@@ -77,6 +77,20 @@ fn adamw_update(
 `;
 // Gradient clipping kernel – clips global gradient norm to max_norm.
 // Run before weight updates.  Two-pass: first compute squared norm, then scale.
+//
+// The accumulator is a REAL atomic. It used to be a plain `array<f32>` written as
+// `norm_sq[0] = norm_sq[0] + local_sq[0]` by the lane-0 invocation of every
+// workgroup — a read-modify-write with no synchronisation, so with more than one
+// workgroup (i.e. any tensor above 256 elements) concurrent workgroups lost each
+// other's contributions and the norm came out too SMALL, under-clipping exactly
+// when clipping matters most. WGSL has no `atomic<f32>`, so the accumulator is an
+// `atomic<u32>` holding the f32 bit pattern and updated with a
+// compare-exchange loop — the standard portable float-atomic-add.
+//
+// Summation ORDER across workgroups is not deterministic (floating-point addition
+// is not associative), so the norm can differ in the last ulp or two between runs.
+// That is fine for a clip threshold and is the accepted trade for correctness;
+// nothing downstream depends on a bit-exact norm.
 export const GRAD_CLIP_WGSL = /* wgsl */ `
 
 struct ClipParams {
@@ -86,10 +100,23 @@ struct ClipParams {
 
 @group(0) @binding(0) var<uniform>             clip_p  : ClipParams;
 @group(0) @binding(1) var<storage, read_write> grad    : array<f32>;
-@group(0) @binding(2) var<storage, read_write> norm_sq : array<f32>;  // size 1, atomic accumulator
+// size 1 – the f32 bit pattern of the accumulated sum of squares, updated
+// atomically. Zero-initialise it by writing 0.0f (bit pattern 0x00000000).
+@group(0) @binding(2) var<storage, read_write> norm_sq : array<atomic<u32>>;
 
 var<workgroup> local_sq : array<f32, 256>;
 
+// Portable atomic add on an f32 stored as its u32 bit pattern.
+fn atomic_add_f32(value: f32) {
+    var old_bits : u32 = atomicLoad(&norm_sq[0]);
+    loop {
+        let new_bits = bitcast<u32>(bitcast<f32>(old_bits) + value);
+        let res = atomicCompareExchangeWeak(&norm_sq[0], old_bits, new_bits);
+        if (res.exchanged) { break; }
+        old_bits = res.old_value;
+    }
+}
+
 // Pass 1: reduce sum of squares into norm_sq[0]
 @compute @workgroup_size(256, 1, 1)
 fn grad_norm_reduce(
@@ -115,8 +142,7 @@ fn grad_norm_reduce(
     }
 
     if (lid == 0u) {
-        // Non-atomic accumulation (single workgroup assumption for small models)
-        norm_sq[0] = norm_sq[0] + local_sq[0];
+        atomic_add_f32(local_sq[0]);
     }
 }
 
@@ -128,7 +154,7 @@ fn grad_clip_scale(
     let i = gid.x;
     if (i >= clip_p.num_elements) { return; }
 
-    let ns = norm_sq[0];
+    let ns = bitcast<f32>(atomicLoad(&norm_sq[0]));
     if (ns > clip_p.max_norm_sq) {
         let scale = sqrt(clip_p.max_norm_sq / ns);
         grad[i] = grad[i] * scale;

package/dist/kernels/weight_update.js.map

@@ -1 +1 @@
-{"version":3,"file":"weight_update.js","sourceRoot":"","sources":["../../src/kernels/weight_update.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,sDAAsD;AACtD,EAAE;AACF,qBAAqB;AACrB,8CAA8C;AAC9C,gDAAgD;AAChD,gCAAgC;AAChC,gCAAgC;AAChC,uFAAuF;AAEvF,MAAM,CAAC,MAAM,kBAAkB,GAAW,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmEnD,CAAC;AAEF,qEAAqE;AACrE,gFAAgF;AAChF,MAAM,CAAC,MAAM,cAAc,GAAW,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyD/C,CAAC"}
+{"version":3,"file":"weight_update.js","sourceRoot":"","sources":["../../src/kernels/weight_update.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,sDAAsD;AACtD,EAAE;AACF,qBAAqB;AACrB,8CAA8C;AAC9C,gDAAgD;AAChD,gCAAgC;AAChC,gCAAgC;AAChC,uFAAuF;AAEvF,MAAM,CAAC,MAAM,kBAAkB,GAAW,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmEnD,CAAC;AAEF,qEAAqE;AACrE,gFAAgF;AAChF,EAAE;AACF,kFAAkF;AAClF,4EAA4E;AAC5E,iFAAiF;AACjF,iFAAiF;AACjF,gFAAgF;AAChF,kFAAkF;AAClF,+DAA+D;AAC/D,kEAAkE;AAClE,EAAE;AACF,kFAAkF;AAClF,mFAAmF;AACnF,+EAA+E;AAC/E,kDAAkD;AAClD,MAAM,CAAC,MAAM,cAAc,GAAW,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqE/C,CAAC"}

package/dist/lm/evermind_lm.d.ts

@@ -21,6 +21,7 @@
  * acceleration with the same shapes.
  */
 import { type AdamWOptions } from "../optim/adamw.js";
+import { DynamicLossScaler, type LossScalerOptions } from "../training/mixed_precision.js";
 export interface EvermindLMConfig {
     /** Vocabulary size (the only required field; everything else has a default). */
     vocabSize: number;
@@ -81,8 +82,34 @@ export interface LMGenerateOptions {
     /** Stop generating when this token id is produced. */
     stopToken?: number;
 }
+/**
+ * Incremental decode state — everything a continuation needs from the prefix.
+ *
+ * The model's only cross-position dependency is the depthwise causal conv, whose
+ * receptive field is `convKernel` positions, so the entire "KV cache" is the
+ * trailing `convKernel - 1` normalised conv inputs per layer. That makes an exact
+ * prefix cache cheap: process a prompt once, then extend it with each candidate
+ * continuation for the cost of the candidate alone.
+ */
+export interface EvermindLMDecodeState {
+    /** [layer][slot] the trailing `convKernel - 1` RMSNormed conv inputs, oldest first. */
+    convWindow: Float32Array[][];
+    /** Positions consumed so far. */
+    length: number;
+    /** Logits at the LAST consumed position — what predicts the next token. */
+    lastLogits: Float32Array | null;
+}
 export declare class EvermindLM {
     readonly config: Required<Omit<EvermindLMConfig, "seed">>;
+    /**
+     * Token-positions pushed through a block since the last {@link resetStats}.
+     *
+     * The cost metric that matters for the tool-calling path: scoring N candidate
+     * tool names used to replay the WHOLE prompt N times, so this counted
+     * N x (prompt + candidate) x layers. With {@link stepDecode} the prompt is paid
+     * for once. Exposed so a benchmark can assert the saving rather than assume it.
+     */
+    private _positionsEvaluated;
     /** Tied token embedding / output head: vocabSize × dModel (row-major). */
     emb: Float32Array;
     private gEmb;
@@ -97,17 +124,124 @@ export declare class EvermindLM {
     /** Per-layer channel mixer. */
     private readonly moe;
     constructor(config: EvermindLMConfig);
+    /** Embed a token sequence into per-position channel vectors. */
+    private _embed;
+    /**
+     * One (conv + MoE) block: pre-norm → depthwise causal conv → residual, then
+     * pre-norm → MoE channel mixer → residual. Returns the block output and the
+     * activation cache its backward needs. Isolating this is what lets
+     * {@link lossAndBackwardCheckpointed} recompute a layer's activations on demand
+     * instead of retaining every layer's cache at once.
+     */
+    private _forwardLayer;
+    /**
+     * ONE position through one (conv + MoE) block, given the trailing conv window.
+     *
+     * The single place the block's maths lives: the batch path
+     * ({@link _forwardLayer}, which needs the full activation cache for backward)
+     * and the incremental path ({@link stepDecode}, which needs none of it) both
+     * run this, so they cannot drift apart. `window` holds the previous
+     * `convKernel - 1` RMSNormed conv inputs, OLDEST FIRST, and is advanced in
+     * place — a shorter window is exactly the causal zero-padding at the start of
+     * a sequence.
+     */
+    private _stepLayerPosition;
+    /** One token's embedding row (a copy — callers write into it). */
+    private _embedOne;
+    /** Tied output head: logits_t[v] = x_t · emb[v]. */
+    private _head;
     /** Run the model over a token sequence; returns per-position logits + a cache. */
     forward(tokens: number[]): {
         logits: Float32Array[];
         cache: ForwardCache;
     };
+    /**
+     * Produces a single fixed-length embedding vector for a token sequence — the
+     * CPU counterpart of `HybridMambaModel.embed()`, to the same contract.
+     *
+     * Runs the full block stack and takes the final hidden state — i.e. exactly the
+     * state the tied LM head consumes in {@link forward} — then mean-pools across
+     * sequence positions and L2-normalises. The result has length `dModel`, so
+     * cosine similarity between two embeddings reduces to a dot product.
+     *
+     * Like the GPU path it skips the (expensive) head projection: it only needs the
+     * `dModel`-wide hidden state, not `vocabSize` logits. Unlike the GPU path it
+     * needs no WebGPU device at all, which is what lets a headless host (the stdio
+     * MCP server) rank recall by SSM embedding instead of word overlap.
+     *
+     * Streamed one position at a time through the SHARED block implementation
+     * ({@link _stepLayerPosition}, the same routine {@link forward} and
+     * {@link stepDecode} run), so it can never drift from them and it retains no
+     * per-position activation cache.
+     *
+     * The embedding reflects whatever the model currently knows — an untrained
+     * model behaves like a random projection of the token embeddings (still
+     * lexically discriminative), and the representation sharpens as the model is
+     * adapted/distilled.
+     */
+    embed(tokenIds: number[] | Uint32Array): Float32Array;
+    /** Text-level embedding: encode with `codec`, then {@link embed}. */
+    embedText(text: string, codec: TextCodec): Float32Array;
+    /**
+     * Head + tied-embedding gradient. Accumulates dL/d(head→emb) into gEmb and
+     * returns the mean next-token loss plus dL/d(finalX). Shared by the full and
+     * checkpointed backward paths so the head maths lives in one place.
+     */
+    private _headBackward;
+    /**
+     * Backward through one (conv + MoE) block given dL/d(block output) and the
+     * block's activation cache. Accumulates conv/norm/MoE gradients and returns
+     * dL/d(block input). The inverse of {@link _forwardLayer}.
+     */
+    private _backwardLayer;
+    /** Embedding lookup: dL/d(layer-0 input) flows into the row for each token. */
+    private _embedBackward;
     /**
      * Next-token cross-entropy over the sequence (predict tokens[t+1] from
      * position t), accumulating exact gradients. Returns the mean loss. Call
      * {@link zeroGrad} before and an optimiser step after.
      */
     lossAndBackward(tokens: number[]): number;
+    /**
+     * Activation-checkpointed backward — numerically identical gradients to
+     * {@link lossAndBackward}, but retains only the per-LAYER inputs during the
+     * forward instead of every layer's full activation cache. Each layer's
+     * activations are RECOMPUTED (a cheap extra forward) when its backward runs,
+     * so peak activation memory is one layer's cache, not all of them. This is the
+     * memory-for-compute trade the cookbook pairs with FSDP to fit longer
+     * sequences / bigger models on a constrained device.
+     */
+    lossAndBackwardCheckpointed(tokens: number[]): number;
+    /** Positions pushed through a block since the last {@link resetStats}. */
+    get positionsEvaluated(): number;
+    resetStats(): void;
+    /** An empty decode state — the start of a sequence. */
+    newDecodeState(): EvermindLMDecodeState;
+    /** Deep copy, so one prefix state can seed many independent continuations. */
+    cloneDecodeState(state: EvermindLMDecodeState): EvermindLMDecodeState;
+    /**
+     * Consume `tokens` from `state`, returning the per-position logits and the
+     * ADVANCED state. `state` is not mutated — pass {@link cloneDecodeState} output
+     * or a fresh state; this clones internally so the caller's prefix stays reusable.
+     *
+     * Numerically identical to {@link forward} over the concatenated sequence: the
+     * shared {@link _stepLayerPosition} is the only implementation of the block.
+     */
+    stepDecode(state: EvermindLMDecodeState, tokens: number[]): {
+        logits: Float32Array[];
+        state: EvermindLMDecodeState;
+    };
+    /** Run a prompt once and keep the state, so continuations are cheap. */
+    prefixState(tokens: number[]): EvermindLMDecodeState;
+    /**
+     * Mean log-probability the model assigns to `continuation` following a cached
+     * prefix — the tool-decision vote, without replaying the prompt.
+     *
+     * Returns `-Infinity` for an empty continuation, and requires a prefix with at
+     * least one position (there must be a position to predict the first
+     * continuation token FROM).
+     */
+    scoreContinuation(prefix: EvermindLMDecodeState, continuation: number[]): number;
     /**
      * Text-level generation: encode the prompt, generate, decode. `codec` is any
      * tokenizer exposing encode/decode (the engine's `BPETokenizer` satisfies it),
@@ -115,7 +249,13 @@ export declare class EvermindLM {
      * `vocabSize` must match the codec's vocabulary.
      */
     generateText(prompt: string, codec: TextCodec, opts: LMGenerateOptions): string;
-    /** Greedy / temperature-sampled autoregressive generation. Returns NEW token ids. */
+    /**
+     * Greedy / temperature-sampled autoregressive generation. Returns NEW token ids.
+     *
+     * Carries an incremental decode state, so the prompt is processed ONCE and each
+     * new token costs one position. The previous implementation re-ran the whole
+     * sequence per token, making generation quadratic in the prompt length.
+     */
     generate(prompt: number[], opts: LMGenerateOptions): number[];
     /** All trainable parameters as {data} (AdamW-compatible), canonical order. */
     parameters(): {
@@ -149,16 +289,52 @@ export declare class EvermindLM {
     /** Reconstruct weights from a base EVL0 checkpoint + a delta (EVM-6). */
     loadDelta(baseCheckpoint: ArrayBuffer, delta: ArrayBuffer): void;
 }
+export interface EvermindLMTrainOptions extends AdamWOptions {
+    epochs?: number;
+    /**
+     * Gradient accumulation: average gradients over this many sequences (micro-
+     * batches) before each optimiser step, for a larger effective batch on a
+     * memory-constrained device. Default 1.
+     */
+    accumSteps?: number;
+    /**
+     * Use activation checkpointing (recompute layer activations in backward) to
+     * cap peak activation memory. Identical gradients, a little extra compute.
+     * Default false.
+     */
+    checkpoint?: boolean;
+    /**
+     * Mixed-precision training: fp16-rounded gradients with dynamic loss scaling
+     * over fp32 master weights (the model params). Overflowing steps are skipped
+     * and the scale backs off. Default false.
+     */
+    mixedPrecision?: boolean | LossScalerOptions;
+}
 /** Minimal sequence trainer: AdamW over next-token cross-entropy. */
 export declare class EvermindLMTrainer {
     private readonly model;
     private readonly opts;
     private readonly adam;
-    constructor(model: EvermindLM, opts?: AdamWOptions & {
-        epochs?: number;
-    });
+    private readonly scaler;
+    private readonly grads;
+    constructor(model: EvermindLM, opts?: EvermindLMTrainOptions);
+    /** The dynamic loss scaler (mixed-precision mode only) — exposes scale/overflow stats. */
+    get lossScaler(): DynamicLossScaler | null;
+    private _backward;
+    /** Divide accumulated gradients by `n` (accumulation averaging), in place. */
+    private _scaleGrads;
+    /** Round accumulated gradients to fp16 precision (mixed-precision simulation), in place. */
+    private _fp16Grads;
+    /** Multiply accumulated gradients by `s`, in place. */
+    private _mulGrads;
     /** Train on a set of token sequences; returns per-epoch mean loss. */
     fit(sequences: number[][]): number[];
 }
+/**
+ * Log-probability the model assigned to `id` at a position, from that position's
+ * raw logits. Log-softmax computed max-shifted so a long-tail logit cannot
+ * overflow `exp`.
+ */
+export declare function logProbOfToken(row: Float32Array, id: number): number;
 export {};
 //# sourceMappingURL=evermind_lm.d.ts.map

package/dist/lm/evermind_lm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evermind_lm.d.ts","sourceRoot":"","sources":["../../src/lm/evermind_lm.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"evermind_lm.d.ts","sourceRoot":"","sources":["../../src/lm/evermind_lm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAa,KAAK,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAMtG,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,WAAW,CAAC,CAOpF,CAAC;AAEF,eAAO,MAAM,eAAe,aAAa,CAAC;AAG1C,UAAU,YAAY;IACpB,CAAC,EAAE,YAAY,CAAC;IAChB,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE,CAAC;IACnE,SAAS,EAAE,YAAY,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,UAAU,YAAY;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,uFAAuF;IACvF,UAAU,EAAE,YAAY,EAAE,EAAE,CAAC;IAC7B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC;CACjC;AAED,qBAAa,UAAU;IACrB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC;IAE1D;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB,CAAK;IAEhC,0EAA0E;IAC1E,GAAG,EAAE,YAAY,CAAC;IAClB,OAAO,CAAC,IAAI,CAAe;IAC3B,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,+BAA+B;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;gBAE5B,MAAM,EAAE,gBAAgB;IA+DpC,gEAAgE;IAChE,OAAO,CAAC,MAAM;IAUd;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAuBrB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;IAiC1B,kEAAkE;IAClE,OAAO,CAAC,SAAS;IAQjB,oDAAoD;IACpD,OAAO,CAAC,KAAK;IAcb,kFAAkF;IAClF,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG;QAAE,MAAM,EAAE,YAAY,EAAE,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE;IAW1E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,WAAW,GAAG,YAAY;IA0BrD,qEAAqE;IACrE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,YAAY;IAMvD;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAyBrB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IA8CtB,+EAA+E;IAC/E,OAAO,CAAC,cAAc;IAQtB;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM;IAUzC;;;;;;;;OAQG;IACH,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM;IAqBrD,0EAA0E;IAC1E,IAAI,kBAAkB,IAAI,MAAM,CAAqC;IACrE,UAAU,IAAI,IAAI;IAElB,uDAAuD;IACvD,cAAc,IAAI,qBAAqB;IAQvC,8EAA8E;IAC9E,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,qBAAqB;IAQrE;;;;;;;OAOG;IACH,UAAU,CAAC,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG;QAAE,MAAM,EAAE,YAAY,EAAE,CAAC;QAAC,KAAK,EAAE,qBAAqB,CAAA;KAAE;IAgBpH,wEAAwE;IACxE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,qBAAqB;IAIpD;;;;;;;OAOG;IACH,iBAAiB,CAAC,MAAM,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,MAAM;IAehF;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,iBAAiB,GAAG,MAAM;IAI/E;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,iBAAiB,GAAG,MAAM,EAAE;IAiB7D,8EAA8E;IAC9E,UAAU,IAAI;QAAE,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE;IAStC,+DAA+D;IAC/D,SAAS,IAAI;QAAE,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE;IASrC,QAAQ,IAAI,IAAI;IAUhB,uFAAuF;IACvF,aAAa,CAAC,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,WAAW;IAiCzD,sFAAsF;IACtF,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAItC,oFAAoF;IACpF,OAAO,CAAC,SAAS;IA0BjB,qFAAqF;IACrF,OAAO,CAAC,KAAK;IASb,uEAAuE;IACvE,OAAO,CAAC,QAAQ;IAQhB;;;;OAIG;IACH,WAAW,CAAC,cAAc,EAAE,WAAW,EAAE,IAAI,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,WAAW;IASlF,yEAAyE;IACzE,SAAS,CAAC,cAAc,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI;CAIjE;AAED,MAAM,WAAW,sBAAuB,SAAQ,YAAY;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;CAC9C;AAED,qEAAqE;AACrE,qBAAa,iBAAiB;IAK1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IALvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;gBAE9B,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE,sBAA2B;IASpD,0FAA0F;IAC1F,IAAI,UAAU,IAAI,iBAAiB,GAAG,IAAI,CAEzC;IAED,OAAO,CAAC,SAAS;IAIjB,8EAA8E;IAC9E,OAAO,CAAC,WAAW;IAMnB,4FAA4F;IAC5F,OAAO,CAAC,UAAU;IAIlB,uDAAuD;IACvD,OAAO,CAAC,SAAS;IAKjB,sEAAsE;IACtE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE;CA8CrC;AA8DD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAQpE"}