@seanhogg/builderforce-memory-engine 2026.7.14 → 2026.9.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory-engine",
-  "version": "2026.7.14",
+  "version": "2026.9.28",
   "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",
@@ -76,6 +76,7 @@
           "tsconfig": {
             "module": "ES2022",
             "moduleResolution": "bundler",
+            "rootDir": ".",
             "strict": true,
             "esModuleInterop": true,
             "skipLibCheck": true,
@@ -94,6 +95,7 @@
   "scripts": {
     "build": "tsc",
     "serve": "node serve.js",
+    "bench:adapt": "npm run build && node scripts/bench-adaptation.mjs",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
     "lint": "eslint src/ tests/",
     "typecheck:native": "tsgo --noEmit"

package/src/bench/adaptation.ts

@@ -0,0 +1,180 @@
+/**
+ * bench/adaptation.ts — what does ON-PREM ADAPTATION COST?
+ *
+ * The rest of the harness measures how GOOD a model is. This measures how much
+ * one write-through adaptation COSTS, which is the number an on-prem operator
+ * needs before turning learning on: every run the host adapts on is CPU it is not
+ * spending on the agent.
+ *
+ * It became measurable only once the gradient path was real. Before that a "fit"
+ * was a forward pass plus an inert optimiser step, so any timing was a timing of
+ * the wrong thing.
+ *
+ * The three knobs are the ones the host actually exposes
+ * (`agent-runtime/src/infra/project-evermind-delta.ts`, and the cloud
+ * coordinator's identical constants):
+ *
+ *   • WINDOW  — `ADAPT_WINDOW_TOKENS = 64`, the length of each training sequence
+ *               the run text is chunked into;
+ *   • EPOCHS  — `new EvermindLMTrainer(lm, { epochs: 1 })`, passes per contribution;
+ *   • SKIP    — `MIN_TEXT_CHARS = 20`, the floor below which a contribution is
+ *               dropped before any work happens; expressed here as how OFTEN the
+ *               floor fires.
+ *
+ * Two quantities are reported, and the difference matters. `positionsEvaluated`
+ * comes from the model's own counter: exact, integer, hardware-independent — the
+ * thing a curve should be asserted on. `elapsedMs` is what those positions cost on
+ * THIS machine, which is what an operator budgets with and what no assertion
+ * should depend on.
+ */
+
+import { EvermindLM, EvermindLMTrainer } from "../lm/evermind_lm.js";
+import { BPETokenizer } from "../tokenizer/bpe.js";
+import { defaultNow } from "./harness.js";
+import type { AdaptationCostOptions, AdaptationCostPoint, AdaptationCostReport } from "./types.js";
+
+/**
+ * Chunk token ids into fixed-length training windows, dropping any tail too short
+ * to have a next-token target.
+ *
+ * A byte-for-byte mirror of the host's own `windows()` helper, so a benchmarked
+ * fit sees exactly the batches a production adaptation would.
+ */
+export function tokenWindows(ids: number[], size: number): number[][] {
+  const out: number[][] = [];
+  const step = Math.max(1, Math.floor(size));
+  for (let i = 0; i + 1 < ids.length; i += step) {
+    const seq = ids.slice(i, i + step);
+    if (seq.length >= 2) out.push(seq);
+  }
+  return out;
+}
+
+/**
+ * How many of `requests` actually adapt at a given skip rate.
+ *
+ * Deterministic rather than sampled: a benchmark whose cost curve moved with an
+ * RNG would be measuring the RNG.
+ */
+export function adaptationsAfterSkip(requests: number, skipRate: number): number {
+  const rate = Math.min(1, Math.max(0, skipRate));
+  return Math.round(requests * (1 - rate));
+}
+
+/** Default corpus — prose of roughly the shape a run-text contribution has. */
+const DEFAULT_TEXT = [
+  "The planning loop retrieves context before generating a response.",
+  "Agents recall facts from the memory layer and act on them.",
+  "Deployment runs on Cloudflare Workers and Durable Objects.",
+  "Tools are gated by a capability registry and a policy pack.",
+  "The coordinator merges weight deltas from every contributing host.",
+  "A ticket moves through triage, execution, review and merge.",
+  "Recall is ranked by embedding cosine fused with lexical scoring.",
+  "The trainer adapts a private copy of the base checkpoint locally.",
+].join(" ");
+
+/** Total trainable scalars — what one optimiser step touches. */
+function paramCountOf(model: EvermindLM): number {
+  let n = 0;
+  for (const p of model.parameters()) n += p.data.length;
+  return n;
+}
+
+/**
+ * Measure adaptation cost across a grid of (window, epochs, skip rate).
+ *
+ * Each grid point starts from a FRESH model, so the points are independent
+ * measurements rather than a single model drifting through the grid (a diverged
+ * checkpoint would otherwise make later points look different for reasons that
+ * have nothing to do with cost).
+ */
+export function benchmarkAdaptationCost(opts: AdaptationCostOptions = {}): AdaptationCostReport {
+  const text = opts.text ?? DEFAULT_TEXT;
+  const windowTokens = opts.windowTokens ?? [32, 64, 128];
+  const epochsGrid = opts.epochs ?? [1, 2, 4];
+  const skipRates = opts.skipRates ?? [0, 0.5];
+  const requests = Math.max(1, opts.requests ?? 4);
+  const dModel = opts.dModel ?? 32;
+  const numLayers = opts.numLayers ?? 2;
+  const hiddenDim = opts.hiddenDim ?? 48;
+  const seed = opts.seed ?? 7;
+  const lr = opts.lr ?? 0.01;
+  const now = opts.now ?? defaultNow;
+
+  const tok = new BPETokenizer();
+  tok.train(text, { numMerges: opts.numMerges ?? 120 });
+  const ids = tok.encode(text);
+
+  const newModel = (): EvermindLM =>
+    new EvermindLM({ vocabSize: tok.vocabSize, dModel, numLayers, hiddenDim, seed });
+
+  const points: AdaptationCostPoint[] = [];
+  for (const w of windowTokens) {
+    const windows = tokenWindows(ids, w);
+    for (const epochs of epochsGrid) {
+      for (const skipRate of skipRates) {
+        const adapted = adaptationsAfterSkip(requests, skipRate);
+        const model = newModel();
+        model.resetStats();
+
+        const t0 = now();
+        for (let r = 0; r < adapted; r++) {
+          // One contribution = one fit over the run text's windows, exactly as the
+          // host does. accumSteps pinned to 1 so `optimizerSteps` is exact.
+          new EvermindLMTrainer(model, { lr, epochs, accumSteps: 1 }).fit(windows);
+        }
+        const elapsedMs = now() - t0;
+
+        const positionsEvaluated = model.positionsEvaluated;
+        const sequences = windows.length * adapted;
+        points.push({
+          windowTokens: w,
+          epochs,
+          skipRate,
+          requests,
+          adapted,
+          sequences,
+          optimizerSteps: sequences * epochs,
+          positionsEvaluated,
+          elapsedMs,
+          msPerKPosition: positionsEvaluated > 0 ? (elapsedMs / positionsEvaluated) * 1000 : 0,
+          msPerAdaptation: adapted > 0 ? elapsedMs / adapted : 0,
+        });
+      }
+    }
+  }
+
+  return {
+    points,
+    textTokens: ids.length,
+    vocabSize: tok.vocabSize,
+    dModel,
+    numLayers,
+    hiddenDim,
+    paramCount: paramCountOf(newModel()),
+  };
+}
+
+/** Render an {@link AdaptationCostReport} as a fixed-width table. */
+export function formatAdaptationCostReport(report: AdaptationCostReport): string {
+  const head =
+    `Evermind adaptation cost — dModel=${report.dModel} layers=${report.numLayers} ` +
+    `hidden=${report.hiddenDim} params=${report.paramCount.toLocaleString()} ` +
+    `vocab=${report.vocabSize} textTokens=${report.textTokens}`;
+  const cols = ["window", "epochs", "skip", "adapts", "seqs", "steps", "positions", "ms", "ms/adapt", "ms/1k pos"];
+  const rows = report.points.map((p) => [
+    String(p.windowTokens),
+    String(p.epochs),
+    p.skipRate.toFixed(2),
+    `${p.adapted}/${p.requests}`,
+    String(p.sequences),
+    String(p.optimizerSteps),
+    String(p.positionsEvaluated),
+    p.elapsedMs.toFixed(1),
+    p.msPerAdaptation.toFixed(1),
+    p.msPerKPosition.toFixed(3),
+  ]);
+  const widths = cols.map((c, i) => Math.max(c.length, ...rows.map((r) => r[i]!.length)));
+  const line = (cells: string[]): string => cells.map((c, i) => c.padStart(widths[i]!)).join("  ");
+  return [head, "", line(cols), line(widths.map((w) => "-".repeat(w))), ...rows.map(line)].join("\n");
+}

package/src/bench/harness.ts

@@ -23,7 +23,7 @@ import type {
 } from "./types.js";
 
 /** A monotonic clock, preferring `performance.now()` when present. */
-function defaultNow(): number {
+export function defaultNow(): number {
   const g = globalThis as { performance?: { now(): number } };
   return typeof g.performance?.now === "function" ? g.performance.now() : Date.now();
 }

package/src/bench/index.ts

@@ -2,8 +2,9 @@
  * 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.
+ * next-token accuracy, throughput), A/Bs two models, offers a one-call
+ * train-and-score path the Studio drives in the browser, and measures what one
+ * on-prem ADAPTATION costs across the host's own window/epoch/skip knobs.
  */
 
 export {
@@ -16,6 +17,13 @@ export {
   trainAndBenchmark,
 } from "./harness.js";
 
+export {
+  benchmarkAdaptationCost,
+  formatAdaptationCostReport,
+  tokenWindows,
+  adaptationsAfterSkip,
+} from "./adaptation.js";
+
 export {
   argmax,
   topKIndices,
@@ -34,4 +42,7 @@ export type {
   ComparisonReport,
   TrainAndBenchmarkOptions,
   TrainAndBenchmarkResult,
+  AdaptationCostOptions,
+  AdaptationCostPoint,
+  AdaptationCostReport,
 } from "./types.js";

package/src/bench/types.ts

@@ -119,3 +119,96 @@ export interface TrainAndBenchmarkResult extends BenchmarkReport {
   /** A short greedy generation from {@link TrainAndBenchmarkOptions.prompt}. */
   sample: string;
 }
+
+// ── Adaptation cost ───────────────────────────────────────────────────────────
+
+/**
+ * Knobs for {@link benchmarkAdaptationCost} — the measured COST of on-prem
+ * adaptation, as opposed to the quality metrics above.
+ *
+ * The defaults bracket what the on-prem host actually runs today
+ * (`agent-runtime/src/infra/project-evermind-delta.ts`, mirrored by the cloud
+ * coordinator): 64-token training windows, ONE epoch per contribution, over at
+ * most 4000 characters of run text, with contributions under 20 characters
+ * skipped before any work happens.
+ */
+export interface AdaptationCostOptions {
+  /** Corpus the tokenizer is learned from and the adaptation trains on. */
+  text?: string;
+  /** Tokens per training window. Default `[32, 64, 128]` (production: 64). */
+  windowTokens?: number[];
+  /** Epochs per adaptation. Default `[1, 2, 4]` (production: 1). */
+  epochs?: number[];
+  /**
+   * Fraction of incoming contributions skipped before any work, 0..1. The
+   * on-prem skip is a floor on contribution length (`MIN_TEXT_CHARS`), so this is
+   * that floor expressed as how often it fires. Default `[0, 0.5]`.
+   */
+  skipRates?: number[];
+  /** Adaptation requests issued per grid point. Default 4. */
+  requests?: number;
+  /** BPE merges learned for the tokenizer. Default 120. */
+  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;
+  /** AdamW learning rate for the adaptation fits. Default 0.01. */
+  lr?: number;
+  /** Deterministic seed for model init. Default 7. */
+  seed?: number;
+  /** Monotonic clock in ms, injectable for deterministic tests. */
+  now?: () => number;
+}
+
+/** Measured cost at one (window, epochs, skipRate) point of the grid. */
+export interface AdaptationCostPoint {
+  /** Tokens per training window. */
+  windowTokens: number;
+  /** Epochs run per adaptation. */
+  epochs: number;
+  /** Fraction of requests skipped before any work. */
+  skipRate: number;
+  /** Adaptation requests issued at this point. */
+  requests: number;
+  /** Requests that actually ran a fit (the rest were skipped). */
+  adapted: number;
+  /** Training windows fitted, summed over the adaptations that ran. */
+  sequences: number;
+  /**
+   * AdamW steps issued: one per window per epoch (the trainer's default, with
+   * gradient accumulation pinned to 1 so the count is exact).
+   */
+  optimizerSteps: number;
+  /**
+   * Block positions pushed through the model, read from
+   * `EvermindLM.positionsEvaluated`. Hardware-independent and exact — this is the
+   * quantity a cost curve should be asserted on; wall time is what it costs HERE.
+   */
+  positionsEvaluated: number;
+  /** Wall-clock milliseconds spent inside the fits. */
+  elapsedMs: number;
+  /** Milliseconds per 1000 evaluated positions — the machine's unit cost. */
+  msPerKPosition: number;
+  /** Wall-clock milliseconds per adaptation that actually ran (0 when all skipped). */
+  msPerAdaptation: number;
+}
+
+/** The adaptation-cost scorecard: one point per (window, epochs, skipRate). */
+export interface AdaptationCostReport {
+  points: AdaptationCostPoint[];
+  /** Tokens the source text produced (the adaptation's input size). */
+  textTokens: number;
+  /** Learned tokenizer vocabulary size. */
+  vocabSize: number;
+  /** Model channel dimension the grid was measured on. */
+  dModel: number;
+  /** Number of blocks the grid was measured on. */
+  numLayers: number;
+  /** MoE expert hidden width the grid was measured on. */
+  hiddenDim: number;
+  /** Trainable scalar parameters — what one optimiser step touches. */
+  paramCount: number;
+}

package/src/evermind/adapt.ts

@@ -0,0 +1,61 @@
+/**
+ * evermind/adapt.ts — ONE adaptation recipe: fit a private copy of a model version
+ * on some text, then diff it against that version.
+ *
+ * Every learner that contributes to a shared Evermind (an on-prem host pushing a
+ * delta, or the single writer fitting queued text itself) must run the SAME recipe,
+ * so a locally-produced delta is the same size of update the writer would have
+ * produced from the same text. That recipe lives here and nowhere else.
+ */
+import type { EvermindModelPackage } from "./package.js";
+import { EvermindLMTrainer } from "../lm/evermind_lm.js";
+import { diffCheckpoints } from "../utils/delta.js";
+import { tokenWindows } from "../bench/adaptation.js";
+
+/** Chars of text fed to one adaptation pass. */
+export const EVERMIND_ADAPT_MAX_CHARS = 4000;
+/** Token window length of the adaptation training sequences. */
+export const EVERMIND_ADAPT_WINDOW_TOKENS = 64;
+
+/** The tokenizer surface adaptation needs (the engine's `BPETokenizer` satisfies it). */
+export interface AdaptTokenizer {
+  encode(text: string): number[];
+}
+
+/** The outcome of one adaptation. */
+export interface AdaptResult {
+  /** Sparse serialized RowDelta of adapted vs base. */
+  diff: ArrayBuffer;
+  /** The trainer's final-epoch mean loss. */
+  loss: number;
+  /** How many training windows the text produced. */
+  sequences: number;
+}
+
+export interface AdaptOptions {
+  maxChars?: number;
+  windowTokens?: number;
+  epochs?: number;
+}
+
+/**
+ * Adapt a freshly-loaded copy of `pkg` on `text` and return the diff, or null when
+ * the text yields no trainable window. The package's own checkpoint is never
+ * mutated, so the diff is exactly "this text's update", never an accumulation.
+ * Throws when `pkg` is not an `evermind-lm` (as `loadLM` does).
+ */
+export function adaptAndDiff(
+  pkg: EvermindModelPackage,
+  tokenizer: AdaptTokenizer,
+  text: string,
+  opts: AdaptOptions = {},
+): AdaptResult | null {
+  const maxChars = opts.maxChars ?? EVERMIND_ADAPT_MAX_CHARS;
+  const windowTokens = opts.windowTokens ?? EVERMIND_ADAPT_WINDOW_TOKENS;
+  const seqs = tokenWindows(tokenizer.encode(text.slice(0, maxChars)), windowTokens);
+  if (seqs.length === 0) return null;
+  const lm = pkg.loadLM();
+  const history = new EvermindLMTrainer(lm, { epochs: opts.epochs ?? 1 }).fit(seqs);
+  const loss = history.length > 0 ? history[history.length - 1]! : 0;
+  return { diff: diffCheckpoints(pkg.checkpoint, lm.exportWeights()), loss, sequences: seqs.length };
+}

package/src/evermind/delta_wire.ts

@@ -0,0 +1,114 @@
+/**
+ * evermind/delta_wire.ts — the wire contract of a pre-diffed weight-delta contribution.
+ *
+ * A learner with CPU to spare adapts a private copy of a model version, diffs it
+ * against that version (`diffCheckpoints`) and ships only the sparse diff; the single
+ * writer then merges it (`mergeCheckpointDiffs`) instead of running the fit.
+ * Everything the PRODUCER and the WRITER must agree on lives here, once:
+ *   - the payload shape (`diff` base64 + integer `baseVersion`, optional weight/label);
+ *   - the size cap, so a producer can fall back before it is refused;
+ *   - the structural check a delta must pass before it may join a merge batch.
+ *
+ * That last one is load-bearing: `mergeCheckpointDiffs` throws on a malformed diff,
+ * and one throw drops the whole batch. A single bad push must cost only itself.
+ */
+import { deserializeRowDelta } from "../utils/delta.js";
+import { verifyCrcTrailer } from "../utils/crc32.js";
+import { base64ToBytes, bytesToBase64 } from "../utils/base64.js";
+
+/** Max accepted base64 delta, in characters (~8 MiB). */
+export const MAX_DELTA_B64_CHARS = 8 * 1024 * 1024;
+
+/** Chars of provenance label kept — a diff carries no text, so the label is its only description. */
+export const DELTA_LABEL_MAX_CHARS = 800;
+
+/** Standard base64 alphabet with optional padding. */
+const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+/** A validated delta contribution — the exact body a producer sends. */
+export interface DeltaLearnPayload {
+  /** base64 serialized RowDelta (`diffCheckpoints(base, adapted)`). */
+  diff: string;
+  /** The model version the delta was diffed against. */
+  baseVersion: number;
+  /** FedAvg sample weight (> 0). Absent means the writer's default (1). */
+  weight?: number;
+  /** Provenance for the merged row (e.g. the run's task). */
+  label?: string;
+}
+
+/** Why a body was refused: `invalid` (malformed) or `too-large` (over {@link MAX_DELTA_B64_CHARS}). */
+export type DeltaParseResult =
+  | { ok: true; payload: DeltaLearnPayload }
+  | { ok: false; reason: "invalid" | "too-large"; error: string };
+
+/**
+ * Parse + validate a delta body. Pure — a front door calls it to refuse a bad body
+ * early, and the single writer calls it again because it trusts no caller.
+ */
+export function parseDeltaLearnPayload(raw: unknown): DeltaParseResult {
+  const body = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+  const diff = typeof body.diff === "string" ? body.diff : "";
+  const baseVersion = typeof body.baseVersion === "number" ? body.baseVersion : Number.NaN;
+  if (!diff || !Number.isInteger(baseVersion)) {
+    return {
+      ok: false,
+      reason: "invalid",
+      error: "diff (base64) and baseVersion (integer head version the delta was taken against) are required",
+    };
+  }
+  if (diff.length > MAX_DELTA_B64_CHARS) {
+    return { ok: false, reason: "too-large", error: `delta too large (max ${MAX_DELTA_B64_CHARS} base64 characters)` };
+  }
+  if (diff.length % 4 !== 0 || !BASE64_RE.test(diff)) {
+    return { ok: false, reason: "invalid", error: "diff must be standard base64" };
+  }
+  const weight = typeof body.weight === "number" && Number.isFinite(body.weight) && body.weight > 0 ? body.weight : undefined;
+  const label = typeof body.label === "string" && body.label.trim() ? body.label.trim().slice(0, DELTA_LABEL_MAX_CHARS) : undefined;
+  return {
+    ok: true,
+    payload: { diff, baseVersion, ...(weight !== undefined ? { weight } : {}), ...(label ? { label } : {}) },
+  };
+}
+
+/**
+ * Build the payload for one computed diff. The caller owns the size guard (compare
+ * `payload.diff.length` with {@link MAX_DELTA_B64_CHARS}) so it can choose a fallback.
+ */
+export function buildDeltaLearnPayload(diff: ArrayBuffer, baseVersion: number, weight?: number, label?: string): DeltaLearnPayload {
+  const trimmed = (label ?? "").trim();
+  return {
+    diff: bytesToBase64(diff),
+    baseVersion,
+    ...(typeof weight === "number" && Number.isFinite(weight) && weight > 0 ? { weight } : {}),
+    ...(trimmed ? { label: trimmed.slice(0, DELTA_LABEL_MAX_CHARS) } : {}),
+  };
+}
+
+/** Decode a payload's base64 `diff` to the serialized RowDelta bytes. Throws on malformed base64. */
+export function decodeDeltaPayload(payload: Pick<DeltaLearnPayload, "diff">): ArrayBuffer {
+  return base64ToBytes(payload.diff);
+}
+
+/**
+ * Structural check of ONE delta against the base it claims to diff: it must
+ * deserialize, be element-granular, index only elements the base has, and carry
+ * finite values. Returns why it is unusable, or null when it can join a merge.
+ */
+export function deltaUnusableReason(delta: ArrayBuffer, baseCheckpoint: ArrayBuffer): string | null {
+  try {
+    const rd = deserializeRowDelta(delta);
+    if (rd.rowSize !== 1) return `expected an element-granular delta (rowSize 1), got ${rd.rowSize}`;
+    const elements = verifyCrcTrailer(baseCheckpoint).body.byteLength / 4;
+    for (let i = 0; i < rd.rows.length; i++) {
+      const idx = rd.rows[i]!;
+      if (!Number.isInteger(idx) || idx < 0 || idx >= elements) {
+        return `row index ${idx} is outside the base checkpoint (${elements} elements)`;
+      }
+      if (!Number.isFinite(rd.data[i]!)) return `non-finite value at row ${idx}`;
+    }
+    return null;
+  } catch (error) {
+    return `not a serialized RowDelta: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}

package/src/evermind/eval.ts

@@ -0,0 +1,62 @@
+/**
+ * evermind/eval.ts — the pre/post-merge regression check.
+ *
+ * Each merge produces a NEW version from the PREVIOUS one. To tell whether it helped
+ * or quietly regressed (catastrophic forgetting), both models are scored on a small
+ * held-out set of previously-learned examples and their mean next-token loss compared.
+ *
+ * Forward-only: the loss is the same mean cross-entropy the trainer reports, computed
+ * from the logits alone, so scoring never pays for a backward pass or touches grads.
+ */
+import type { LogitsModel } from "../bench/types.js";
+import { crossEntropyLoss } from "../training/autograd.js";
+
+/** One held-out example: the learned text, optionally with the task prompt it answered. */
+export interface EvalExample {
+  prompt?: string;
+  text: string;
+}
+
+/** Max tokens scored per example — bounds the forward cost of eval. */
+export const EVAL_MAX_TOKENS = 128;
+
+/** The tokenizer surface eval needs (the engine's `BPETokenizer` satisfies it). */
+export interface EvalTokenizer {
+  encode(text: string): number[];
+}
+
+/** Mean next-token cross-entropy over one token sequence, or null when it has no target. */
+export function sequenceLoss(model: LogitsModel, ids: number[]): number | null {
+  if (ids.length < 2) return null;
+  const { logits } = model.forward(ids);
+  const n = Math.min(logits.length, ids.length) - 1;
+  if (n < 1) return null;
+  let sum = 0;
+  for (let t = 0; t < n; t++) sum += crossEntropyLoss(logits[t]!, ids[t + 1]!);
+  const loss = sum / n;
+  return Number.isFinite(loss) && loss >= 0 ? loss : null;
+}
+
+/**
+ * Mean loss of `model` across `examples` (unscorable ones skipped), each example
+ * weighted equally. Null when nothing was scorable, so a caller can decline to
+ * record a meaningless eval point.
+ */
+export function meanEvalLoss(
+  model: LogitsModel,
+  tokenizer: EvalTokenizer,
+  examples: readonly EvalExample[],
+  maxTokens: number = EVAL_MAX_TOKENS,
+): number | null {
+  let sum = 0;
+  let n = 0;
+  for (const ex of examples) {
+    const text = (ex.prompt ? `${ex.prompt}\n` : "") + ex.text;
+    const loss = sequenceLoss(model, tokenizer.encode(text).slice(0, maxTokens));
+    if (loss != null) {
+      sum += loss;
+      n++;
+    }
+  }
+  return n > 0 ? sum / n : null;
+}

package/src/evermind/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Evermind — the engine half of the Evermind module: the portable `.evermind`
+ * artifact plus the learning pipeline every learner shares (adapt, diff wire
+ * contract, FedAvg merge, pre/post-merge eval).
+ */
+export { EvermindModelPackage } from "./package.js";
+export type {
+  EvermindModelManifest,
+  EvermindModelCard,
+  EvermindModelType,
+  EvermindModality,
+  PackageMeta,
+  ValidationResult,
+} from "./package.js";
+
+export { adaptAndDiff, EVERMIND_ADAPT_MAX_CHARS } from "./adapt.js";
+export type { AdaptResult, AdaptOptions, AdaptTokenizer } from "./adapt.js";
+
+export {
+  parseDeltaLearnPayload,
+  buildDeltaLearnPayload,
+  decodeDeltaPayload,
+  deltaUnusableReason,
+  MAX_DELTA_B64_CHARS,
+} from "./delta_wire.js";
+export type { DeltaLearnPayload, DeltaParseResult } from "./delta_wire.js";
+
+export { mergeCheckpointDiffs } from "./merge.js";
+export type { MergeResult } from "./merge.js";
+
+export { meanEvalLoss } from "./eval.js";
+export type { EvalExample, EvalTokenizer } from "./eval.js";