@seanhogg/builderforce-memory-engine 2026.7.14 → 2026.9.27

package/src/evermind/merge.ts

@@ -0,0 +1,106 @@
+/**
+ * evermind/merge.ts — the conflict resolver for concurrent Evermind learning.
+ *
+ * Many learners adapt their LOCAL replica of the same model version and each
+ * produces a row-sparse weight delta (`diffCheckpoints(base, adapted)`). A single
+ * writer folds N such deltas into one canonical update here, then republishes.
+ *
+ * Merge policy = **FedAvg over contributors**: each delta stores the contributor's
+ * ABSOLUTE new values for the elements it touched, so the merged value of an element
+ * is the (optionally sample-weighted) MEAN of the contributors that touched it.
+ * Elements only one learner touched take that learner's value; non-touchers do NOT
+ * vote the base value back in (a lone real update is kept, not diluted toward base).
+ *
+ * Pure, GPU-free and deterministic — the math lives here, isolated from whatever
+ * storage/orchestration the host wraps around it.
+ */
+import {
+  applyCheckpointDiff,
+  deserializeRowDelta,
+  serializeRowDelta,
+  type RowDelta,
+} from "../utils/delta.js";
+import { verifyCrcTrailer } from "../utils/crc32.js";
+
+export interface MergeResult {
+  /** The new canonical checkpoint (base + merged delta), ready to repackage. */
+  checkpoint: ArrayBuffer;
+  /** How many distinct elements the merged delta touches. */
+  mergedRows: number;
+  /** How many contributor deltas were folded in. */
+  contributors: number;
+  /** L2 norm of the ACTUAL weight movement base→merged, (Σ(merged−base)²)^½. 0 when nothing moved. */
+  deltaNorm: number;
+}
+
+/** Per-element weighted accumulator while merging. */
+interface Acc {
+  sum: number;
+  weight: number;
+}
+
+/**
+ * Fold contributor weight-deltas (each a serialized RowDelta vs the SAME base) into
+ * one merged checkpoint by FedAvg-over-contributors.
+ *
+ * @param baseCheckpoint the canonical checkpoint the deltas were diffed against
+ * @param diffs          serialized RowDelta buffers (from `diffCheckpoints`)
+ * @param weights        optional per-diff sample weights (default 1 each = plain mean);
+ *                       a zero/negative weight excludes that contributor
+ */
+export function mergeCheckpointDiffs(
+  baseCheckpoint: ArrayBuffer,
+  diffs: ArrayBuffer[],
+  weights?: number[],
+): MergeResult {
+  if (diffs.length === 0) {
+    return { checkpoint: baseCheckpoint, mergedRows: 0, contributors: 0, deltaNorm: 0 };
+  }
+  if (weights && weights.length !== diffs.length) {
+    throw new Error(`mergeCheckpointDiffs: weights length ${weights.length} != diffs length ${diffs.length}`);
+  }
+
+  const parsed: RowDelta[] = diffs.map((d) => deserializeRowDelta(d));
+  // `diffCheckpoints` emits element-granular (rowSize 1) deltas, which is what makes
+  // element-wise FedAvg exact: a partially-overlapping merge can never zero a column.
+  for (const rd of parsed) {
+    if (rd.rowSize !== 1) {
+      throw new Error(`mergeCheckpointDiffs: expected element-granular deltas (rowSize 1), got ${rd.rowSize}`);
+    }
+  }
+
+  const acc = new Map<number, Acc>();
+  parsed.forEach((rd, k) => {
+    const w = weights ? weights[k]! : 1;
+    if (!(w > 0)) return;
+    rd.rows.forEach((idx, i) => {
+      const value = rd.data[i]!;
+      const prev = acc.get(idx);
+      if (prev) { prev.sum += w * value; prev.weight += w; }
+      else acc.set(idx, { sum: w * value, weight: w });
+    });
+  });
+
+  if (acc.size === 0) {
+    return { checkpoint: baseCheckpoint, mergedRows: 0, contributors: parsed.length, deltaNorm: 0 };
+  }
+
+  const rows = [...acc.keys()].sort((a, b) => a - b);
+  const data = new Float32Array(rows.length);
+  rows.forEach((idx, i) => {
+    const a = acc.get(idx)!;
+    data[i] = a.sum / a.weight;
+  });
+
+  // The merged delta stores ABSOLUTE values, so movement is (merged − base) per element.
+  const baseBody = new Float32Array(verifyCrcTrailer(baseCheckpoint).body);
+  let sumSq = 0;
+  rows.forEach((idx, i) => {
+    const moved = data[i]! - (baseBody[idx] ?? 0);
+    sumSq += moved * moved;
+  });
+
+  const merged: RowDelta = { rowSize: 1, rows, data };
+  const checkpoint = applyCheckpointDiff(baseCheckpoint, serializeRowDelta(merged));
+  return { checkpoint, mergedRows: rows.length, contributors: parsed.length, deltaNorm: Math.sqrt(sumSq) };
+}

package/src/{moe/moe_package.ts → evermind/package.ts}

@@ -1,5 +1,5 @@
 /**
- * moe_package.ts — EvermindModelPackage: the portable, publishable AI artifact.
+ * evermind/package.ts — EvermindModelPackage: the portable, publishable AI artifact.
  *
  * This is the unit a creator publishes to the marketplace and a buyer downloads
  * and runs: a self-describing manifest (name, version, config, model card,
@@ -11,9 +11,10 @@
  * browser (where models are trained) and in Node/Workers (where they execute).
  */
 
-import { SharedExpertMoE, type MoEConfig } from "./moe_model.js";
+import { SharedExpertMoE, type MoEConfig } from "../moe/moe_model.js";
 import { EvermindLM, type EvermindLMConfig } from "../lm/evermind_lm.js";
 import { VideoRVQCodec } from "../codec/video_rvq.js";
+import { BPETokenizer } from "../tokenizer/bpe.js";
 
 /** First 4 bytes of a serialised package: "EVM1". */
 const PKG_MAGIC = 0x45564d31;
@@ -60,8 +61,27 @@ export interface EvermindModelManifest {
   checksum: number;
   /** Media codec section format (present for video/image packages). */
   codecFormat?: "VRQ0";
+  /**
+   * Byte length of the codec section — REQUIRED when a tokenizer section follows.
+   * Absent ⇒ the codec runs to end-of-blob (the original media layout).
+   */
+  codecBytes?: number;
   /** 32-bit FNV-1a over the codec bytes — integrity for the bundled codec. */
   codecChecksum?: number;
+  /**
+   * Embedded-tokenizer section format. Token ids are meaningless without the exact
+   * vocabulary that produced them, so a package that carries one is self-contained:
+   * a consumer no longer has to source the matching vocab separately (and can no
+   * longer pair the wrong one with it). Absent ⇒ no tokenizer embedded, which every
+   * package written before this field is — those still load exactly as before.
+   */
+  tokenizerFormat?: "BPE0";
+  /** Byte length of the tokenizer section (always last). */
+  tokenizerBytes?: number;
+  /** 32-bit FNV-1a over the tokenizer bytes. */
+  tokenizerChecksum?: number;
+  /** Vocabulary size of the embedded tokenizer — cross-checked against the model's. */
+  tokenizerVocabSize?: number;
   card: EvermindModelCard;
   /** ISO timestamp, caller-supplied (the engine avoids Date for determinism). */
   createdAt?: string;
@@ -73,6 +93,12 @@ export interface PackageMeta {
   card: EvermindModelCard;
   /** Store the checkpoint in fp16 (half the size). Default false. */
   fp16?: boolean;
+  /**
+   * Embed this tokenizer in the package, making the artifact self-contained.
+   * Its `vocabSize` must equal the model's, or packaging throws — a mismatched
+   * pair produces confident nonsense, which is worse than a failure to publish.
+   */
+  tokenizer?: BPETokenizer;
   createdAt?: string;
 }
 
@@ -102,12 +128,45 @@ export class EvermindModelPackage {
     readonly checkpoint: ArrayBuffer,
     /** Serialized media codec ("VRQ0" blob), present for video/image packages. */
     readonly codec?: ArrayBuffer,
+    /** Serialized BPE tokenizer ("BPE0" blob) — present when the package embeds one. */
+    readonly tokenizer?: ArrayBuffer,
   ) {}
 
+  /**
+   * Serialise `meta.tokenizer` and the manifest fields describing it, or `{}` when
+   * no tokenizer was supplied. Shared by every `from*` factory so the vocab-size
+   * cross-check exists in exactly one place.
+   */
+  private static _tokenizerSection(
+    meta: PackageMeta,
+    modelVocabSize: number | undefined,
+  ): { blob?: ArrayBuffer; fields: Partial<EvermindModelManifest> } {
+    if (!meta.tokenizer) return { fields: {} };
+    const vocabSize = meta.tokenizer.vocabSize;
+    if (modelVocabSize != null && vocabSize !== modelVocabSize) {
+      throw new Error(
+        `EvermindModelPackage: tokenizer vocabSize (${vocabSize}) must equal the model's (${modelVocabSize}) — ` +
+        "a mismatched pair decodes to nonsense.",
+      );
+    }
+    const blob = meta.tokenizer.serialize();
+    return {
+      blob,
+      fields: {
+        tokenizerFormat: "BPE0",
+        tokenizerBytes: blob.byteLength,
+        tokenizerChecksum: fnv1a(new Uint8Array(blob)),
+        tokenizerVocabSize: vocabSize,
+      },
+    };
+  }
+
   /** Package a trained model with its publishing metadata. */
   static fromModel(model: SharedExpertMoE, meta: PackageMeta): EvermindModelPackage {
     const fp16 = meta.fp16 ?? false;
     const checkpoint = model.exportWeights({ fp16 });
+    // A bare MoE layer has no vocabulary of its own, so there is nothing to cross-check.
+    const tokenizer = EvermindModelPackage._tokenizerSection(meta, undefined);
     const manifest: EvermindModelManifest = {
       schema: "evermind.model/1",
       name: meta.name,
@@ -117,17 +176,20 @@ export class EvermindModelPackage {
       paramCount: model.parameters().reduce((n, p) => n + p.numel, 0),
       checkpointFormat: "MoE0",
       checkpointFp16: fp16,
+      ...(tokenizer.blob ? { checkpointBytes: checkpoint.byteLength } : {}),
       checksum: fnv1a(new Uint8Array(checkpoint)),
+      ...tokenizer.fields,
       card: meta.card,
       ...(meta.createdAt ? { createdAt: meta.createdAt } : {}),
     };
-    return new EvermindModelPackage(manifest, checkpoint);
+    return new EvermindModelPackage(manifest, checkpoint, undefined, tokenizer.blob);
   }
 
   /** Package a trained generative {@link EvermindLM} — the runnable marketplace AI. */
   static fromLM(lm: EvermindLM, meta: PackageMeta): EvermindModelPackage {
     const fp16 = meta.fp16 ?? false;
     const checkpoint = lm.exportWeights({ fp16 });
+    const tokenizer = EvermindModelPackage._tokenizerSection(meta, lm.config.vocabSize);
     const manifest: EvermindModelManifest = {
       schema: "evermind.model/1",
       name: meta.name,
@@ -137,11 +199,13 @@ export class EvermindModelPackage {
       paramCount: lm.parameters().reduce((n, p) => n + p.data.length, 0),
       checkpointFormat: "EVL0",
       checkpointFp16: fp16,
+      ...(tokenizer.blob ? { checkpointBytes: checkpoint.byteLength } : {}),
       checksum: fnv1a(new Uint8Array(checkpoint)),
+      ...tokenizer.fields,
       card: meta.card,
       ...(meta.createdAt ? { createdAt: meta.createdAt } : {}),
     };
-    return new EvermindModelPackage(manifest, checkpoint);
+    return new EvermindModelPackage(manifest, checkpoint, undefined, tokenizer.blob);
   }
 
   /**
@@ -163,6 +227,7 @@ export class EvermindModelPackage {
     const fp16 = meta.fp16 ?? false;
     const checkpoint = lm.exportWeights({ fp16 });
     const codecBlob = codec.serialize();
+    const tokenizer = EvermindModelPackage._tokenizerSection(meta, lm.config.vocabSize);
     const manifest: EvermindModelManifest = {
       schema: "evermind.model/1",
       name: meta.name,
@@ -176,19 +241,28 @@ export class EvermindModelPackage {
       checkpointBytes: checkpoint.byteLength,
       checksum: fnv1a(new Uint8Array(checkpoint)),
       codecFormat: "VRQ0",
+      ...(tokenizer.blob ? { codecBytes: codecBlob.byteLength } : {}),
       codecChecksum: fnv1a(new Uint8Array(codecBlob)),
+      ...tokenizer.fields,
       card: meta.card,
       ...(meta.createdAt ? { createdAt: meta.createdAt } : {}),
     };
-    return new EvermindModelPackage(manifest, checkpoint, codecBlob);
+    return new EvermindModelPackage(manifest, checkpoint, codecBlob, tokenizer.blob);
   }
 
-  /** Serialise to a single `.evermind` blob: magic, version, manifest, checkpoint[, codec]. */
+  /**
+   * Serialise to a single `.evermind` blob: magic, version, manifest, checkpoint
+   * [, codec][, tokenizer]. Each section's length is fixed in the manifest whenever
+   * another section follows it, so the reader never has to guess where one ends.
+   */
   toBlob(): ArrayBuffer {
     const manifestBytes = new TextEncoder().encode(JSON.stringify(this.manifest));
     const headerBytes = 12; // magic, version, manifestLen
     const codecBytes = this.codec?.byteLength ?? 0;
-    const out = new ArrayBuffer(headerBytes + manifestBytes.byteLength + this.checkpoint.byteLength + codecBytes);
+    const tokBytes = this.tokenizer?.byteLength ?? 0;
+    const out = new ArrayBuffer(
+      headerBytes + manifestBytes.byteLength + this.checkpoint.byteLength + codecBytes + tokBytes,
+    );
     const head = new Uint32Array(out, 0, 3);
     head[0] = PKG_MAGIC;
     head[1] = PKG_VERSION;
@@ -198,10 +272,15 @@ export class EvermindModelPackage {
     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));
+    if (this.codec) {
+      new Uint8Array(out, o, codecBytes).set(new Uint8Array(this.codec));
+      o += codecBytes;
+    }
+    if (this.tokenizer) new Uint8Array(out, o, tokBytes).set(new Uint8Array(this.tokenizer));
     return out;
   }
 
+
   /** Parse a `.evermind` blob. Throws on bad magic / truncation. */
   static fromBlob(buffer: ArrayBuffer): EvermindModelPackage {
     if (buffer.byteLength < 12) throw new Error("EvermindModelPackage.fromBlob: truncated (no header)");
@@ -215,18 +294,35 @@ export class EvermindModelPackage {
     const manifestBytes = new Uint8Array(buffer, headerBytes, manifestLen);
     const manifest = JSON.parse(new TextDecoder().decode(manifestBytes)) as EvermindModelManifest;
     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).
+    // Sections run checkpoint -> codec -> tokenizer, each present only when the
+    // manifest says so. A section's length is explicit whenever another follows it;
+    // the last section runs to end-of-blob. That keeps every package written before
+    // the codec and tokenizer sections existed readable byte for byte.
     const cpBytes = manifest.checkpointBytes;
-    if (cpBytes != null) {
-      if (bodyStart + cpBytes > buffer.byteLength) {
-        throw new Error("EvermindModelPackage.fromBlob: truncated (checkpointBytes exceeds blob)");
+    if (cpBytes == null) return new EvermindModelPackage(manifest, buffer.slice(bodyStart));
+    if (bodyStart + cpBytes > buffer.byteLength) {
+      throw new Error("EvermindModelPackage.fromBlob: truncated (checkpointBytes exceeds blob)");
+    }
+    const checkpoint = buffer.slice(bodyStart, bodyStart + cpBytes);
+    let o = bodyStart + cpBytes;
+
+    const tokBytes = manifest.tokenizerBytes ?? 0;
+    if (o + tokBytes > buffer.byteLength) {
+      throw new Error("EvermindModelPackage.fromBlob: truncated (tokenizerBytes exceeds blob)");
+    }
+    const tokStart = buffer.byteLength - tokBytes;
+
+    let codec: ArrayBuffer | undefined;
+    if (o < tokStart) {
+      const codecEnd = manifest.codecBytes != null ? o + manifest.codecBytes : tokStart;
+      if (codecEnd > tokStart) {
+        throw new Error("EvermindModelPackage.fromBlob: truncated (codecBytes overruns the tokenizer section)");
       }
-      const checkpoint = buffer.slice(bodyStart, bodyStart + cpBytes);
-      const codec = bodyStart + cpBytes < buffer.byteLength ? buffer.slice(bodyStart + cpBytes) : undefined;
-      return new EvermindModelPackage(manifest, checkpoint, codec);
+      codec = buffer.slice(o, codecEnd);
+      o = codecEnd;
     }
-    return new EvermindModelPackage(manifest, buffer.slice(bodyStart));
+    const tokenizer = tokBytes > 0 ? buffer.slice(tokStart) : undefined;
+    return new EvermindModelPackage(manifest, checkpoint, codec, tokenizer);
   }
 
   /** Verify integrity + structural sanity before trusting a downloaded package. */
@@ -262,9 +358,44 @@ export class EvermindModelPackage {
         }
       }
     }
+    // An embedded tokenizer must be intact AND agree with the model's vocabulary —
+    // a corrupt or mismatched one decodes confidently into nonsense.
+    if (this.manifest.tokenizerFormat) {
+      if (!this.tokenizer) {
+        errors.push("manifest declares an embedded tokenizer but the package has no tokenizer section");
+      } else {
+        const tokActual = fnv1a(new Uint8Array(this.tokenizer));
+        if (tokActual !== this.manifest.tokenizerChecksum) {
+          errors.push(
+            `tokenizer checksum mismatch (manifest ${this.manifest.tokenizerChecksum}, actual ${tokActual}) - corrupt tokenizer`,
+          );
+        }
+        const modelVocab = this.manifest.config?.['vocabSize'];
+        const tokVocab = this.manifest.tokenizerVocabSize;
+        if (modelVocab != null && tokVocab != null && modelVocab !== tokVocab) {
+          errors.push(`tokenizer vocabSize (${tokVocab}) does not match the model's (${modelVocab})`);
+        }
+      }
+    }
     return { ok: errors.length === 0, errors };
   }
 
+  /**
+   * The tokenizer embedded in this package, or `null` when it carries none.
+   *
+   * A package WITH one is self-contained: a consumer runs `loadLM()` +
+   * `loadTokenizer()` and can turn text into tokens and back with the exact
+   * vocabulary the model was trained on. A package without one still loads — every
+   * artifact published before this section existed is in that shape — but the
+   * consumer must supply the matching vocabulary itself.
+   */
+  loadTokenizer(): BPETokenizer | null {
+    if (!this.manifest.tokenizerFormat || !this.tokenizer) return null;
+    const v = this.validate();
+    if (!v.ok) throw new Error(`EvermindModelPackage.loadTokenizer: ${v.errors.join("; ")}`);
+    return BPETokenizer.deserialize(this.tokenizer);
+  }
+
   /** Reconstruct the bare MoE layer. Validates first; throws if invalid / wrong type. */
   loadModel(): SharedExpertMoE {
     const v = this.validate();

package/src/import/foreign/adapter.ts

@@ -0,0 +1,106 @@
+/**
+ * import/foreign/adapter.ts — what every foreign-architecture adapter provides,
+ * plus the shared `config.json` readers so no adapter re-implements them.
+ *
+ * An adapter answers two questions about a published checkpoint:
+ *   1. what {@link HybridMambaModelConfig} do these weights fit? and
+ *   2. which {@link PortPlan} moves them onto this engine's parameters?
+ * Everything downstream (detection, execution, upload) is architecture-agnostic.
+ */
+
+import type { HybridMambaModelConfig } from "../../model/mamba_model.js";
+import type { PortPlan } from "./plan.js";
+
+/** A checkpoint's parsed `config.json` (HF) or `params.json` (Mistral-native). */
+export type ForeignConfig = Record<string, unknown>;
+
+/** Everything a port needs to know about one checkpoint. */
+export interface PortTarget {
+  /** Construct a `HybridMambaModel` with this to receive the ported weights. */
+  modelConfig: HybridMambaModelConfig;
+  plan: PortPlan;
+}
+
+export interface ForeignMambaAdapter {
+  /** Stable id, e.g. `falcon_mamba`. */
+  readonly id: string;
+  /** Human-readable label for errors and reports. */
+  readonly label: string;
+  /** `config.model_type` values this adapter claims. */
+  readonly modelTypes: readonly string[];
+  /** `config.architectures[]` entries this adapter claims. */
+  readonly architectures: readonly string[];
+  /** Read the checkpoint's geometry and build its port plan. */
+  describe(config: ForeignConfig): PortTarget;
+}
+
+// ── config.json readers ──────────────────────────────────────────────────────
+
+function fail(key: string, detail: string): never {
+  throw new Error(`import/foreign: config field "${key}" ${detail}`);
+}
+
+/** A positive integer field, required. */
+export function requireInt(config: ForeignConfig, key: string): number {
+  const v = config[key];
+  if (typeof v !== "number" || !Number.isInteger(v) || v <= 0) {
+    fail(key, `must be a positive integer, got ${JSON.stringify(v)}`);
+  }
+  return v;
+}
+
+/** The first of `keys` present as a positive integer, else `undefined`. */
+export function firstInt(config: ForeignConfig, keys: readonly string[]): number | undefined {
+  for (const key of keys) {
+    const v = config[key];
+    if (typeof v === "number" && Number.isInteger(v) && v > 0) return v;
+  }
+  return undefined;
+}
+
+/**
+ * The mixer's inner width.
+ *
+ * `intermediate_size` is authoritative and `expand` is NOT trustworthy:
+ * `tiiuae/falcon-mamba-7b` ships `expand: 16` against `hidden_size: 4096` while
+ * its weights are `d_inner = 8192`. Transformers only tolerates it because the
+ * JSON's `intermediate_size` is re-applied over the derived value, so a port
+ * that trusted `expand` would build a model 8× too wide. Fall back to
+ * `expand * hidden_size` only when `intermediate_size` is absent.
+ */
+export function readInnerSize(config: ForeignConfig, dModel: number): number {
+  const stated = firstInt(config, ["intermediate_size"]);
+  if (stated !== undefined) return stated;
+  const expand = firstInt(config, ["expand"]);
+  if (expand === undefined) {
+    fail("intermediate_size", "is absent and no usable \"expand\" was found");
+  }
+  return expand * dModel;
+}
+
+/**
+ * `d_inner / d_model` as this engine's integer `expand` factor — the blocks size
+ * themselves from it, so a non-integer ratio cannot be represented and must fail
+ * loudly rather than silently truncate.
+ */
+export function expandFactor(dInner: number, dModel: number, label: string): number {
+  if (dInner % dModel !== 0) {
+    throw new Error(
+      `import/foreign: ${label} has d_inner ${dInner} which is not a whole multiple of ` +
+        `d_model ${dModel} — this engine's blocks are sized by an integer expand factor`,
+    );
+  }
+  return dInner / dModel;
+}
+
+/**
+ * `time_step_rank`, resolving HF's `"auto"` to `ceil(hidden_size / 16)` — the
+ * same default `Mamba1Block` applies, so an `"auto"` checkpoint and this engine
+ * agree without the caller doing anything.
+ */
+export function readTimeStepRank(config: ForeignConfig, dModel: number): number {
+  const v = config["time_step_rank"];
+  if (typeof v === "number" && Number.isInteger(v) && v > 0) return v;
+  if (v === undefined || v === "auto") return Math.ceil(dModel / 16);
+  fail("time_step_rank", `must be a positive integer or "auto", got ${JSON.stringify(v)}`);
+}

package/src/import/foreign/apply.ts

@@ -0,0 +1,54 @@
+/**
+ * import/foreign/apply.ts — write ported weights into a live model.
+ *
+ * Kept separate from the port itself so the mapping stays device-free and
+ * testable: {@link portForeignMamba} produces plain `Float32Array`s, this is the
+ * only piece that needs a `GPUDevice`.
+ *
+ * Matching is by parameter NAME, never by position, so a change to
+ * `HybridMambaModel.parameters()` ordering can never silently mis-assign a
+ * buffer — an unexpected or missing name throws instead.
+ */
+
+import type { HybridMambaModel } from "../../model/mamba_model.js";
+import { uploadBuffer } from "../../utils/gpu_utils.js";
+import type { PortedTensors } from "./plan.js";
+
+/**
+ * Upload every ported tensor into `model`'s parameter buffers.
+ *
+ * Throws when the model expects a parameter the port did not produce, when an
+ * element count disagrees, or when the port produced a name the model does not
+ * have — all three mean the model was built from a different config than
+ * {@link PortedCheckpoint.modelConfig}.
+ */
+export function applyPortedWeights(model: HybridMambaModel, ported: PortedTensors): void {
+  const params = model.parameters();
+  const expected = new Set(params.map((p) => p.name));
+
+  const extra = [...ported.weights.keys()].filter((name) => !expected.has(name));
+  if (extra.length > 0) {
+    throw new Error(
+      `import/foreign: ported tensors ${extra.slice(0, 5).map((n) => `"${n}"`).join(", ")}` +
+        `${extra.length > 5 ? ` (+${extra.length - 5} more)` : ""} have no parameter on this model — ` +
+        `build it from the port's modelConfig`,
+    );
+  }
+
+  for (const param of params) {
+    const data = ported.weights.get(param.name);
+    if (!data) {
+      throw new Error(
+        `import/foreign: no ported tensor for parameter "${param.name}" — ` +
+          `the model was built from a different config than the port's modelConfig`,
+      );
+    }
+    if (data.length !== param.numel) {
+      throw new Error(
+        `import/foreign: parameter "${param.name}" expects ${param.numel} elements, ` +
+          `the port produced ${data.length}`,
+      );
+    }
+    uploadBuffer(model.device, param.buf, data);
+  }
+}