@seanhogg/builderforce-memory-engine 2026.6.30 → 2026.6.34

package/dist/utils/crc32.js

@@ -0,0 +1,70 @@
+/**
+ * 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 = (() => {
+    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) {
+    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) {
+    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;
+}
+/**
+ * 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) {
+    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 };
+}
+//# sourceMappingURL=crc32.js.map

package/dist/utils/crc32.js.map

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

package/dist/utils/delta.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+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 declare function computeRowDelta(base: Float32Array, current: Float32Array, rowSize: number, eps?: number): RowDelta;
+/** Apply a delta onto a copy of `base`, returning the reconstructed weights. */
+export declare function applyRowDelta(base: Float32Array, delta: RowDelta): Float32Array;
+/** Serialize a delta to a CRC-trailed binary. */
+export declare function serializeRowDelta(delta: RowDelta): ArrayBuffer;
+/** Parse a binary produced by {@link serializeRowDelta}; verifies CRC + magic. */
+export declare function deserializeRowDelta(buffer: ArrayBuffer): RowDelta;
+//# sourceMappingURL=delta.d.ts.map

package/dist/utils/delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.ts","sourceRoot":"","sources":["../../src/utils/delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,MAAM,WAAW,QAAQ;IACrB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,4EAA4E;IAC5E,IAAI,EAAE,YAAY,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC3B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,SAAI,GACR,QAAQ,CAoBV;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,GAAG,YAAY,CAa/E;AAED,iDAAiD;AACjD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,CAgB9D;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,CAiBjE"}

package/dist/utils/delta.js

@@ -0,0 +1,108 @@
+/**
+ * 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;
+/**
+ * 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, current, rowSize, eps = 0) {
+    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 = [];
+    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, delta) {
+    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) {
+    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) {
+    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 = [];
+    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 };
+}
+//# sourceMappingURL=delta.js.map

package/dist/utils/delta.js.map

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

package/dist/utils/gpu_utils.d.ts

@@ -1,6 +1,27 @@
 /**
  * gpu_utils.ts – WebGPU device management and buffer helpers.
  */
+/**
+ * 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 declare class BufferPool {
+    private readonly device;
+    private readonly _free;
+    constructor(device: GPUDevice);
+    private _key;
+    /** A free buffer of this shape, or a freshly created one. */
+    acquire(byteSize: number, usage: number): GPUBuffer;
+    /** Return a buffer to the pool for later reuse (do not destroy it yourself). */
+    release(buffer: GPUBuffer, byteSize: number, usage: number): void;
+    /** Number of pooled (free) buffers across all shapes. */
+    get freeCount(): number;
+    /** Destroy every pooled buffer and empty the pool. */
+    clear(): void;
+}
 export interface InitWebGPUOptions {
     powerPreference?: 'high-performance' | 'low-power';
 }

package/dist/utils/gpu_utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gpu_utils.d.ts","sourceRoot":"","sources":["../../src/utils/gpu_utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAAC;CACpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;CACrB;AAED,wBAAsB,UAAU,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwCxF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,WAAW,GAAG,MAAM,EAAE,EAAE,QAAQ,UAAQ,GAAG,SAAS,CAW/H;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,SAAS,CAGzG;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,SAAS,CAUrG;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAgBjH;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,SAAI,GAAG,IAAI,CAE3G;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAMnH;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,kBAAkB,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,UAAU,SAAI,GAAG,YAAY,CASnI;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAQnJ;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD"}
+{"version":3,"file":"gpu_utils.d.ts","sourceRoot":"","sources":["../../src/utils/gpu_utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH;;;;;;GAMG;AACH,qBAAa,UAAU;IAEP,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;gBAC3B,MAAM,EAAE,SAAS;IAE9C,OAAO,CAAC,IAAI;IAIZ,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS;IAMnD,gFAAgF;IAChF,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAOjE,yDAAyD;IACzD,IAAI,SAAS,IAAI,MAAM,CAItB;IAED,sDAAsD;IACtD,KAAK,IAAI,IAAI;CAMhB;AAUD,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAAC;CACpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;CACrB;AAED,wBAAsB,UAAU,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwCxF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,WAAW,GAAG,MAAM,EAAE,EAAE,QAAQ,UAAQ,GAAG,SAAS,CAW/H;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,SAAS,CAGzG;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,SAAS,CAUrG;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiBjH;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,SAAI,GAAG,IAAI,CAE3G;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAMnH;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,kBAAkB,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,UAAU,SAAI,GAAG,YAAY,CASnI;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAQnJ;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/utils/gpu_utils.js

@@ -8,6 +8,64 @@ const STORAGE = _gpu.GPUBufferUsage?.STORAGE ?? 0x80;
 const COPY_SRC = _gpu.GPUBufferUsage?.COPY_SRC ?? 0x04;
 const COPY_DST = _gpu.GPUBufferUsage?.COPY_DST ?? 0x08;
 const MAP_READ = _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 {
+    device;
+    _free = new Map();
+    constructor(device) {
+        this.device = device;
+    }
+    _key(byteSize, usage) {
+        return `${byteSize}:${usage}`;
+    }
+    /** A free buffer of this shape, or a freshly created one. */
+    acquire(byteSize, usage) {
+        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, byteSize, usage) {
+        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() {
+        let n = 0;
+        for (const list of this._free.values())
+            n += list.length;
+        return n;
+    }
+    /** Destroy every pooled buffer and empty the pool. */
+    clear() {
+        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();
+function stagingPool(device) {
+    let pool = _stagingPools.get(device);
+    if (!pool) {
+        pool = new BufferPool(device);
+        _stagingPools.set(device, pool);
+    }
+    return pool;
+}
 export async function initWebGPU(opts = {}) {
     if (typeof navigator === 'undefined' || !navigator.gpu) {
         throw new Error('WebGPU is not available in this environment. ' +
@@ -63,17 +121,18 @@ export function createUniformBuffer(device, data) {
 }
 export async function readBuffer(device, srcBuffer, byteSize) {
     const MAP_READ_FLAG = _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);
     device.queue.submit([encoder.finish()]);
     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;
 }
 export function uploadBuffer(device, buffer, data, byteOffset = 0) {

package/dist/utils/gpu_utils.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory-engine",
-  "version": "2026.6.30",
+  "version": "2026.6.34",
   "description": "BuilderForce Agent Memory — engine layer. TypeScript/WGSL Mamba SSM kernels, model blocks, autograd, training, and BPE tokenizer (zero runtime deps, WebGPU-native).",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/bench/harness.ts

@@ -0,0 +1,219 @@
+/**
+ * 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";
+import type {
+  AsyncLogitsModel,
+  BenchmarkOptions,
+  BenchmarkReport,
+  ComparisonReport,
+  LogitsModel,
+  TrainAndBenchmarkOptions,
+  TrainAndBenchmarkResult,
+} from "./types.js";
+
+/** A monotonic clock, preferring `performance.now()` when present. */
+function defaultNow(): number {
+  const g = globalThis as { performance?: { now(): number } };
+  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: number[]): number[] {
+  return seq.slice(1);
+}
+
+function finalize(
+  acc: { tokens: number; ceSum: number; top1Hits: number; topKHits: number },
+  sequences: number,
+  topK: number,
+  elapsedMs: number | undefined,
+): BenchmarkReport {
+  const meanCe = acc.tokens > 0 ? acc.ceSum / acc.tokens : 0;
+  const report: BenchmarkReport = {
+    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: LogitsModel,
+  sequences: number[][],
+  opts: BenchmarkOptions = {},
+): BenchmarkReport {
+  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: AsyncLogitsModel,
+  sequences: number[][],
+  opts: BenchmarkOptions = {},
+): Promise<BenchmarkReport> {
+  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: LogitsModel,
+  baseline: LogitsModel,
+  sequences: number[][],
+  opts: BenchmarkOptions = {},
+): ComparisonReport {
+  return compareReports(benchmarkModel(candidate, sequences, opts), benchmarkModel(baseline, sequences, opts));
+}
+
+/** Build a {@link ComparisonReport} from two already-computed scorecards. */
+export function compareReports(candidate: BenchmarkReport, baseline: BenchmarkReport): ComparisonReport {
+  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: ComparisonReport["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: string, codec: { encode(text: string): number[] }): number[][] {
+  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: LogitsModel,
+  codec: { encode(text: string): number[] },
+  corpus: string,
+  opts: BenchmarkOptions = {},
+): BenchmarkReport {
+  return benchmarkModel(model, corpusToSequences(corpus, codec), opts);
+}
+
+/** Deterministic Fisher–Yates shuffle (in place) driven by a seeded RNG. */
+function shuffle<T>(arr: T[], rng: SeededRng): T[] {
+  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: string,
+  opts: TrainAndBenchmarkOptions = {},
+): TrainAndBenchmarkResult {
+  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,
+  };
+}

package/src/bench/index.ts

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