@seanhogg/builderforce-memory-engine 2026.6.39 → 2026.7.12

package/dist/training/trainer.d.ts

@@ -14,22 +14,54 @@ export interface TrainOptions {
     beta2?: number;
     eps?: number;
     wsla?: boolean;
-    onEpochEnd?: ((epoch: number, loss: number) => void) | null;
+    /** Trust region: max |Δθ| per optimizer step. 0 disables. Defaults to
+     *  {@link WSLA_MAX_DELTA} in WSLA (write-through) mode, else 0 (full training). */
+    maxDelta?: number;
+    /** Read back the pre-clip gradient L2 norm each step (the `grad_norm_reduce`
+     *  kernel already computes it — this just maps it to the CPU). OFF by default: the
+     *  readback is a GPU sync point that would slow a long finetune. `adapt()` turns it
+     *  ON so the norm reaches {@link AdaptResult} as an instability signal. */
+    trackGradNorm?: boolean;
+    onEpochEnd?: ((epoch: number, loss: number, gradNorm?: number) => void) | null;
 }
+/**
+ * Default per-step trust region for WSLA / write-through adaptation. Small
+ * enough that a single `adapt()` nudges the narrow params without lurching, so
+ * repeated adapts stay stable (and any that regress are cheaply rolled back by
+ * the session). Full-training callers pass `maxDelta: 0` (or omit it in
+ * non-WSLA mode) for unbounded steps.
+ */
+export declare const WSLA_MAX_DELTA = 0.05;
 export declare class MambaTrainer {
     model: HybridMambaModel;
     tokenizer: BPETokenizer | null;
     device: GPUDevice;
+    /**
+     * Adam moments keyed by parameter NAME (not array index). Name-keying is what
+     * lets WSLA toggle safely: a narrow write-through step updates only the
+     * `layer{i}.wXProj/bXProj` subset, a full fine-tune updates everything, and
+     * both reuse the SAME `m`/`v` buffers per parameter. Index-keyed moments (the
+     * old scheme) silently misaligned the moment with the wrong parameter the
+     * moment the trainable set changed shape — corrupting the update.
+     */
     private _moments;
     private _step;
     private _adamwPipeline;
     private _clipReducePipeline;
     private _clipScalePipeline;
     constructor(model: HybridMambaModel | MambaModel, tokenizer?: BPETokenizer | null);
-    private _initMoments;
+    /** Get-or-create the Adam first/second moments for a parameter, by name. */
+    private _momentFor;
     train(input: string | number[], opts?: TrainOptions): Promise<number[]>;
     private _trainStep;
     private _adamwStep;
+    /**
+     * Clip gradients to `maxNorm` in place. The reduce kernel writes Σg² into
+     * `normSqBuf`; the scale kernel then rescales the grads. When `trackNorm` is set
+     * we read Σg² back and return the true pre-clip L2 norm (√Σg²) — the kernel
+     * already computed it, so this is only a small buffer readback (a GPU sync,
+     * hence opt-in). Returns null when not tracking.
+     */
     private _clipGradients;
     evaluate(input: string | number[]): Promise<number>;
 }

package/dist/training/trainer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trainer.d.ts","sourceRoot":"","sources":["../../src/training/trainer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAcH,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7D;AAiBD,qBAAa,YAAY;IACrB,KAAK,EAAE,gBAAgB,CAAC;IACxB,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,kBAAkB,CAAqB;gBAEnC,KAAK,EAAE,gBAAgB,GAAG,UAAU,EAAE,SAAS,GAAE,YAAY,GAAG,IAAW;IAavF,OAAO,CAAC,YAAY;IAQd,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAkEnE,UAAU;YAkDV,UAAU;YAgCV,cAAc;IAuBtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CA4B5D"}
+{"version":3,"file":"trainer.d.ts","sourceRoot":"","sources":["../../src/training/trainer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAeH,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;uFACmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;+EAG2E;IAC3E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAChF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AAkBnC,qBAAa,YAAY;IACrB,KAAK,EAAE,gBAAgB,CAAC;IACxB,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,kBAAkB,CAAqB;gBAEnC,KAAK,EAAE,gBAAgB,GAAG,UAAU,EAAE,SAAS,GAAE,YAAY,GAAG,IAAW;IAavF,4EAA4E;IAC5E,OAAO,CAAC,UAAU;IAYZ,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YA2EnE,UAAU;YAqDV,UAAU;IAiCxB;;;;;;OAMG;YACW,cAAc;IAgCtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CA4B5D"}

package/dist/training/trainer.js

@@ -1,13 +1,29 @@
 /**
  * trainer.ts – MambaTrainer class
  */
-import { createUniformBuffer, createStorageBuffer, createEmptyStorageBuffer, createComputePipeline, createBindGroup, dispatchKernel, cdiv, } from '../utils/gpu_utils.js';
+import { createUniformBuffer, createStorageBuffer, createEmptyStorageBuffer, createComputePipeline, createBindGroup, dispatchKernel, readBuffer, cdiv, } from '../utils/gpu_utils.js';
 import { crossEntropyLoss, crossEntropyGrad } from './autograd.js';
 import { WEIGHT_UPDATE_WGSL, GRAD_CLIP_WGSL } from '../kernels/weight_update.js';
+/**
+ * Default per-step trust region for WSLA / write-through adaptation. Small
+ * enough that a single `adapt()` nudges the narrow params without lurching, so
+ * repeated adapts stay stable (and any that regress are cheaply rolled back by
+ * the session). Full-training callers pass `maxDelta: 0` (or omit it in
+ * non-WSLA mode) for unbounded steps.
+ */
+export const WSLA_MAX_DELTA = 0.05;
 export class MambaTrainer {
     model;
     tokenizer;
     device;
+    /**
+     * Adam moments keyed by parameter NAME (not array index). Name-keying is what
+     * lets WSLA toggle safely: a narrow write-through step updates only the
+     * `layer{i}.wXProj/bXProj` subset, a full fine-tune updates everything, and
+     * both reuse the SAME `m`/`v` buffers per parameter. Index-keyed moments (the
+     * old scheme) silently misaligned the moment with the wrong parameter the
+     * moment the trainable set changed shape — corrupting the update.
+     */
     _moments;
     _step;
     _adamwPipeline;
@@ -17,22 +33,28 @@ export class MambaTrainer {
         this.model = model;
         this.tokenizer = tokenizer;
         this.device = model.device;
-        this._moments = null;
+        this._moments = new Map();
         this._step = 0;
         this._adamwPipeline = createComputePipeline(this.device, WEIGHT_UPDATE_WGSL, 'adamw_update');
         this._clipReducePipeline = createComputePipeline(this.device, GRAD_CLIP_WGSL, 'grad_norm_reduce');
         this._clipScalePipeline = createComputePipeline(this.device, GRAD_CLIP_WGSL, 'grad_clip_scale');
     }
-    _initMoments() {
-        if (this._moments)
-            return;
-        this._moments = this.model.parameters().map(p => ({
-            m: createEmptyStorageBuffer(this.device, p.numel * 4, false),
-            v: createEmptyStorageBuffer(this.device, p.numel * 4, false),
-        }));
+    /** Get-or-create the Adam first/second moments for a parameter, by name. */
+    _momentFor(p) {
+        let mom = this._moments.get(p.name);
+        if (!mom) {
+            mom = {
+                m: createEmptyStorageBuffer(this.device, p.numel * 4, false),
+                v: createEmptyStorageBuffer(this.device, p.numel * 4, false),
+            };
+            this._moments.set(p.name, mom);
+        }
+        return mom;
     }
     async train(input, opts = {}) {
-        const { learningRate = 1e-4, epochs = 5, batchSize = 1, seqLen = 512, maxGradNorm = 1.0, weightDecay = 0.01, beta1 = 0.9, beta2 = 0.999, eps = 1e-8, wsla = false, onEpochEnd = null, } = opts;
+        const { learningRate = 1e-4, epochs = 5, batchSize = 1, seqLen = 512, maxGradNorm = 1.0, weightDecay = 0.01, beta1 = 0.9, beta2 = 0.999, eps = 1e-8, wsla = false, trackGradNorm = false, onEpochEnd = null, } = opts;
+        // Trust region defaults ON for write-through (WSLA) adapts, OFF otherwise.
+        const maxDelta = opts.maxDelta ?? (wsla ? WSLA_MAX_DELTA : 0);
         if (wsla)
             this.model.setWSLAMode(true);
         let tokenIds;
@@ -53,27 +75,34 @@ export class MambaTrainer {
         if (chunks.length === 0) {
             throw new Error('Input is too short to form any training chunk.');
         }
-        this._initMoments();
+        // Moments are created lazily per-parameter (name-keyed) on first touch —
+        // no upfront allocation needed, and it stays correct as WSLA narrows the
+        // trainable set.
         const epochLosses = [];
         for (let epoch = 0; epoch < epochs; epoch++) {
             let epochLoss = 0;
+            let epochGradNorm = 0;
             let numSteps = 0;
             for (const { inputs, targets } of chunks) {
-                const loss = await this._trainStep(inputs, targets, batchSize, { learningRate, maxGradNorm, weightDecay, beta1, beta2, eps, wsla });
+                const { loss, gradNorm } = await this._trainStep(inputs, targets, batchSize, { learningRate, maxGradNorm, weightDecay, beta1, beta2, eps, wsla, maxDelta, trackGradNorm });
                 epochLoss += loss;
+                if (gradNorm != null)
+                    epochGradNorm += gradNorm;
                 numSteps++;
             }
             const avgLoss = epochLoss / numSteps;
             epochLosses.push(avgLoss);
+            // Mean pre-clip grad norm this epoch (only measured when trackGradNorm is on).
+            const avgGradNorm = trackGradNorm ? epochGradNorm / numSteps : undefined;
             if (onEpochEnd)
-                onEpochEnd(epoch + 1, avgLoss);
+                onEpochEnd(epoch + 1, avgLoss, avgGradNorm);
         }
         if (wsla)
             this.model.setWSLAMode(false);
         return epochLosses;
     }
     async _trainStep(inputs, targets, batch, hyperparams) {
-        const { learningRate, maxGradNorm, weightDecay, beta1, beta2, eps } = hyperparams;
+        const { learningRate, maxGradNorm, weightDecay, beta1, beta2, eps, maxDelta, trackGradNorm } = hyperparams;
         this._step++;
         const seqLen = inputs.length;
         const vocabSize = this.model.config.vocabSize;
@@ -92,35 +121,46 @@ export class MambaTrainer {
         }
         const loss = totalLoss / seqLen;
         const dLogitsBuf = createStorageBuffer(this.device, dLogits, false);
-        await this._clipGradients(dLogitsBuf, dLogits.length, maxGradNorm);
-        const params = this.model.parameters();
+        const gradNorm = await this._clipGradients(dLogitsBuf, dLogits.length, maxGradNorm, !!trackGradNorm);
+        // Only the trainable set is updated. Under WSLA (write-through) that is
+        // the narrow per-layer subset and the backbone (incl. every A_log) stays
+        // frozen — the guarantee that repeated adapts can't destabilise the SSM.
+        const params = this.model.getTrainableParams();
         const beta1_t = Math.pow(beta1, this._step);
         const beta2_t = Math.pow(beta2, this._step);
-        await this._adamwStep(params, [dLogitsBuf], { learningRate, weightDecay, beta1, beta2, eps, beta1_t, beta2_t });
+        await this._adamwStep(params, [dLogitsBuf], { learningRate, weightDecay, beta1, beta2, eps, beta1_t, beta2_t, maxDelta });
         dLogitsBuf.destroy();
         gpuLogits.destroy();
-        return loss;
+        return { loss, gradNorm };
     }
     async _adamwStep(params, gradBufs, hp) {
-        const { learningRate, weightDecay, beta1, beta2, eps, beta1_t, beta2_t } = hp;
+        const { learningRate, weightDecay, beta1, beta2, eps, beta1_t, beta2_t, maxDelta } = hp;
         for (let i = 0; i < params.length; i++) {
             const p = params[i];
             const gradBuf = gradBufs[Math.min(i, gradBufs.length - 1)];
             if (!gradBuf || gradBuf.size < p.numel * 4)
                 continue;
-            const paramsBuf = createUniformBuffer(this.device, packAdamParams(p.numel, learningRate, beta1, beta2, eps, weightDecay, beta1_t, beta2_t));
+            const mom = this._momentFor(p);
+            const paramsBuf = createUniformBuffer(this.device, packAdamParams(p.numel, learningRate, beta1, beta2, eps, weightDecay, beta1_t, beta2_t, maxDelta));
             const bg = createBindGroup(this.device, this._adamwPipeline, [
                 paramsBuf,
                 p.buf,
                 gradBuf,
-                this._moments[i].m,
-                this._moments[i].v,
+                mom.m,
+                mom.v,
             ]);
             dispatchKernel(this.device, this._adamwPipeline, bg, [cdiv(p.numel, 256), 1, 1]);
             paramsBuf.destroy();
         }
     }
-    async _clipGradients(gradBuf, numel, maxNorm) {
+    /**
+     * Clip gradients to `maxNorm` in place. The reduce kernel writes Σg² into
+     * `normSqBuf`; the scale kernel then rescales the grads. When `trackNorm` is set
+     * we read Σg² back and return the true pre-clip L2 norm (√Σg²) — the kernel
+     * already computed it, so this is only a small buffer readback (a GPU sync,
+     * hence opt-in). Returns null when not tracking.
+     */
+    async _clipGradients(gradBuf, numel, maxNorm, trackNorm = false) {
         const normSqBuf = createEmptyStorageBuffer(this.device, 4, true);
         this.device.queue.writeBuffer(normSqBuf, 0, new Float32Array([0.0]));
         const clipParams = new ArrayBuffer(8);
@@ -129,10 +169,18 @@ export class MambaTrainer {
         const pBuf = createUniformBuffer(this.device, clipParams);
         const bg1 = createBindGroup(this.device, this._clipReducePipeline, [pBuf, gradBuf, normSqBuf]);
         dispatchKernel(this.device, this._clipReducePipeline, bg1, [cdiv(numel, 256), 1, 1]);
+        // Read Σg² AFTER the reduce (the scale kernel only reads it, never overwrites),
+        // so the returned norm is the pre-clip magnitude — the instability signal.
+        let gradNorm = null;
+        if (trackNorm) {
+            const out = await readBuffer(this.device, normSqBuf, 4);
+            gradNorm = Math.sqrt(Math.max(0, out[0] ?? 0));
+        }
         const bg2 = createBindGroup(this.device, this._clipScalePipeline, [pBuf, gradBuf, normSqBuf]);
         dispatchKernel(this.device, this._clipScalePipeline, bg2, [cdiv(numel, 256), 1, 1]);
         pBuf.destroy();
         normSqBuf.destroy();
+        return gradNorm;
     }
     async evaluate(input) {
         let tokenIds;
@@ -174,10 +222,12 @@ function buildChunks(ids, seqLen) {
     }
     return chunks;
 }
-function packAdamParams(numElements, lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t) {
-    const buf = new ArrayBuffer(32);
+function packAdamParams(numElements, lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t, maxDelta) {
+    // 48 bytes: u32 + 8×f32 = 36, padded to a 16-byte multiple for the uniform
+    // layout (matches AdamParams' _pad0.._pad2 in WEIGHT_UPDATE_WGSL).
+    const buf = new ArrayBuffer(48);
     new Uint32Array(buf, 0, 1).set([numElements]);
-    new Float32Array(buf, 4, 7).set([lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t]);
+    new Float32Array(buf, 4, 8).set([lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t, maxDelta]);
     return buf;
 }
 //# sourceMappingURL=trainer.js.map

package/dist/training/trainer.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory-engine",
-  "version": "2026.6.39",
+  "version": "2026.7.12",
   "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/codec/evermind_video.ts

@@ -0,0 +1,55 @@
+/**
+ * evermind_video.ts — thin bridge that makes the EXISTING EvermindLM generate
+ * video. No new model, no new generator: the codec turns frames into tokens, the
+ * unqualified `EvermindLM.generate` autoregresses over them, and the codec turns
+ * the emitted tokens back into frames. Deliberately DRY — everything the text
+ * path already has (sampling, checkpoints, delta export, training) is reused.
+ */
+
+import type { EvermindLM, LMGenerateOptions } from "../lm/evermind_lm.js";
+import type { VideoRVQCodec, Video, Frame } from "./video_rvq.js";
+import type { ImageRVQCodec } from "./image_rvq.js";
+
+/**
+ * Build a unified training sequence `text… <vid> frames… </vid>` for
+ * `EvermindLMTrainer.fit`. `textTokens` are ids in the codec's text region (from
+ * a BPE tokenizer whose vocab size equals `codec.vocab.textVocabSize`). Training
+ * the LM on many such sequences is what teaches text→video.
+ */
+export function buildVideoSequence(codec: VideoRVQCodec, textTokens: number[], video: Video): number[] {
+  return [...textTokens, ...codec.encode(video)];
+}
+
+/**
+ * Generate video from a prompt of already-tokenised context (text ids and/or a
+ * partial video stream). The prompt should normally end just before or at the
+ * `<vid>` marker; generation stops at `</vid>` or after `maxNewTokens`.
+ *
+ * Returns the decoded clip plus the raw produced token ids (useful for chaining
+ * or continued generation).
+ */
+export function generateVideo(
+  lm: EvermindLM,
+  codec: VideoRVQCodec,
+  promptTokens: number[],
+  opts: LMGenerateOptions,
+): { video: Video; tokens: number[] } {
+  if (lm.config.vocabSize !== codec.vocabSize) {
+    throw new Error(
+      `generateVideo: EvermindLM vocabSize (${lm.config.vocabSize}) must equal codec.vocabSize (${codec.vocabSize})`,
+    );
+  }
+  const tokens = lm.generate(promptTokens, { ...opts, stopToken: opts.stopToken ?? codec.vocab.eosVideo });
+  return { video: codec.decode(tokens), tokens };
+}
+
+/** Generate a single image — the still-image case of {@link generateVideo}. */
+export function generateImage(
+  lm: EvermindLM,
+  codec: ImageRVQCodec,
+  promptTokens: number[],
+  opts: LMGenerateOptions,
+): { image: Frame; tokens: number[] } {
+  const { video, tokens } = generateVideo(lm, codec.video, promptTokens, opts);
+  return { image: video[0] ?? new Float32Array(codec.frameSize), tokens };
+}

package/src/codec/image_rvq.ts

@@ -0,0 +1,50 @@
+/**
+ * image_rvq.ts — ImageRVQCodec: still-image generation as the single-frame case
+ * of {@link VideoRVQCodec}. An image has no temporal axis, so every frame is a
+ * keyframe (intra) — this wrapper just fixes `keyframeInterval = 1` and speaks in
+ * single frames instead of clips. Deliberately thin: it reuses the video codec's
+ * patchify + residual-VQ + learned codebooks + tolerant decode wholesale, so
+ * there is exactly one implementation to maintain.
+ */
+
+import { VideoRVQCodec, type VideoRVQConfig, type Frame } from "./video_rvq.js";
+
+export type { Frame } from "./video_rvq.js";
+
+export class ImageRVQCodec {
+  /** The underlying video codec (pass to `generateVideo`/`generateImage`). */
+  readonly video: VideoRVQCodec;
+
+  constructor(config: Omit<VideoRVQConfig, "keyframeInterval">) {
+    this.video = new VideoRVQCodec({ ...config, keyframeInterval: 1 });
+  }
+
+  get vocab() {
+    return this.video.vocab;
+  }
+  get vocabSize(): number {
+    return this.video.vocabSize;
+  }
+  get frameSize(): number {
+    return this.video.height * this.video.width * this.video.channels;
+  }
+
+  /** Encode one image to a `<vid> <key> codes… </vid>` token stream. */
+  encode(image: Frame): number[] {
+    return this.video.encode([image]);
+  }
+
+  /** Decode a token stream to a single image (zeros if the stream yields no frame). */
+  decode(tokens: number[]): Frame {
+    const frames = this.video.decode(tokens);
+    return frames[0] ?? new Float32Array(this.frameSize);
+  }
+
+  /** Learn codebooks from a set of images (each is a one-frame clip). Returns recon MSE. */
+  fit(images: Frame[], opts?: { iterations?: number; seed?: number }): number {
+    return this.video.fit(
+      images.map((im) => [im]),
+      opts,
+    );
+  }
+}

package/src/codec/index.ts

@@ -0,0 +1,16 @@
+/**
+ * codec/ — modality codecs that turn non-text media into the discrete token
+ * streams Evermind's generator already speaks. Today: video (temporal residual
+ * VQ). Images are the single-frame case; audio/other modalities follow the same
+ * "media ⇄ tokens + unified vocab" shape.
+ */
+
+export { MultimodalVocab, VIDEO_BANK_INTRA, VIDEO_BANK_INTER } from "./multimodal_vocab.js";
+export type { MultimodalVocabConfig, TokenKind } from "./multimodal_vocab.js";
+
+export { VideoRVQCodec } from "./video_rvq.js";
+export type { VideoRVQConfig, Frame, Video } from "./video_rvq.js";
+
+export { ImageRVQCodec } from "./image_rvq.js";
+
+export { buildVideoSequence, generateVideo, generateImage } from "./evermind_video.js";

package/src/codec/multimodal_vocab.ts

@@ -0,0 +1,115 @@
+/**
+ * multimodal_vocab.ts — one flat token space shared by text and video.
+ *
+ * Evermind's generator ({@link ../lm/evermind_lm.EvermindLM}) is a pure
+ * next-token predictor: it neither knows nor cares whether a token id is a BPE
+ * text piece or a quantised video-patch code. So "make Evermind generate video"
+ * is a *vocabulary* problem, not a model problem — lay text tokens, a handful of
+ * modality control tokens, and the video codebook codes out on a single integer
+ * axis, and the same model handles `(caption … <vid> … frames … </vid>)`.
+ *
+ * Layout (low → high):
+ *
+ *   [ 0 .. textVocabSize )                     text (BPE) — passthrough
+ *   textVocabSize + 0                          <vid>   (BOS_VIDEO)
+ *   textVocabSize + 1                          </vid>  (EOS_VIDEO)
+ *   textVocabSize + 2                          <key>   (start of an intra frame)
+ *   textVocabSize + 3                          <delta> (start of an inter frame)
+ *   codeBase + bank·levels·K + level·K + code  residual-VQ code tokens
+ *
+ * where `bank ∈ {INTRA, INTER}`, `level ∈ [0, levels)`, `code ∈ [0, K)` and
+ * `K = codebookSize`. A frame is therefore a marker followed by
+ * `patchesPerFrame · levels` code tokens — a deterministic, self-delimiting
+ * structure the codec can parse straight out of the generator's output.
+ */
+
+export const VIDEO_BANK_INTRA = 0;
+export const VIDEO_BANK_INTER = 1;
+
+export interface MultimodalVocabConfig {
+  /** Size of the text (BPE) region; 0 for a pure-video model. */
+  textVocabSize: number;
+  /** Residual-VQ depth (codes emitted per patch). */
+  levels: number;
+  /** Entries per codebook per level per bank. */
+  codebookSize: number;
+}
+
+/** What a token id decodes to when parsing a mixed stream. */
+export type TokenKind =
+  | { kind: "text"; id: number }
+  | { kind: "control"; control: "bosVideo" | "eosVideo" | "frameKey" | "frameDelta" }
+  | { kind: "code"; bank: number; level: number; code: number };
+
+/**
+ * Bijective map between (text ids, control tokens, video codes) and a single
+ * flat token id space. Owns the offset arithmetic so nothing else has to.
+ */
+export class MultimodalVocab {
+  readonly textVocabSize: number;
+  readonly levels: number;
+  readonly codebookSize: number;
+
+  readonly bosVideo: number;
+  readonly eosVideo: number;
+  readonly frameKey: number;
+  readonly frameDelta: number;
+  readonly codeBase: number;
+  /** Total vocabulary size — pass this as EvermindLM's `vocabSize`. */
+  readonly size: number;
+
+  private readonly perBank: number;
+
+  constructor(cfg: MultimodalVocabConfig) {
+    if (cfg.textVocabSize < 0) throw new Error("MultimodalVocab: textVocabSize must be ≥ 0");
+    if (cfg.levels <= 0 || cfg.codebookSize <= 0) throw new Error("MultimodalVocab: levels and codebookSize must be > 0");
+    this.textVocabSize = cfg.textVocabSize;
+    this.levels = cfg.levels;
+    this.codebookSize = cfg.codebookSize;
+
+    this.bosVideo = cfg.textVocabSize;
+    this.eosVideo = cfg.textVocabSize + 1;
+    this.frameKey = cfg.textVocabSize + 2;
+    this.frameDelta = cfg.textVocabSize + 3;
+    this.codeBase = cfg.textVocabSize + 4;
+    this.perBank = cfg.levels * cfg.codebookSize;
+    this.size = this.codeBase + 2 * this.perBank;
+  }
+
+  /** Global token id for a residual-VQ code. */
+  codeToken(bank: number, level: number, code: number): number {
+    return this.codeBase + bank * this.perBank + level * this.codebookSize + code;
+  }
+
+  isText(tok: number): boolean {
+    return tok >= 0 && tok < this.textVocabSize;
+  }
+
+  isCode(tok: number): boolean {
+    return tok >= this.codeBase && tok < this.size;
+  }
+
+  isVideoMarker(tok: number): boolean {
+    return tok === this.frameKey || tok === this.frameDelta;
+  }
+
+  /** Decompose a code token into (bank, level, code). Level/code are meaningful even if the bank differs. */
+  decodeCode(tok: number): { bank: number; level: number; code: number } {
+    const idx = tok - this.codeBase;
+    const bank = Math.floor(idx / this.perBank);
+    const rem = idx - bank * this.perBank;
+    const level = Math.floor(rem / this.codebookSize);
+    const code = rem - level * this.codebookSize;
+    return { bank, level, code };
+  }
+
+  /** Classify any token id in the flat space. */
+  classify(tok: number): TokenKind {
+    if (this.isText(tok)) return { kind: "text", id: tok };
+    if (tok === this.bosVideo) return { kind: "control", control: "bosVideo" };
+    if (tok === this.eosVideo) return { kind: "control", control: "eosVideo" };
+    if (tok === this.frameKey) return { kind: "control", control: "frameKey" };
+    if (tok === this.frameDelta) return { kind: "control", control: "frameDelta" };
+    return { kind: "code", ...this.decodeCode(tok) };
+  }
+}