@seanhogg/builderforce-memory-engine 2026.6.35 → 2026.7.11

package/src/import/safetensors.ts

@@ -0,0 +1,67 @@
+/**
+ * import/safetensors.ts — read weights FROM the HF-native `.safetensors` format.
+ *
+ * The exact inverse of {@link ../export/safetensors.ts}: parse the 8-byte
+ * little-endian u64 header length, the JSON header (name → {dtype, shape,
+ * data_offsets}), then decode each tensor's raw bytes into a Float32Array.
+ * F32 and F16 are supported (F16 is widened to f32 on read). This is the reader
+ * half of the warm-start / weight-port path — export was one-directional before.
+ */
+
+import type { NamedTensor } from "../export/tensors.js";
+import { fp16ToFloat } from "../utils/quantization.js";
+
+interface HeaderEntry {
+  dtype: string;
+  shape: number[];
+  data_offsets: [number, number];
+}
+
+/** Decode a `.safetensors` byte buffer into named F32 tensors (header order). */
+export function safetensorsToTensors(bytes: Uint8Array): NamedTensor[] {
+  if (bytes.length < 8) throw new Error("safetensors: buffer too short for header length");
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const headerLen = Number(dv.getBigUint64(0, true));
+  const headerEnd = 8 + headerLen;
+  if (headerEnd > bytes.length) throw new Error(`safetensors: header length ${headerLen} exceeds buffer`);
+
+  const headerJson = new TextDecoder().decode(bytes.subarray(8, headerEnd));
+  let header: Record<string, unknown>;
+  try {
+    header = JSON.parse(headerJson) as Record<string, unknown>;
+  } catch (e) {
+    throw new Error(`safetensors: malformed JSON header (${e instanceof Error ? e.message : String(e)})`);
+  }
+
+  const dataBase = headerEnd;
+  const out: NamedTensor[] = [];
+  for (const [name, raw] of Object.entries(header)) {
+    if (name === "__metadata__") continue;
+    const entry = raw as HeaderEntry;
+    if (!entry || !Array.isArray(entry.shape) || !Array.isArray(entry.data_offsets)) {
+      throw new Error(`safetensors: malformed entry for "${name}"`);
+    }
+    const [start, end] = entry.data_offsets;
+    const numel = entry.shape.reduce((n, d) => n * d, 1);
+    const seg = bytes.subarray(dataBase + start, dataBase + end);
+    out.push({ name, shape: entry.shape, data: decodeTensor(seg, entry.dtype, numel, name) });
+  }
+  return out;
+}
+
+function decodeTensor(seg: Uint8Array, dtype: string, numel: number, name: string): Float32Array {
+  const dv = new DataView(seg.buffer, seg.byteOffset, seg.byteLength);
+  const data = new Float32Array(numel);
+  const d = dtype.toUpperCase();
+  if (d === "F32" || d === "FLOAT32") {
+    if (seg.length < numel * 4) throw new Error(`safetensors: "${name}" F32 bytes ${seg.length} < ${numel * 4}`);
+    for (let i = 0; i < numel; i++) data[i] = dv.getFloat32(i * 4, true);
+    return data;
+  }
+  if (d === "F16" || d === "FLOAT16") {
+    if (seg.length < numel * 2) throw new Error(`safetensors: "${name}" F16 bytes ${seg.length} < ${numel * 2}`);
+    for (let i = 0; i < numel; i++) data[i] = fp16ToFloat(dv.getUint16(i * 2, true));
+    return data;
+  }
+  throw new Error(`safetensors: unsupported dtype "${dtype}" for "${name}" (expected F32 or F16)`);
+}

package/src/index.ts

@@ -33,6 +33,8 @@ export type {
     MoEEpochResult,
     EvermindModelManifest,
     EvermindModelCard,
+    EvermindModelType,
+    EvermindModality,
     PackageMeta,
     ValidationResult,
 } from './moe/index.js';
@@ -60,6 +62,27 @@ export {
 // ── Tokenizer ─────────────────────────────────────────────────────────────────
 
 export { BPETokenizer } from './tokenizer/bpe.js';
+export type { BPEEncodeOptions, PadSide, HuggingFaceTokenizerSpec, SpecialTokenOverrides } from './tokenizer/bpe.js';
+
+// ── Modality codecs (media ⇄ tokens; lets EvermindLM generate video) ────────────
+
+export {
+    MultimodalVocab,
+    VIDEO_BANK_INTRA,
+    VIDEO_BANK_INTER,
+    VideoRVQCodec,
+    ImageRVQCodec,
+    buildVideoSequence,
+    generateVideo,
+    generateImage,
+} from './codec/index.js';
+export type {
+    MultimodalVocabConfig,
+    TokenKind,
+    VideoRVQConfig,
+    Frame,
+    Video,
+} from './codec/index.js';
 
 // ── Model export (the publishing step: ONNX / safetensors / GGUF / HF repo) ─────
 
@@ -90,6 +113,16 @@ export type {
     TensorSpec,
 } from './export/index.js';
 
+// ── Model import (warm-start / weight-port: safetensors → EvermindLM) ────────────
+
+export {
+    safetensorsToTensors,
+    importEvermind,
+    importEvermindTensors,
+    inferArchFromTensors,
+} from './import/index.js';
+export type { ImportOptions } from './import/index.js';
+
 // ── Benchmarking (held-out perplexity / accuracy / throughput + A/B) ──────────
 
 export {
@@ -220,6 +253,7 @@ export {
     neutralState,
     stateToRecord,
     recordToState,
+    personalitySetpoint,
     LimbicModel,
     DEFAULT_LIMBIC_CONFIG,
     DEFAULT_LIMBIC_SEED,
@@ -228,6 +262,7 @@ export {
 export type {
     Region,
     LimbicDimName,
+    PersonalityTraits,
     LimbicModelConfig,
     LimbicForward,
     LimbicParam,

package/src/kernels/selective_scan.ts

@@ -60,12 +60,15 @@ fn softplus(x: f32) -> f32 {
 //   B_bar = (A_bar - 1) / A * B  ≈  Δ * B  (first-order for simplicity)
 fn discretise_A(delta_val: f32, a_log: f32) -> f32 {
     // A is stored as -exp(a_log) to ensure A_bar < 1 (stable)
-    let a_cont = -exp(a_log);
+    // Clamp log-decay so -exp(a_log) can't overflow to -Inf (A_bar→0, state
+    // death) nor collapse toward 0 (A_bar→1, no decay). Keeps A_bar strictly in
+    // (0,1) across repeated adapts. Belt-and-suspenders: WSLA also freezes A_log.
+    let a_cont = -exp(clamp(a_log, -10.0, 5.0));
     return exp(delta_val * a_cont);
 }
 
 fn discretise_B(delta_val: f32, a_log: f32, b_val: f32) -> f32 {
-    let a_cont  = -exp(a_log);
+    let a_cont  = -exp(clamp(a_log, -10.0, 5.0));
     let a_bar   = exp(delta_val * a_cont);
     // (A_bar - 1) / A_cont * B
     let b_bar   = (a_bar - 1.0) / a_cont * b_val;
@@ -264,7 +267,10 @@ fn softplus_grad(x: f32) -> f32 {
 }
 
 fn discretise_A(delta_val: f32, a_log: f32) -> f32 {
-    let a_cont = -exp(a_log);
+    // Clamp log-decay so -exp(a_log) can't overflow to -Inf (A_bar→0, state
+    // death) nor collapse toward 0 (A_bar→1, no decay). Keeps A_bar strictly in
+    // (0,1) across repeated adapts. Belt-and-suspenders: WSLA also freezes A_log.
+    let a_cont = -exp(clamp(a_log, -10.0, 5.0));
     return exp(delta_val * a_cont);
 }
 

package/src/kernels/ssd.ts

@@ -50,7 +50,10 @@ struct SsdParams {
 @group(0) @binding(9) var<storage, read_write> state_carry : array<f32>; // [n_chunks+1,B,H,N,d_head]
 
 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) — and a downstream
+    // exp(-Inf*0) then yields NaN, poisoning the state. This form never overflows.
+    return max(x, 0.0) + log(1.0 + exp(-abs(x)));
 }
 
 // Workgroup: one chunk × one head × one batch item
@@ -186,7 +189,10 @@ struct SsdParams {
 @group(0) @binding(14) var<storage, read_write> dD_vec     : 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) — and a downstream
+    // exp(-Inf*0) then yields NaN, poisoning the state. This form never overflows.
+    return max(x, 0.0) + log(1.0 + exp(-abs(x)));
 }
 fn d_softplus(x: f32) -> f32 {
     return 1.0 / (1.0 + exp(-x));

package/src/kernels/weight_update.ts

@@ -19,6 +19,10 @@ struct AdamParams {
     weight_decay   : f32,   // default 0.01
     beta1_t        : f32,   // beta1^t  (precomputed bias correction term)
     beta2_t        : f32,   // beta2^t
+    max_delta      : f32,   // trust region: max |Δθ| per step (0 ⇒ unbounded)
+    _pad0          : f32,   // pad struct to a 16-byte multiple (uniform layout)
+    _pad1          : f32,
+    _pad2          : f32,
 };
 
 @group(0) @binding(0) var<uniform>             adam     : AdamParams;
@@ -52,9 +56,24 @@ fn adamw_update(
     let m_hat = m_new / (1.0 - adam.beta1_t);
     let v_hat = v_new / (1.0 - adam.beta2_t);
 
-    // Weight decay (decoupled) + gradient step
-    param[i] = p * (1.0 - adam.lr * adam.weight_decay) -
-               adam.lr * m_hat / (sqrt(v_hat) + adam.eps);
+    // Adam step.
+    var step = adam.lr * m_hat / (sqrt(v_hat) + adam.eps);
+
+    // Numerical guard: never write a non-finite step into a weight. A NaN or Inf
+    // here (from a bad gradient, a zero v_hat, an overflow) would permanently
+    // poison the parameter and every future forward — the "model dies" failure.
+    // NaN fails self-comparison; treat ±Inf-magnitude as non-finite too.
+    if (step != step || step > 3.4e38 || step < -3.4e38) { step = 0.0; }
+
+    // Trust region: bound how far ONE step can move a weight. With write-through
+    // adaptation running repeatedly, an unbounded step (even from a noisy
+    // gradient) compounds across executions and blows the weights up; clamping
+    // the per-element delta keeps every adapt small and reversible. max_delta==0
+    // disables the bound (full-training callers that don't set it).
+    if (adam.max_delta > 0.0) { step = clamp(step, -adam.max_delta, adam.max_delta); }
+
+    // Weight decay (decoupled) + bounded gradient step
+    param[i] = p * (1.0 - adam.lr * adam.weight_decay) - step;
 }
 `;
 

package/src/limbic/index.ts

@@ -18,8 +18,9 @@ export {
   neutralState,
   stateToRecord,
   recordToState,
+  personalitySetpoint,
 } from "./regions.js";
-export type { Region, LimbicDimName } from "./regions.js";
+export type { Region, LimbicDimName, PersonalityTraits } from "./regions.js";
 
 export { LimbicModel, DEFAULT_LIMBIC_CONFIG, DEFAULT_LIMBIC_SEED } from "./limbic_model.js";
 export type { LimbicModelConfig, LimbicForward, LimbicParam } from "./limbic_model.js";

package/src/limbic/regions.ts

@@ -139,3 +139,63 @@ export function recordToState(rec: Partial<Record<LimbicDimName, number>>): Floa
   }
   return s;
 }
+
+/**
+ * The static psychometric traits (0..100, 50 = neutral) that pull the resting
+ * affective setpoint away from {@link NEUTRAL_STATE}. A subset of the full
+ * personality vector — only the dimensions that map to a limbic drive. All
+ * optional; an omitted trait is treated as neutral (50).
+ *
+ * Keep the mapping in {@link personalitySetpoint} in sync with the runtime
+ * compiler `deriveLimbicSetpoints` in `@builderforce/agent-tools` so the on-prem
+ * runtime, the cloud engine, and this WebGPU trainer settle on the SAME baseline
+ * for the same personality. The two are coupled only by this mapping.
+ */
+export interface PersonalityTraits {
+  openness?: number;
+  emotionality?: number;
+  conscientiousness?: number;
+  extraversion?: number;
+  /** Regulatory focus: 0 = prevention, 100 = promotion. */
+  regulatoryFocus?: number;
+  riskTolerance?: number;
+  grit?: number;
+  /** Schwartz "stimulation" value. */
+  stimulation?: number;
+}
+
+/** Signed influence of a 0..100 trait around its neutral midpoint → [-1, 1]. */
+function infl(s: number | undefined): number {
+  const v = typeof s === "number" && !Number.isNaN(s) ? Math.max(0, Math.min(100, s)) : 50;
+  return (v - 50) / 50;
+}
+
+/**
+ * Derive the personality-conditioned resting SETPOINT from a trait vector — the
+ * homeostatic target the limbic dynamics relax toward and that the trainable
+ * affect model rides on top of ("personality = setpoints, limbic = dynamics").
+ * Returns a fresh clamped 8-dim state vector. A fully-neutral trait vector yields
+ * {@link NEUTRAL_STATE}. Mirrors `deriveLimbicSetpoints` in `@builderforce/agent-tools`.
+ */
+export function personalitySetpoint(traits: PersonalityTraits | undefined): Float32Array {
+  const s = neutralState();
+  if (!traits) return s;
+  const open = infl(traits.openness);
+  const emo = infl(traits.emotionality);
+  const consc = infl(traits.conscientiousness);
+  const extra = infl(traits.extraversion);
+  const reg = infl(traits.regulatoryFocus);
+  const risk = infl(traits.riskTolerance);
+  const grit = infl(traits.grit);
+  const stim = infl(traits.stimulation);
+
+  s[LIMBIC_DIM.driveCuriosity] = clampDim(LIMBIC_DIM.driveCuriosity, 0.5 + 0.35 * open + 0.15 * stim);
+  s[LIMBIC_DIM.exploration] = clampDim(LIMBIC_DIM.exploration, 0.4 + 0.3 * open + 0.25 * risk + 0.15 * reg);
+  s[LIMBIC_DIM.driveCaution] = clampDim(LIMBIC_DIM.driveCaution, 0.5 + 0.3 * consc - 0.3 * risk - 0.2 * reg + 0.15 * emo);
+  s[LIMBIC_DIM.arousal] = clampDim(LIMBIC_DIM.arousal, 0.2 + 0.2 * emo + 0.1 * extra);
+  s[LIMBIC_DIM.driveSocial] = clampDim(LIMBIC_DIM.driveSocial, 0.5 + 0.35 * extra);
+  s[LIMBIC_DIM.driveEffort] = clampDim(LIMBIC_DIM.driveEffort, 0.8 + 0.15 * grit + 0.1 * consc);
+  s[LIMBIC_DIM.valence] = clampDim(LIMBIC_DIM.valence, 0.0 + 0.1 * reg - 0.1 * emo);
+  s[LIMBIC_DIM.attention] = clampDim(LIMBIC_DIM.attention, 0.7 + 0.1 * consc);
+  return s;
+}

package/src/model/mamba_model.ts

@@ -413,6 +413,33 @@ export class HybridMambaModel {
         return params;
     }
 
+    /**
+     * The parameters a `learn()` / `adapt()` step is allowed to update.
+     *
+     * Under WSLA (write-through / narrow adaptation — the Evermind "update ==
+     * replace" path) this is ONLY the per-layer narrow subset (the input
+     * projections that produce Δ/B/C). The backbone — token embedding, final
+     * norm, and every block's `A_log` / conv / output projection — stays FROZEN.
+     * Freezing `A_log` is the key stability guarantee: the state-transition
+     * decay can never drift into a degenerate regime (state death / no-decay)
+     * across repeated adapts, which is what made the model "die after several
+     * executions". Outside WSLA every parameter trains (full fine-tune / distill).
+     *
+     * Param names are namespaced `layer{i}.{name}` to match {@link parameters},
+     * so a name-keyed optimizer (see MambaTrainer) reuses the same Adam moments
+     * whether it's stepping the full set or just the WSLA subset.
+     */
+    getTrainableParams(): LayerParam[] {
+        if (!this._wslaMode) return this.parameters();
+        const params: LayerParam[] = [];
+        for (let i = 0; i < this.layers.length; i++) {
+            for (const p of this.layers[i]!.getTrainableParams()) {
+                params.push({ ...p, name: `layer${i}.${p.name}` });
+            }
+        }
+        return params;
+    }
+
     setWSLAMode(enabled: boolean): void {
         for (const layer of this.layers) layer.setWSLAMode(enabled);
         this._wslaMode = enabled;

package/src/moe/index.ts

@@ -18,6 +18,7 @@ export type {
   EvermindModelManifest,
   EvermindModelCard,
   EvermindModelType,
+  EvermindModality,
   PackageMeta,
   ValidationResult,
 } from "./moe_package.js";

package/src/moe/moe_package.ts

@@ -13,6 +13,7 @@
 
 import { SharedExpertMoE, type MoEConfig } from "./moe_model.js";
 import { EvermindLM, type EvermindLMConfig } from "../lm/evermind_lm.js";
+import { VideoRVQCodec } from "../codec/video_rvq.js";
 
 /** First 4 bytes of a serialised package: "EVM1". */
 const PKG_MAGIC = 0x45564d31;
@@ -21,6 +22,9 @@ const PKG_VERSION = 1;
 /** The kinds of model an `.evermind` package can carry. */
 export type EvermindModelType = "shared-expert-moe" | "evermind-lm";
 
+/** Output modality. `text` (default) needs no codec; `video`/`image` bundle a VRQ codec. */
+export type EvermindModality = "text" | "video" | "image";
+
 /** Human-facing description published with the model (the "model card"). */
 export interface EvermindModelCard {
   description: string;
@@ -38,14 +42,26 @@ export interface EvermindModelManifest {
   name: string;
   version: string;
   modelType: EvermindModelType;
+  /** Output modality; absent ⇒ "text". Video/image also carry a `codec` section. */
+  modality?: EvermindModality;
   /** Flat numeric model config (the constructor args), serialised verbatim. */
   config: Record<string, number>;
   /** Total trainable scalar parameters (for sizing / pricing / display). */
   paramCount: number;
   checkpointFormat: "MoE0" | "EVL0";
   checkpointFp16: boolean;
+  /**
+   * Byte length of the checkpoint section — REQUIRED when a codec section follows
+   * (so the reader knows where the checkpoint ends). Absent ⇒ checkpoint runs to
+   * end-of-blob (the original text-only layout, still read verbatim).
+   */
+  checkpointBytes?: number;
   /** 32-bit FNV-1a over the checkpoint bytes — integrity for download/purchase. */
   checksum: number;
+  /** Media codec section format (present for video/image packages). */
+  codecFormat?: "VRQ0";
+  /** 32-bit FNV-1a over the codec bytes — integrity for the bundled codec. */
+  codecChecksum?: number;
   card: EvermindModelCard;
   /** ISO timestamp, caller-supplied (the engine avoids Date for determinism). */
   createdAt?: string;
@@ -84,6 +100,8 @@ export class EvermindModelPackage {
   constructor(
     readonly manifest: EvermindModelManifest,
     readonly checkpoint: ArrayBuffer,
+    /** Serialized media codec ("VRQ0" blob), present for video/image packages. */
+    readonly codec?: ArrayBuffer,
   ) {}
 
   /** Package a trained model with its publishing metadata. */
@@ -126,17 +144,61 @@ export class EvermindModelPackage {
     return new EvermindModelPackage(manifest, checkpoint);
   }
 
-  /** Serialise to a single `.evermind` blob: magic, version, manifest, checkpoint. */
+  /**
+   * Package a video/image generative model: its {@link EvermindLM} weights AND the
+   * {@link VideoRVQCodec} needed to turn generated tokens back into frames. Without
+   * the bundled codec a served media model would emit undecodable token ids — this
+   * is what makes an `.evermind` media artifact self-contained and servable.
+   */
+  static fromMediaLM(
+    lm: EvermindLM,
+    codec: VideoRVQCodec,
+    meta: PackageMeta & { modality: "video" | "image" },
+  ): EvermindModelPackage {
+    if (lm.config.vocabSize !== codec.vocabSize) {
+      throw new Error(
+        `fromMediaLM: LM vocabSize (${lm.config.vocabSize}) must equal codec.vocabSize (${codec.vocabSize})`,
+      );
+    }
+    const fp16 = meta.fp16 ?? false;
+    const checkpoint = lm.exportWeights({ fp16 });
+    const codecBlob = codec.serialize();
+    const manifest: EvermindModelManifest = {
+      schema: "evermind.model/1",
+      name: meta.name,
+      version: meta.version,
+      modelType: "evermind-lm",
+      modality: meta.modality,
+      config: lm.config as unknown as Record<string, number>,
+      paramCount: lm.parameters().reduce((n, p) => n + p.data.length, 0),
+      checkpointFormat: "EVL0",
+      checkpointFp16: fp16,
+      checkpointBytes: checkpoint.byteLength,
+      checksum: fnv1a(new Uint8Array(checkpoint)),
+      codecFormat: "VRQ0",
+      codecChecksum: fnv1a(new Uint8Array(codecBlob)),
+      card: meta.card,
+      ...(meta.createdAt ? { createdAt: meta.createdAt } : {}),
+    };
+    return new EvermindModelPackage(manifest, checkpoint, codecBlob);
+  }
+
+  /** Serialise to a single `.evermind` blob: magic, version, manifest, checkpoint[, codec]. */
   toBlob(): ArrayBuffer {
     const manifestBytes = new TextEncoder().encode(JSON.stringify(this.manifest));
     const headerBytes = 12; // magic, version, manifestLen
-    const out = new ArrayBuffer(headerBytes + manifestBytes.byteLength + this.checkpoint.byteLength);
+    const codecBytes = this.codec?.byteLength ?? 0;
+    const out = new ArrayBuffer(headerBytes + manifestBytes.byteLength + this.checkpoint.byteLength + codecBytes);
     const head = new Uint32Array(out, 0, 3);
     head[0] = PKG_MAGIC;
     head[1] = PKG_VERSION;
     head[2] = manifestBytes.byteLength;
-    new Uint8Array(out, headerBytes, manifestBytes.byteLength).set(manifestBytes);
-    new Uint8Array(out, headerBytes + manifestBytes.byteLength).set(new Uint8Array(this.checkpoint));
+    let o = headerBytes;
+    new Uint8Array(out, o, manifestBytes.byteLength).set(manifestBytes);
+    o += manifestBytes.byteLength;
+    new Uint8Array(out, o, this.checkpoint.byteLength).set(new Uint8Array(this.checkpoint));
+    o += this.checkpoint.byteLength;
+    if (this.codec) new Uint8Array(out, o, codecBytes).set(new Uint8Array(this.codec));
     return out;
   }
 
@@ -152,8 +214,19 @@ export class EvermindModelPackage {
     }
     const manifestBytes = new Uint8Array(buffer, headerBytes, manifestLen);
     const manifest = JSON.parse(new TextDecoder().decode(manifestBytes)) as EvermindModelManifest;
-    const checkpoint = buffer.slice(headerBytes + manifestLen);
-    return new EvermindModelPackage(manifest, checkpoint);
+    const bodyStart = headerBytes + manifestLen;
+    // A codec section follows the checkpoint only when the manifest fixed the
+    // checkpoint length; otherwise the checkpoint runs to end-of-blob (text layout).
+    const cpBytes = manifest.checkpointBytes;
+    if (cpBytes != null) {
+      if (bodyStart + cpBytes > buffer.byteLength) {
+        throw new Error("EvermindModelPackage.fromBlob: truncated (checkpointBytes exceeds blob)");
+      }
+      const checkpoint = buffer.slice(bodyStart, bodyStart + cpBytes);
+      const codec = bodyStart + cpBytes < buffer.byteLength ? buffer.slice(bodyStart + cpBytes) : undefined;
+      return new EvermindModelPackage(manifest, checkpoint, codec);
+    }
+    return new EvermindModelPackage(manifest, buffer.slice(bodyStart));
   }
 
   /** Verify integrity + structural sanity before trusting a downloaded package. */
@@ -176,6 +249,19 @@ export class EvermindModelPackage {
     if (actual !== this.manifest.checksum) {
       errors.push(`checksum mismatch (manifest ${this.manifest.checksum}, actual ${actual}) — corrupt or tampered checkpoint`);
     }
+    // Media packages must carry an integral codec — a served media model can't
+    // decode tokens → frames without it.
+    const modality = this.manifest.modality ?? "text";
+    if (modality === "video" || modality === "image") {
+      if (!this.codec) {
+        errors.push(`modality '${modality}' package is missing its codec section`);
+      } else {
+        const codecActual = fnv1a(new Uint8Array(this.codec));
+        if (codecActual !== this.manifest.codecChecksum) {
+          errors.push(`codec checksum mismatch (manifest ${this.manifest.codecChecksum}, actual ${codecActual}) — corrupt codec`);
+        }
+      }
+    }
     return { ok: errors.length === 0, errors };
   }
 
@@ -202,4 +288,19 @@ export class EvermindModelPackage {
     lm.loadWeights(this.checkpoint);
     return lm;
   }
+
+  /**
+   * Reconstruct a video/image model: the generative {@link EvermindLM} plus its
+   * {@link VideoRVQCodec}. Pair with `generateVideo` / `generateImage` to produce
+   * frames. This is what a media-serving path (gateway) loads and runs.
+   */
+  loadMediaLM(): { lm: EvermindLM; codec: VideoRVQCodec; modality: EvermindModality } {
+    const v = this.validate();
+    if (!v.ok) throw new Error(`EvermindModelPackage.loadMediaLM: ${v.errors.join("; ")}`);
+    const modality = this.manifest.modality ?? "text";
+    if (modality !== "video" && modality !== "image") {
+      throw new Error(`loadMediaLM: package modality is '${modality}', use loadLM()`);
+    }
+    return { lm: this.loadLM(), codec: VideoRVQCodec.deserialize(this.codec!), modality };
+  }
 }

package/src/tokenizer/bpe.ts

@@ -9,6 +9,21 @@ export interface BPEEncodeOptions {
 
 export type PadSide = 'right' | 'left';
 
+/** A Hugging Face `tokenizer.json` (or a bare `{ vocab, merges }`) for import. */
+export interface HuggingFaceTokenizerSpec {
+  model?: { vocab?: Record<string, number>; merges?: Array<string | [string, string]> };
+  vocab?: Record<string, number>;
+  merges?: Array<string | [string, string]>;
+}
+
+/** Override the special-token strings to match an imported tokenizer. */
+export interface SpecialTokenOverrides {
+  bos?: string;
+  eos?: string;
+  pad?: string;
+  unk?: string;
+}
+
 function buildByteEncoder(): Map<number, string> {
     const enc = new Map<number, string>();
     const ranges: [number, number][] = [
@@ -177,6 +192,50 @@ export class BPETokenizer {
         this.padId = this.vocab.get(this.padToken) ?? null;
     }
 
+    /**
+     * Seed this tokenizer from an existing Hugging Face `tokenizer.json` — the
+     * *import-merges* path (vs `train`, which learns a fresh vocab from a corpus).
+     *
+     * BPE merges + vocab are portable DATA, not architecture: a proven code
+     * tokenizer (GPT-2 / Llama / StarCoder family) gives Evermind a battle-tested
+     * code vocabulary on day one. Those tokenizers use the same GPT-2 byte→unicode
+     * mapping this class already implements ({@link BYTE_ENCODER}), so the imported
+     * vocab is directly compatible with `encode`/`decode`/`_bpe`.
+     *
+     * Accepts the full `tokenizer.json` object (reads `.model.vocab` / `.model.merges`)
+     * or a bare `{ vocab, merges }`. `merges` may be the classic `"a b"` strings or
+     * the newer `["a", "b"]` pair arrays. Special-token strings can be overridden to
+     * match the source tokenizer (e.g. `<|endoftext|>`, `<s>`, `</s>`).
+     */
+    loadHuggingFace(spec: HuggingFaceTokenizerSpec, specials: SpecialTokenOverrides = {}): void {
+        const model = (spec.model ?? spec) as { vocab?: Record<string, number>; merges?: Array<string | [string, string]> };
+        const vocabObj = model.vocab ?? (spec as HuggingFaceTokenizerSpec).vocab;
+        const rawMerges = model.merges ?? (spec as HuggingFaceTokenizerSpec).merges;
+        if (!vocabObj || typeof vocabObj !== 'object') {
+            throw new Error('loadHuggingFace: missing model.vocab (expected a Hugging Face tokenizer.json)');
+        }
+        if (!Array.isArray(rawMerges)) {
+            throw new Error('loadHuggingFace: missing model.merges (expected a BPE tokenizer.json)');
+        }
+        const mergeArr = rawMerges.map((m) => (Array.isArray(m) ? `${m[0]} ${m[1]}` : String(m)));
+        if (specials.bos) this.bosToken = specials.bos;
+        if (specials.eos) this.eosToken = specials.eos;
+        if (specials.pad) this.padToken = specials.pad;
+        if (specials.unk) this.unkToken = specials.unk;
+        this.loadFromObjects(vocabObj, mergeArr);
+    }
+
+    /**
+     * Fetch and import a Hugging Face `tokenizer.json` by URL — the IDE's
+     * "import merges from a repo" path. Resolves once the tokenizer is loaded.
+     */
+    async loadHuggingFaceUrl(url: string, specials: SpecialTokenOverrides = {}): Promise<void> {
+        const res = await fetch(url);
+        if (!res.ok) throw new Error(`loadHuggingFaceUrl: ${res.status} fetching ${url}`);
+        const spec = (await res.json()) as HuggingFaceTokenizerSpec;
+        this.loadHuggingFace(spec, specials);
+    }
+
     encode(text: string, opts: BPEEncodeOptions = {}): number[] {
         const words = text.match(PRE_TOKENIZE_RE) ?? [];
         const ids: number[]   = [];