@seanhogg/builderforce-memory-engine 2026.6.31 → 2026.6.35

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";

package/src/bench/metrics.ts

@@ -0,0 +1,98 @@
+/**
+ * bench/metrics.ts — pure scoring primitives over per-position logits.
+ *
+ * These are the building blocks the harness composes. They are exact, allocation
+ * -light, and numerically stable (cross-entropy reuses the engine's stable
+ * log-sum-exp). Nothing here trains or mutates the model — benchmarking is a
+ * read-only forward pass over held-out data.
+ */
+
+import { crossEntropyLoss } from "../training/autograd.js";
+
+/** Natural log of 2 — used to convert nats → bits. */
+export const LN2 = Math.LN2;
+
+/**
+ * Indices of the `k` largest logits, descending. O(V·k) — fine for the small
+ * top-k used in accuracy scoring; avoids a full sort of the vocab per position.
+ */
+export function topKIndices(logits: Float32Array, k: number): number[] {
+  const n = logits.length;
+  const kk = Math.max(1, Math.min(k, n));
+  const idx: number[] = [];
+  const used = new Uint8Array(n);
+  for (let s = 0; s < kk; s++) {
+    let best = -1;
+    let bestVal = -Infinity;
+    for (let i = 0; i < n; i++) {
+      if (used[i]) continue;
+      const v = logits[i]!;
+      if (v > bestVal) {
+        bestVal = v;
+        best = i;
+      }
+    }
+    if (best < 0) break;
+    used[best] = 1;
+    idx.push(best);
+  }
+  return idx;
+}
+
+/** Index of the single largest logit (argmax). */
+export function argmax(logits: Float32Array): number {
+  let best = 0;
+  let bestVal = -Infinity;
+  for (let i = 0; i < logits.length; i++) {
+    if (logits[i]! > bestVal) {
+      bestVal = logits[i]!;
+      best = i;
+    }
+  }
+  return best;
+}
+
+/** Perplexity from a mean cross-entropy (nats). */
+export function perplexity(meanCrossEntropy: number): number {
+  return Math.exp(meanCrossEntropy);
+}
+
+/** Bits-per-token from a mean cross-entropy (nats). */
+export function bitsPerToken(meanCrossEntropy: number): number {
+  return meanCrossEntropy / LN2;
+}
+
+/** Accumulator over predicted positions — cross-entropy + top-1/top-k hits. */
+export interface ScoreAccumulator {
+  tokens: number;
+  ceSum: number;
+  top1Hits: number;
+  topKHits: number;
+}
+
+export function newAccumulator(): ScoreAccumulator {
+  return { tokens: 0, ceSum: 0, top1Hits: 0, topKHits: 0 };
+}
+
+/**
+ * Score one (logits, targets) pair into the accumulator. `logits[t]` predicts
+ * `targets[t]`; positions with an out-of-range target are skipped. The caller
+ * aligns logits/targets (next-token: logits[0..T-2] predict tokens[1..T-1]).
+ */
+export function scoreInto(
+  acc: ScoreAccumulator,
+  logits: Float32Array[],
+  targets: number[],
+  k: number,
+): void {
+  const n = Math.min(logits.length, targets.length);
+  for (let t = 0; t < n; t++) {
+    const target = targets[t]!;
+    const lg = logits[t]!;
+    if (target < 0 || target >= lg.length) continue;
+    acc.ceSum += crossEntropyLoss(lg, target);
+    if (argmax(lg) === target) acc.top1Hits++;
+    if (topKIndices(lg, k).includes(target)) acc.topKHits++;
+    acc.tokens++;
+  }
+}

package/src/bench/types.ts

@@ -0,0 +1,121 @@
+/**
+ * bench/types.ts — public types for the Evermind benchmarking harness.
+ *
+ * Benchmarking answers the question the marketplace (and the "beats a frozen
+ * LLM" thesis) actually rests on: *how good is this model?* The harness measures
+ * a trained model on held-out data with the standard language-model yardsticks —
+ * perplexity, bits-per-token, and next-token accuracy — plus generation
+ * throughput, and can A/B two models (e.g. a quantized vs full-precision build,
+ * or a freshly-adapted vs prior checkpoint).
+ *
+ * The metrics operate on any object that can produce per-position logits from a
+ * token sequence — the engine's `EvermindLM` satisfies {@link LogitsModel}
+ * directly — so the harness is model-agnostic and dependency-free.
+ */
+
+/** The minimal surface a model must expose to be benchmarked: per-position logits. */
+export interface LogitsModel {
+  /** Run the model over a token sequence; returns one logit vector per position. */
+  forward(tokens: number[]): { logits: Float32Array[] };
+}
+
+/** A model whose forward pass is asynchronous (e.g. a WebGPU backend). */
+export interface AsyncLogitsModel {
+  forward(tokens: number[]): Promise<{ logits: Float32Array[] }>;
+}
+
+/** Knobs for a benchmark run. */
+export interface BenchmarkOptions {
+  /** k for top-k next-token accuracy. Default 5. */
+  topK?: number;
+  /** Measure forward throughput (tokens/sec). Default true. */
+  measureLatency?: boolean;
+  /**
+   * Monotonic clock in milliseconds, injectable for deterministic tests.
+   * Defaults to `performance.now()` when available, else `Date.now()`.
+   */
+  now?: () => number;
+}
+
+/** The scorecard a benchmark run produces. */
+export interface BenchmarkReport {
+  /** Number of evaluated sequences. */
+  sequences: number;
+  /** Number of predicted positions (next-token targets) scored. */
+  tokens: number;
+  /** Mean next-token cross-entropy, in nats. Lower is better. */
+  crossEntropy: number;
+  /** Perplexity = exp(crossEntropy). Lower is better; 1.0 is perfect. */
+  perplexity: number;
+  /** Bits per token = crossEntropy / ln(2). Lower is better. */
+  bitsPerToken: number;
+  /** Fraction of positions where the argmax prediction was correct (0..1). */
+  top1Accuracy: number;
+  /** Fraction of positions where the true token was in the top-k (0..1). */
+  topKAccuracy: number;
+  /** The k used for {@link topKAccuracy}. */
+  topK: number;
+  /** Forward throughput in tokens/sec, when {@link BenchmarkOptions.measureLatency}. */
+  tokensPerSecond?: number;
+  /** Wall-clock spent in the forward passes (ms), when measured. */
+  elapsedMs?: number;
+}
+
+/** The result of A/B-ing two models on the same eval set. */
+export interface ComparisonReport {
+  candidate: BenchmarkReport;
+  baseline: BenchmarkReport;
+  /** candidate.perplexity − baseline.perplexity (negative = candidate better). */
+  perplexityDelta: number;
+  /** candidate.perplexity / baseline.perplexity (<1 = candidate better). */
+  perplexityRatio: number;
+  /** candidate.top1Accuracy − baseline.top1Accuracy (positive = candidate better). */
+  top1Delta: number;
+  /** Which model won on perplexity (the primary metric). */
+  winner: "candidate" | "baseline" | "tie";
+  /** Human-readable one-liner. */
+  summary: string;
+}
+
+/** Options for {@link trainAndBenchmark}: train a fresh EvermindLM, then score it. */
+export interface TrainAndBenchmarkOptions {
+  /** BPE merges to learn for the tokenizer. Default 100. */
+  numMerges?: number;
+  /** Model channel dimension. Default 32. */
+  dModel?: number;
+  /** Number of (conv + MoE) blocks. Default 2. */
+  numLayers?: number;
+  /** MoE expert FFN hidden width. Default 48. */
+  hiddenDim?: number;
+  /** Training epochs. Default 30. */
+  epochs?: number;
+  /** AdamW learning rate. Default 0.03. */
+  lr?: number;
+  /** Deterministic seed (model init + held-out split). Default 7. */
+  seed?: number;
+  /**
+   * Fraction of sequences reserved for evaluation (never trained on). Default
+   * 0.25. A real benchmark must score held-out data, so this is enforced > 0.
+   */
+  heldOutRatio?: number;
+  /** k for top-k accuracy. Default 5. */
+  topK?: number;
+  /** Prompt used to capture a qualitative generation sample. Default "The". */
+  prompt?: string;
+}
+
+/** {@link trainAndBenchmark} result: the held-out scorecard plus training context. */
+export interface TrainAndBenchmarkResult extends BenchmarkReport {
+  /** Sequences used for training. */
+  trainSequences: number;
+  /** Held-out sequences used for evaluation. */
+  evalSequences: number;
+  /** Final-epoch mean training loss (nats). */
+  finalTrainLoss: number;
+  /** First-epoch mean training loss (nats) — pairs with final to show the drop. */
+  initialTrainLoss: number;
+  /** Learned tokenizer vocabulary size. */
+  vocabSize: number;
+  /** A short greedy generation from {@link TrainAndBenchmarkOptions.prompt}. */
+  sample: string;
+}

package/src/export/gguf.ts

@@ -0,0 +1,168 @@
+/**
+ * export/gguf.ts — export weights to a GGUF v3 container (the llama.cpp format).
+ *
+ * Emits a spec-valid GGUF file: magic + version, KV metadata (architecture, dims,
+ * expert counts…), aligned tensor-info table, then aligned tensor data. ggml
+ * stores dimensions innermost-first, so row-major shapes are reversed here.
+ *
+ * NOTE: GGUF is a *container*. llama.cpp can only RUN a file whose
+ * `general.architecture` it has a graph for; "evermind" is custom, so this file
+ * is a valid, inspectable artifact (gguf tooling reads it) but won't execute in
+ * stock llama.cpp until the architecture is upstreamed. It exists so the same
+ * weights can travel through GGUF-native tooling. For an executable export use
+ * {@link ./onnx} or {@link ./safetensors}.
+ */
+
+import type { EvermindLM } from "../lm/evermind_lm.js";
+import { archOf, namedTensors, type NamedTensor } from "./tensors.js";
+import { floatToFp16 } from "../utils/quantization.js";
+
+const GGUF_MAGIC = 0x46554747; // "GGUF" little-endian
+const GGUF_VERSION = 3;
+const ALIGNMENT = 32;
+
+// GGUF metadata value types
+const T_UINT32 = 4;
+const T_STRING = 8;
+// ggml tensor types
+const GGML_F32 = 0;
+const GGML_F16 = 1;
+
+export interface GgufOptions {
+  name?: string;
+  /** Store tensors as float16 (ggml type F16). Default false (F32). */
+  fp16?: boolean;
+}
+
+/** A growable little-endian byte buffer. */
+class ByteBuf {
+  private buf = new Uint8Array(1024);
+  private len = 0;
+  private ensure(n: number): void {
+    if (this.len + n <= this.buf.length) return;
+    let cap = this.buf.length * 2;
+    while (cap < this.len + n) cap *= 2;
+    const next = new Uint8Array(cap);
+    next.set(this.buf.subarray(0, this.len));
+    this.buf = next;
+  }
+  u32(v: number): void {
+    this.ensure(4);
+    new DataView(this.buf.buffer).setUint32(this.len, v, true);
+    this.len += 4;
+  }
+  u64(v: number): void {
+    this.ensure(8);
+    new DataView(this.buf.buffer).setBigUint64(this.len, BigInt(v), true);
+    this.len += 8;
+  }
+  raw(bytes: Uint8Array): void {
+    this.ensure(bytes.length);
+    this.buf.set(bytes, this.len);
+    this.len += bytes.length;
+  }
+  /** Pad with zeros until the length is a multiple of `align`. */
+  alignTo(align: number): void {
+    const pad = (align - (this.len % align)) % align;
+    if (pad > 0) {
+      this.ensure(pad);
+      this.len += pad;
+    }
+  }
+  string(s: string): void {
+    const bytes = new TextEncoder().encode(s);
+    this.u64(bytes.length);
+    this.raw(bytes);
+  }
+  get length(): number {
+    return this.len;
+  }
+  bytes(): Uint8Array {
+    return this.buf.subarray(0, this.len);
+  }
+}
+
+function tensorBytes(data: Float32Array, fp16: boolean): Uint8Array {
+  if (!fp16) {
+    const out = new Uint8Array(data.length * 4);
+    const dv = new DataView(out.buffer);
+    for (let i = 0; i < data.length; i++) dv.setFloat32(i * 4, data[i]!, true);
+    return out;
+  }
+  const out = new Uint8Array(data.length * 2);
+  const dv = new DataView(out.buffer);
+  for (let i = 0; i < data.length; i++) dv.setUint16(i * 2, floatToFp16(data[i]!), true);
+  return out;
+}
+
+/** Export a trained LM to GGUF bytes. */
+export function exportGguf(lm: EvermindLM, opts: GgufOptions = {}): Uint8Array {
+  const fp16 = opts.fp16 ?? false;
+  const a = archOf(lm);
+  const tensors = namedTensors(lm);
+  const ggmlType = fp16 ? GGML_F16 : GGML_F32;
+  const bytesPer = fp16 ? 2 : 4;
+
+  const kvU32: [string, number][] = [
+    ["evermind.vocab_size", a.vocabSize],
+    ["evermind.embedding_length", a.dModel],
+    ["evermind.block_count", a.numLayers],
+    ["evermind.conv_kernel", a.convKernel],
+    ["evermind.feed_forward_length", a.hiddenDim],
+    ["evermind.expert_count", a.numExperts],
+    ["evermind.expert_used_count", a.topK],
+    ["general.alignment", ALIGNMENT],
+  ];
+  const kvStr: [string, string][] = [
+    ["general.architecture", "evermind"],
+    ["general.name", opts.name ?? "Evermind"],
+  ];
+
+  // Header: magic, version, tensor_count, metadata_kv_count, KVs.
+  const head = new ByteBuf();
+  head.u32(GGUF_MAGIC);
+  head.u32(GGUF_VERSION);
+  head.u64(tensors.length);
+  head.u64(kvU32.length + kvStr.length);
+  for (const [k, v] of kvStr) {
+    head.string(k);
+    head.u32(T_STRING);
+    head.string(v);
+  }
+  for (const [k, v] of kvU32) {
+    head.string(k);
+    head.u32(T_UINT32);
+    head.u32(v);
+  }
+
+  // Tensor-info table. Offsets are relative to the start of the (aligned) tensor
+  // data section; each tensor starts at an ALIGNMENT boundary within it.
+  const dims = (t: NamedTensor): number[] => [...t.shape].reverse(); // ggml: innermost first
+  let dataOffset = 0;
+  const offsets: number[] = [];
+  for (const t of tensors) {
+    offsets.push(dataOffset);
+    const nbytes = t.data.length * bytesPer;
+    dataOffset += nbytes;
+    dataOffset += (ALIGNMENT - (dataOffset % ALIGNMENT)) % ALIGNMENT;
+  }
+  tensors.forEach((t, i) => {
+    head.string(t.name);
+    const d = dims(t);
+    head.u32(d.length);
+    for (const dim of d) head.u64(dim);
+    head.u32(ggmlType);
+    head.u64(offsets[i]!);
+  });
+
+  // Pad header to the alignment boundary, then write aligned tensor data.
+  head.alignTo(ALIGNMENT);
+  const dataStart = head.length;
+  for (let i = 0; i < tensors.length; i++) {
+    // Re-establish alignment relative to the data section start.
+    const want = dataStart + offsets[i]!;
+    while (head.length < want) head.raw(new Uint8Array(1));
+    head.raw(tensorBytes(tensors[i]!.data, fp16));
+  }
+  return head.bytes();
+}