@seanhogg/builderforce-memory-engine 2026.6.30 → 2026.6.34

package/src/kernels/selective_scan.ts

@@ -48,9 +48,11 @@ var<workgroup> wg_bu : array<f32, 256>;   // B*u values
 
 // ---- Helpers ----
 
-// Softplus: numerically stable log(1 + exp(x))
+// Softplus: numerically stable softplus(x) = log(1 + exp(x))
 fn softplus(x: f32) -> f32 {
-    return log(1.0 + exp(x));
+    // Numerically stable: max(x,0) + log1p(exp(-|x|)). The naive log(1+exp(x))
+    // overflows to +Inf for x ≳ 88 (f32 exp range); this form never does. (EVM-8)
+    return max(x, 0.0) + log(1.0 + exp(-abs(x)));
 }
 
 // ZerO-Order Hold discretisation of continuous A, Δ:
@@ -251,7 +253,9 @@ struct ScanParams {
 @group(0) @binding(12) var<storage, read_write> du       : array<f32>;
 
 fn softplus(x: f32) -> f32 {
-    return log(1.0 + exp(x));
+    // Numerically stable: max(x,0) + log1p(exp(-|x|)). The naive log(1+exp(x))
+    // overflows to +Inf for x ≳ 88 (f32 exp range); this form never does. (EVM-8)
+    return max(x, 0.0) + log(1.0 + exp(-abs(x)));
 }
 
 fn softplus_grad(x: f32) -> f32 {

package/src/lm/evermind_lm.ts

@@ -26,6 +26,8 @@ import { crossEntropyLoss, crossEntropyGrad } from "../training/autograd.js";
 import { AdamW, type AdamWOptions } from "../optim/adamw.js";
 import { SeededRng } from "../utils/rng.js";
 import { quantizeFp16, dequantizeFp16 } from "../utils/quantization.js";
+import { appendCrcTrailer, verifyCrcTrailer } from "../utils/crc32.js";
+import { computeRowDelta, applyRowDelta, serializeRowDelta, deserializeRowDelta } from "../utils/delta.js";
 
 export interface EvermindLMConfig {
   /** Vocabulary size (the only required field; everything else has a default). */
@@ -434,11 +436,22 @@ export class EvermindLM {
     }
     if (fp16) new Uint16Array(buf, headerBytes, total).set(quantizeFp16(flat));
     else new Float32Array(buf, headerBytes, total).set(flat);
-    return buf;
+    // Append a CRC-32 trailer so a corrupt/truncated checkpoint is caught on load
+    // (backward-compatible: pre-CRC readers ignore the trailing bytes). (EVM-7)
+    return appendCrcTrailer(buf);
   }
 
-  /** Load weights from an "EVL0" binary. Validates magic + dims. */
+  /** Load weights from an "EVL0" binary. Validates CRC (when present), magic + dims. */
   loadWeights(buffer: ArrayBuffer): void {
+    this._setFlat(this._readFlat(buffer));
+  }
+
+  /** Parse + validate an EVL0 checkpoint to a flat f32 param vector (no mutation). */
+  private _readFlat(buffer: ArrayBuffer): Float32Array {
+    const crc = verifyCrcTrailer(buffer);
+    if (crc.hasTrailer && !crc.ok) {
+      throw new Error("EvermindLM.loadWeights: checkpoint failed CRC integrity check (corrupt or truncated)");
+    }
     const head = new Uint32Array(buffer, 0, 9);
     if (head[0] !== MAGIC) throw new Error("EvermindLM.loadWeights: bad magic (not an EVL0 checkpoint)");
     const version = head[1]!;
@@ -453,19 +466,51 @@ export class EvermindLM {
     ) {
       throw new Error("EvermindLM.loadWeights: config mismatch with checkpoint");
     }
+    const total = this.parameters().reduce((n, p) => n + p.data.length, 0);
+    const headerBytes = 36;
+    return version === 2
+      ? dequantizeFp16(new Uint16Array(buffer, headerBytes, total))
+      : new Float32Array(buffer.slice(headerBytes, headerBytes + total * 4));
+  }
+
+  /** Flat concatenation of all params, canonical order (matches checkpoint layout). */
+  private _flat(): Float32Array {
     const params = this.parameters();
     const total = params.reduce((n, p) => n + p.data.length, 0);
-    const headerBytes = 36;
-    const flat =
-      version === 2
-        ? dequantizeFp16(new Uint16Array(buffer, headerBytes, total))
-        : new Float32Array(buffer.slice(headerBytes, headerBytes + total * 4));
+    const flat = new Float32Array(total);
     let o = 0;
-    for (const p of params) {
+    for (const p of params) { flat.set(p.data, o); o += p.data.length; }
+    return flat;
+  }
+
+  /** Distribute a flat param vector back into the model's parameters. */
+  private _setFlat(flat: Float32Array): void {
+    let o = 0;
+    for (const p of this.parameters()) {
       p.data.set(flat.subarray(o, o + p.data.length));
       o += p.data.length;
     }
   }
+
+  /**
+   * Export a SPARSE DELTA of the current weights against a base EVL0 checkpoint
+   * (EVM-6). Online WSLA updates only a few rows, so a delta persists kilobytes
+   * instead of rewriting the whole model. Reconstruct with {@link loadDelta}.
+   */
+  exportDelta(baseCheckpoint: ArrayBuffer, opts: { eps?: number } = {}): ArrayBuffer {
+    const base = this._readFlat(baseCheckpoint);
+    const current = this._flat();
+    // Row-granular when the param vector tiles evenly by the model width (the
+    // embedding dominates and is dModel-wide); else fall back to per-element.
+    const rowSize = current.length % this.config.dModel === 0 ? this.config.dModel : 1;
+    return serializeRowDelta(computeRowDelta(base, current, rowSize, opts.eps ?? 0));
+  }
+
+  /** Reconstruct weights from a base EVL0 checkpoint + a delta (EVM-6). */
+  loadDelta(baseCheckpoint: ArrayBuffer, delta: ArrayBuffer): void {
+    const base = this._readFlat(baseCheckpoint);
+    this._setFlat(applyRowDelta(base, deserializeRowDelta(delta)));
+  }
 }
 
 /** Minimal sequence trainer: AdamW over next-token cross-entropy. */

package/src/model/mamba_model.ts

@@ -36,6 +36,7 @@ import { LINEAR_FORWARD_WGSL } from '../kernels/linear_projection.js';
 import { ACTIVATIONS_WGSL }    from '../kernels/activations.js';
 import { gaussianArray, setInitSeed } from '../utils/rng.js';
 import { quantizeFp16, dequantizeFp16 } from '../utils/quantization.js';
+import { appendCrcTrailer, verifyCrcTrailer } from '../utils/crc32.js';
 
 // ── Public types ──────────────────────────────────────────────────────────────
 
@@ -485,7 +486,9 @@ export class HybridMambaModel {
             }
         }
 
-        return out;
+        // Append a CRC-32 trailer for integrity-on-load (backward compatible —
+        // length-bounded readers ignore the trailing bytes). (EVM-7)
+        return appendCrcTrailer(out);
     }
 
     /**
@@ -496,6 +499,11 @@ export class HybridMambaModel {
      * v3: identical layout to v2 but the data section is fp16 (dequantised on load).
      */
     async loadWeights(buffer: ArrayBuffer): Promise<void> {
+        // Verify the CRC trailer when present (corrupt/truncated guard, EVM-7).
+        const crc = verifyCrcTrailer(buffer);
+        if (crc.hasTrailer && !crc.ok) {
+            throw new Error('Invalid weight file: failed CRC integrity check (corrupt or truncated).');
+        }
         const view = new DataView(buffer);
         let off    = 0;
 

package/src/utils/crc32.ts

@@ -0,0 +1,82 @@
+/**
+ * utils/crc32.ts — checkpoint integrity (CRC-32) + a backward-compatible trailer.
+ *
+ * Checkpoints had no integrity check: a truncated or bit-rotted `.bin` would
+ * either throw deep in the parser or, worse, load corrupt weights silently. This
+ * adds a standard IEEE CRC-32 and a self-describing trailer that callers append
+ * on export and verify on load.
+ *
+ * The trailer is appended AFTER the existing payload as `[magic u32][crc u32]`
+ * (8 bytes, little-endian). Because every checkpoint reader consumes a
+ * length-bounded payload (header declares element counts) and ignores trailing
+ * bytes, an old reader still loads a trailer-bearing file — the trailer is
+ * purely additive. The CRC covers the payload bytes only (everything before the
+ * trailer).
+ */
+
+/** Trailer sentinel: 'EVCR' (Evermind CRc), little-endian uint32. */
+export const CRC_TRAILER_MAGIC = 0x52435645; // bytes 45 56 43 52 = "EVCR"
+const TRAILER_BYTES = 8;
+
+/** Precomputed CRC-32 (IEEE 802.3, reflected) lookup table. */
+const CRC_TABLE: Uint32Array = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+
+/** IEEE CRC-32 of a byte buffer, returned as an unsigned 32-bit number. */
+export function crc32(bytes: Uint8Array): number {
+    let crc = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++) {
+        crc = CRC_TABLE[(crc ^ bytes[i]!) & 0xff]! ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** Return a new ArrayBuffer = `payload` followed by the CRC trailer. */
+export function appendCrcTrailer(payload: ArrayBuffer): ArrayBuffer {
+    const body = new Uint8Array(payload);
+    const out = new ArrayBuffer(body.length + TRAILER_BYTES);
+    const u8 = new Uint8Array(out);
+    u8.set(body, 0);
+    const view = new DataView(out);
+    view.setUint32(body.length, CRC_TRAILER_MAGIC, true);
+    view.setUint32(body.length + 4, crc32(body), true);
+    return out;
+}
+
+export interface CrcCheck {
+    /** True when a recognised CRC trailer is present. */
+    hasTrailer: boolean;
+    /** True when no trailer is present, or the trailer's CRC matches the payload. */
+    ok: boolean;
+    /** The payload with any trailer stripped (safe to parse). */
+    body: ArrayBuffer;
+}
+
+/**
+ * Inspect a buffer for a CRC trailer. When present, verifies the CRC over the
+ * preceding payload. When absent (legacy file), reports `ok: true` and returns
+ * the buffer unchanged — so verification is opt-in by the writer, never a
+ * hard requirement that would reject pre-CRC checkpoints.
+ */
+export function verifyCrcTrailer(buffer: ArrayBuffer): CrcCheck {
+    if (buffer.byteLength < TRAILER_BYTES) {
+        return { hasTrailer: false, ok: true, body: buffer };
+    }
+    const view = new DataView(buffer);
+    const bodyLen = buffer.byteLength - TRAILER_BYTES;
+    const magic = view.getUint32(bodyLen, true);
+    if (magic !== CRC_TRAILER_MAGIC) {
+        return { hasTrailer: false, ok: true, body: buffer };
+    }
+    const stored = view.getUint32(bodyLen + 4, true);
+    const body = buffer.slice(0, bodyLen);
+    const ok = crc32(new Uint8Array(body)) === stored;
+    return { hasTrailer: true, ok, body };
+}

package/src/utils/delta.ts

@@ -0,0 +1,117 @@
+/**
+ * utils/delta.ts — sparse, row-granular weight deltas for online checkpoints.
+ *
+ * Online adaptation (WSLA) restricts the trainable set to a few
+ * selective-projection ROWS, yet each `adapt()` previously rewrote the WHOLE
+ * model to disk. That is wasteful in both size and I/O: 99% of the bytes are
+ * identical to the base checkpoint. A delta persists only the rows that actually
+ * changed, as a diff against a base, so an online update writes kilobytes
+ * instead of megabytes.
+ *
+ * Format (little-endian), CRC-trailed via {@link appendCrcTrailer}:
+ *   magic 'EVD0' u32 | version u32 | rowSize u32 | nRows u32 |
+ *   rowIndex[nRows] u32 | float32 row data[nRows * rowSize]
+ *
+ * The base + delta reconstruct the exact current weights; a row counts as
+ * "changed" if any element differs beyond an optional epsilon.
+ */
+
+import { appendCrcTrailer, verifyCrcTrailer } from './crc32.js';
+
+const DELTA_MAGIC = 0x30445645; // 'EVD0'
+const DELTA_VERSION = 1;
+
+export interface RowDelta {
+    /** Width of one row (elements). `base.length` must be a multiple of it. */
+    rowSize: number;
+    /** Indices (row-major) of the rows that changed. */
+    rows: number[];
+    /** Concatenated new values for the changed rows (rows.length * rowSize). */
+    data: Float32Array;
+}
+
+/**
+ * Compute the row-sparse delta of `current` vs `base` (same length + layout).
+ * A row is included when any element differs by more than `eps` (default 0).
+ */
+export function computeRowDelta(
+    base: Float32Array,
+    current: Float32Array,
+    rowSize: number,
+    eps = 0,
+): RowDelta {
+    if (base.length !== current.length) {
+        throw new Error(`computeRowDelta: length mismatch (base ${base.length}, current ${current.length})`);
+    }
+    if (rowSize <= 0 || base.length % rowSize !== 0) {
+        throw new Error(`computeRowDelta: base length ${base.length} is not a multiple of rowSize ${rowSize}`);
+    }
+    const nRowsTotal = base.length / rowSize;
+    const rows: number[] = [];
+    for (let r = 0; r < nRowsTotal; r++) {
+        const off = r * rowSize;
+        let changed = false;
+        for (let c = 0; c < rowSize; c++) {
+            if (Math.abs(current[off + c]! - base[off + c]!) > eps) { changed = true; break; }
+        }
+        if (changed) rows.push(r);
+    }
+    const data = new Float32Array(rows.length * rowSize);
+    rows.forEach((r, i) => data.set(current.subarray(r * rowSize, r * rowSize + rowSize), i * rowSize));
+    return { rowSize, rows, data };
+}
+
+/** Apply a delta onto a copy of `base`, returning the reconstructed weights. */
+export function applyRowDelta(base: Float32Array, delta: RowDelta): Float32Array {
+    if (base.length % delta.rowSize !== 0) {
+        throw new Error(`applyRowDelta: base length ${base.length} is not a multiple of rowSize ${delta.rowSize}`);
+    }
+    const out = Float32Array.from(base);
+    delta.rows.forEach((r, i) => {
+        const dst = r * delta.rowSize;
+        if (dst + delta.rowSize > out.length) {
+            throw new Error(`applyRowDelta: row ${r} out of range for base of ${out.length} elements`);
+        }
+        out.set(delta.data.subarray(i * delta.rowSize, i * delta.rowSize + delta.rowSize), dst);
+    });
+    return out;
+}
+
+/** Serialize a delta to a CRC-trailed binary. */
+export function serializeRowDelta(delta: RowDelta): ArrayBuffer {
+    const nRows = delta.rows.length;
+    const headerEls = 4; // magic, version, rowSize, nRows
+    const headerBytes = headerEls * 4;
+    const rowIdxBytes = nRows * 4;
+    const dataBytes = delta.data.length * 4;
+    const buf = new ArrayBuffer(headerBytes + rowIdxBytes + dataBytes);
+    const view = new DataView(buf);
+    view.setUint32(0, DELTA_MAGIC, true);
+    view.setUint32(4, DELTA_VERSION, true);
+    view.setUint32(8, delta.rowSize, true);
+    view.setUint32(12, nRows, true);
+    let off = headerBytes;
+    for (const r of delta.rows) { view.setUint32(off, r, true); off += 4; }
+    new Float32Array(buf, off, delta.data.length).set(delta.data);
+    return appendCrcTrailer(buf);
+}
+
+/** Parse a binary produced by {@link serializeRowDelta}; verifies CRC + magic. */
+export function deserializeRowDelta(buffer: ArrayBuffer): RowDelta {
+    const crc = verifyCrcTrailer(buffer);
+    if (crc.hasTrailer && !crc.ok) {
+        throw new Error('deserializeRowDelta: failed CRC integrity check (corrupt or truncated)');
+    }
+    const body = crc.body;
+    const view = new DataView(body);
+    if (view.getUint32(0, true) !== DELTA_MAGIC) {
+        throw new Error('deserializeRowDelta: bad magic (not an EVD0 delta)');
+    }
+    const rowSize = view.getUint32(8, true);
+    const nRows = view.getUint32(12, true);
+    let off = 16;
+    const rows: number[] = [];
+    for (let i = 0; i < nRows; i++) { rows.push(view.getUint32(off, true)); off += 4; }
+    const data = new Float32Array(body.slice(off, off + nRows * rowSize * 4));
+    return { rowSize, rows, data };
+}

package/src/utils/gpu_utils.ts

@@ -10,6 +10,60 @@ const COPY_SRC: number = _gpu.GPUBufferUsage?.COPY_SRC ?? 0x04;
 const COPY_DST: number = _gpu.GPUBufferUsage?.COPY_DST ?? 0x08;
 const MAP_READ: number = _gpu.GPUBufferUsage?.MAP_READ ?? 0x01;
 
+/**
+ * Shape-keyed GPUBuffer pool (EVM-8). Hot paths (e.g. `readBuffer` staging)
+ * allocated and destroyed a GPUBuffer on EVERY call — costly under load. The
+ * pool reuses buffers keyed by (byteSize, usage): `acquire` hands back a free
+ * buffer of that shape or creates one; `release` returns it for reuse. Buffers
+ * of one shape are interchangeable, so reuse is always safe.
+ */
+export class BufferPool {
+    private readonly _free = new Map<string, GPUBuffer[]>();
+    constructor(private readonly device: GPUDevice) {}
+
+    private _key(byteSize: number, usage: number): string {
+        return `${byteSize}:${usage}`;
+    }
+
+    /** A free buffer of this shape, or a freshly created one. */
+    acquire(byteSize: number, usage: number): GPUBuffer {
+        const list = this._free.get(this._key(byteSize, usage));
+        const reused = list?.pop();
+        return reused ?? this.device.createBuffer({ size: byteSize, usage });
+    }
+
+    /** Return a buffer to the pool for later reuse (do not destroy it yourself). */
+    release(buffer: GPUBuffer, byteSize: number, usage: number): void {
+        const key = this._key(byteSize, usage);
+        let list = this._free.get(key);
+        if (!list) { list = []; this._free.set(key, list); }
+        list.push(buffer);
+    }
+
+    /** Number of pooled (free) buffers across all shapes. */
+    get freeCount(): number {
+        let n = 0;
+        for (const list of this._free.values()) n += list.length;
+        return n;
+    }
+
+    /** Destroy every pooled buffer and empty the pool. */
+    clear(): void {
+        for (const list of this._free.values()) {
+            for (const b of list) b.destroy();
+        }
+        this._free.clear();
+    }
+}
+
+/** One staging-buffer pool per device, used by {@link readBuffer}. */
+const _stagingPools = new WeakMap<GPUDevice, BufferPool>();
+function stagingPool(device: GPUDevice): BufferPool {
+    let pool = _stagingPools.get(device);
+    if (!pool) { pool = new BufferPool(device); _stagingPools.set(device, pool); }
+    return pool;
+}
+
 export interface InitWebGPUOptions {
   powerPreference?: 'high-performance' | 'low-power';
 }
@@ -93,10 +147,11 @@ export function createUniformBuffer(device: GPUDevice, data: ArrayBuffer | Array
 
 export async function readBuffer(device: GPUDevice, srcBuffer: GPUBuffer, byteSize: number): Promise<Float32Array> {
     const MAP_READ_FLAG: number = _gpu.GPUMapMode?.READ ?? 0x01;
-    const stagingBuffer = device.createBuffer({
-        size  : byteSize,
-        usage : MAP_READ | COPY_DST,
-    });
+    // EVM-8: reuse a pooled staging buffer instead of allocating + destroying one
+    // per call. After unmap a staging buffer is fully reusable for the next read.
+    const stagingUsage = MAP_READ | COPY_DST;
+    const pool = stagingPool(device);
+    const stagingBuffer = pool.acquire(byteSize, stagingUsage);
 
     const encoder = device.createCommandEncoder();
     encoder.copyBufferToBuffer(srcBuffer, 0, stagingBuffer, 0, byteSize);
@@ -105,7 +160,7 @@ export async function readBuffer(device: GPUDevice, srcBuffer: GPUBuffer, byteSi
     await stagingBuffer.mapAsync(MAP_READ_FLAG);
     const result = new Float32Array(stagingBuffer.getMappedRange().slice(0));
     stagingBuffer.unmap();
-    stagingBuffer.destroy();
+    pool.release(stagingBuffer, byteSize, stagingUsage);
     return result;
 }