@seanhogg/builderforce-memory-engine 2026.6.18

package/src/utils/gpu_utils.ts

@@ -0,0 +1,147 @@
+/**
+ * gpu_utils.ts – WebGPU device management and buffer helpers.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const _gpu = globalThis as any;
+const UNIFORM: number  = _gpu.GPUBufferUsage?.UNIFORM  ?? 0x40;
+const STORAGE: number  = _gpu.GPUBufferUsage?.STORAGE  ?? 0x80;
+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;
+
+export interface InitWebGPUOptions {
+  powerPreference?: 'high-performance' | 'low-power';
+}
+
+export interface InitWebGPUResult {
+  device: GPUDevice;
+  adapter: GPUAdapter;
+}
+
+export async function initWebGPU(opts: InitWebGPUOptions = {}): Promise<InitWebGPUResult> {
+    if (typeof navigator === 'undefined' || !navigator.gpu) {
+        throw new Error(
+            'WebGPU is not available in this environment. ' +
+            'Use Chrome 113+, Edge 113+, or Firefox Nightly with WebGPU enabled.'
+        );
+    }
+
+    const adapter = await navigator.gpu.requestAdapter({
+        powerPreference: opts.powerPreference ?? 'high-performance',
+    });
+
+    if (!adapter) {
+        throw new Error('Failed to acquire a GPUAdapter. Your GPU may not support WebGPU.');
+    }
+
+    const adapterLimits = adapter.limits;
+    const requested3GB  = 3 * 1024 * 1024 * 1024;
+    const device = await adapter.requestDevice({
+        requiredLimits: {
+            maxBufferSize: Math.min(
+                requested3GB,
+                adapterLimits.maxBufferSize
+            ),
+            maxStorageBufferBindingSize: Math.min(
+                requested3GB,
+                adapterLimits.maxStorageBufferBindingSize
+            ),
+            maxComputeInvocationsPerWorkgroup: Math.min(
+                256,
+                adapterLimits.maxComputeInvocationsPerWorkgroup
+            ),
+        },
+    });
+
+    device.lost.then((info) => {
+        console.error('WebGPU device lost:', info.message);
+    });
+
+    return { device, adapter };
+}
+
+export function createStorageBuffer(device: GPUDevice, data: Float32Array | Uint32Array | number[], readable = false): GPUBuffer {
+    const arr    = data instanceof Float32Array || data instanceof Uint32Array ? data : new Float32Array(data);
+    const usage  = STORAGE | COPY_DST | (readable ? COPY_SRC : 0);
+    const buffer = device.createBuffer({ size: arr.byteLength, usage, mappedAtCreation: true });
+    if (arr instanceof Uint32Array) {
+        new Uint32Array(buffer.getMappedRange()).set(arr);
+    } else {
+        new Float32Array(buffer.getMappedRange()).set(arr as Float32Array);
+    }
+    buffer.unmap();
+    return buffer;
+}
+
+export function createEmptyStorageBuffer(device: GPUDevice, byteSize: number, readable = false): GPUBuffer {
+    const usage = STORAGE | COPY_DST | (readable ? COPY_SRC : 0);
+    return device.createBuffer({ size: byteSize, usage });
+}
+
+export function createUniformBuffer(device: GPUDevice, data: ArrayBuffer | ArrayBufferView): GPUBuffer {
+    const bytes  = ArrayBuffer.isView(data) ? data.buffer : data;
+    const buffer = device.createBuffer({
+        size  : bytes.byteLength,
+        usage : UNIFORM | COPY_DST,
+        mappedAtCreation: true,
+    });
+    new Uint8Array(buffer.getMappedRange()).set(new Uint8Array(bytes));
+    buffer.unmap();
+    return buffer;
+}
+
+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,
+    });
+
+    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();
+    return result;
+}
+
+export function uploadBuffer(device: GPUDevice, buffer: GPUBuffer, data: Float32Array, byteOffset = 0): void {
+    device.queue.writeBuffer(buffer, byteOffset, data.buffer, data.byteOffset, data.byteLength);
+}
+
+export function createComputePipeline(device: GPUDevice, wgslSource: string, entryPoint: string): GPUComputePipeline {
+    const shaderModule = device.createShaderModule({ code: wgslSource });
+    return device.createComputePipeline({
+        layout : 'auto',
+        compute: { module: shaderModule, entryPoint },
+    });
+}
+
+export function createBindGroup(device: GPUDevice, pipeline: GPUComputePipeline, buffers: GPUBuffer[], groupIndex = 0): GPUBindGroup {
+    const entries = buffers.map((buf, i) => ({
+        binding : i,
+        resource: { buffer: buf },
+    }));
+    return device.createBindGroup({
+        layout : pipeline.getBindGroupLayout(groupIndex),
+        entries,
+    });
+}
+
+export function dispatchKernel(device: GPUDevice, pipeline: GPUComputePipeline, bindGroup: GPUBindGroup, workgroups: [number, number, number]): void {
+    const encoder = device.createCommandEncoder();
+    const pass    = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+    pass.dispatchWorkgroups(...workgroups);
+    pass.end();
+    device.queue.submit([encoder.finish()]);
+}
+
+export function cdiv(a: number, b: number): number {
+    return Math.ceil(a / b);
+}

package/src/utils/quantization.ts

@@ -0,0 +1,154 @@
+/**
+ * quantization.ts – FP16 and Int8 quantization utilities.
+ */
+
+export interface QuantizeInt8Result {
+  data: Int8Array;
+  scale: number;
+}
+
+export interface QuantizeInt8PerChannelResult {
+  data: Int8Array;
+  scales: Float32Array;
+}
+
+export interface MemoryEstimate {
+  fp32: number;
+  fp16: number;
+  int8: number;
+}
+
+export function floatToFp16(val: number): number {
+    const buf = new ArrayBuffer(4);
+    const f32 = new Float32Array(buf);
+    const u32 = new Uint32Array(buf);
+    f32[0] = val;
+    const bits = u32[0]!;
+
+    const sign     = (bits >>> 31) & 0x1;
+    const exponent = (bits >>> 23) & 0xFF;
+    const mantissa =  bits         & 0x7FFFFF;
+
+    if (exponent === 255) {
+        return (sign << 15) | 0x7C00 | (mantissa ? 0x200 : 0);
+    }
+
+    const expAdj = exponent - 127 + 15;
+
+    if (expAdj >= 31) {
+        return (sign << 15) | 0x7C00;
+    }
+
+    if (expAdj <= 0) {
+        if (expAdj < -10) { return sign << 15; }
+        const shift = 14 - expAdj;
+        return (sign << 15) | ((mantissa | 0x800000) >> shift);
+    }
+
+    return (sign << 15) | (expAdj << 10) | (mantissa >> 13);
+}
+
+export function fp16ToFloat(val: number): number {
+    const sign     = (val >>> 15) & 0x1;
+    const exponent = (val >>> 10) & 0x1F;
+    const mantissa =  val         & 0x3FF;
+
+    if (exponent === 0) {
+        const f = mantissa / 1024.0;
+        return sign ? -f : f;
+    }
+
+    if (exponent === 31) {
+        return sign ? -Infinity : (mantissa ? NaN : Infinity);
+    }
+
+    const expUnbiased = exponent - 15;
+    const f = (1 + mantissa / 1024.0) * Math.pow(2, expUnbiased);
+    return sign ? -f : f;
+}
+
+export function quantizeFp16(f32: Float32Array): Uint16Array {
+    const out = new Uint16Array(f32.length);
+    for (let i = 0; i < f32.length; i++) {
+        out[i] = floatToFp16(f32[i]!);
+    }
+    return out;
+}
+
+export function dequantizeFp16(fp16: Uint16Array): Float32Array {
+    const out = new Float32Array(fp16.length);
+    for (let i = 0; i < fp16.length; i++) {
+        out[i] = fp16ToFloat(fp16[i]!);
+    }
+    return out;
+}
+
+export function quantizeInt8(f32: Float32Array): QuantizeInt8Result {
+    let maxAbs = 0;
+    for (let i = 0; i < f32.length; i++) {
+        const a = Math.abs(f32[i]!);
+        if (a > maxAbs) maxAbs = a;
+    }
+
+    const scale = maxAbs / 127.0 || 1.0;
+    const data  = new Int8Array(f32.length);
+
+    for (let i = 0; i < f32.length; i++) {
+        data[i] = Math.max(-128, Math.min(127, Math.round(f32[i]! / scale)));
+    }
+
+    return { data, scale };
+}
+
+export function dequantizeInt8(int8: Int8Array, scale: number): Float32Array {
+    const out = new Float32Array(int8.length);
+    for (let i = 0; i < int8.length; i++) {
+        out[i] = int8[i]! * scale;
+    }
+    return out;
+}
+
+export function quantizeInt8PerChannel(f32: Float32Array, numChannels: number): QuantizeInt8PerChannelResult {
+    const channelSize = f32.length / numChannels;
+    const scales = new Float32Array(numChannels);
+    const data   = new Int8Array(f32.length);
+
+    for (let c = 0; c < numChannels; c++) {
+        let maxAbs = 0;
+        const base = c * channelSize;
+        for (let j = 0; j < channelSize; j++) {
+            const a = Math.abs(f32[base + j]!);
+            if (a > maxAbs) maxAbs = a;
+        }
+        scales[c] = maxAbs / 127.0 || 1.0;
+        for (let j = 0; j < channelSize; j++) {
+            data[base + j] = Math.max(-128, Math.min(127,
+                Math.round(f32[base + j]! / scales[c]!)
+            ));
+        }
+    }
+
+    return { data, scales };
+}
+
+export function dequantizeInt8PerChannel(int8: Int8Array, scales: Float32Array, numChannels: number): Float32Array {
+    const channelSize = int8.length / numChannels;
+    const out = new Float32Array(int8.length);
+
+    for (let c = 0; c < numChannels; c++) {
+        const base = c * channelSize;
+        for (let j = 0; j < channelSize; j++) {
+            out[base + j] = int8[base + j]! * scales[c]!;
+        }
+    }
+
+    return out;
+}
+
+export function estimateMemory(numElements: number): MemoryEstimate {
+    return {
+        fp32: numElements * 4,
+        fp16: numElements * 2,
+        int8: numElements * 1,
+    };
+}

package/src/utils/rng.ts

@@ -0,0 +1,65 @@
+/**
+ * rng.ts – shared, optionally-seeded random source for weight initialisation.
+ *
+ * Weight init across the model and every block used to duplicate the same
+ * `Math.random()` Box–Muller draw. That made cold-start weights
+ * non-reproducible across machines. This module centralises the draw and lets
+ * the model install a deterministic seed for the duration of construction, so
+ * the same `seed` yields byte-identical initial weights everywhere.
+ *
+ * The default (unseeded) source delegates to `Math.random`, preserving the
+ * original behaviour for callers that don't request a seed.
+ *
+ * The seeded generator uses the same LCG constants as tools/generate-bin.js so
+ * tooling and runtime agree on what a "seed N" model looks like.
+ */
+
+/** Deterministic linear-congruential generator (Numerical Recipes constants). */
+export class SeededRng {
+    private _s: number;
+
+    constructor(seed: number) {
+        // Avoid the zero fixed point; keep state in uint32 range.
+        this._s = (seed >>> 0) || 1;
+    }
+
+    /** Next float in [0, 1). */
+    next(): number {
+        this._s = (Math.imul(1664525, this._s) + 1013904223) >>> 0;
+        return this._s / 0x1_0000_0000;
+    }
+}
+
+/** Active uniform source. Swapped by setInitSeed; defaults to Math.random. */
+let _next: () => number = Math.random;
+
+/**
+ * Installs (or clears) the deterministic init seed.
+ * Pass a number to make subsequent `randn`/`gaussianArray` draws reproducible;
+ * pass `undefined` to restore the default `Math.random` source.
+ *
+ * Construction is synchronous, so a process-wide source is safe: seed before
+ * building a model and clear afterwards.
+ */
+export function setInitSeed(seed: number | undefined): void {
+    if (seed == null) {
+        _next = Math.random;
+    } else {
+        const rng = new SeededRng(seed);
+        _next = () => rng.next();
+    }
+}
+
+/** Box–Muller Gaussian sample from the active source. */
+export function randn(std = 1): number {
+    const u1 = Math.max(_next(), 1e-12);
+    const u2 = _next();
+    return std * Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+}
+
+/** Returns a Float32Array of `n` Gaussian samples with the given standard deviation. */
+export function gaussianArray(n: number, std: number): Float32Array {
+    const a = new Float32Array(n);
+    for (let i = 0; i < n; i++) a[i] = randn(std);
+    return a;
+}