@seanhogg/builderforce-memory-engine 2026.9.34 → 2026.10.2

package/src/ml/classical/math.ts

@@ -0,0 +1,93 @@
+/**
+ * ml/classical/math.ts — the small vector helpers every classical algorithm shares.
+ * Pure, allocation-light, deterministic.
+ */
+import { SeededRng } from "../../utils/rng.js";
+
+/** The engine's ONE sigmoid / softmax (`training/cpu_ops.ts`). */
+export { sigmoid, softmax } from "../../training/cpu_ops.js";
+
+export type Vec = ArrayLike<number>;
+
+export function dot(a: Vec, b: Vec): number {
+  const n = Math.min(a.length, b.length);
+  let s = 0;
+  for (let i = 0; i < n; i++) s += a[i]! * b[i]!;
+  return s;
+}
+
+export function norm(a: Vec): number {
+  return Math.sqrt(dot(a, a));
+}
+
+/** Cosine similarity in [-1, 1]; 0 when either vector is zero. */
+export function cosine(a: Vec, b: Vec): number {
+  const na = norm(a);
+  const nb = norm(b);
+  return na > 0 && nb > 0 ? dot(a, b) / (na * nb) : 0;
+}
+
+export function squaredDistance(a: Vec, b: Vec): number {
+  const n = Math.min(a.length, b.length);
+  let s = 0;
+  for (let i = 0; i < n; i++) {
+    const d = a[i]! - b[i]!;
+    s += d * d;
+  }
+  return s;
+}
+
+/** Median of a numeric list (copy-sorted). NaN for an empty list. */
+export function median(values: readonly number[]): number {
+  if (values.length === 0) return Number.NaN;
+  const s = [...values].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
+}
+
+/** Index of the largest value (first on ties). */
+export function argmax(values: ArrayLike<number>): number {
+  let best = 0;
+  for (let i = 1; i < values.length; i++) if (values[i]! > values[best]!) best = i;
+  return best;
+}
+
+/** Number of distinct classes implied by integer labels 0..k-1. */
+export function classCount(labels: readonly number[]): number {
+  let k = 0;
+  for (const y of labels) {
+    if (!Number.isInteger(y) || y < 0) throw new Error(`class label must be a non-negative integer, got ${y}`);
+    k = Math.max(k, y + 1);
+  }
+  return Math.max(k, 2);
+}
+
+/** Feature dimension of a non-empty sample matrix; throws on ragged rows. */
+export function featureDim(X: readonly Vec[]): number {
+  if (X.length === 0) throw new Error("no samples");
+  const d = X[0]!.length;
+  for (const x of X) if (x.length !== d) throw new Error(`ragged features: expected ${d}, got ${x.length}`);
+  return d;
+}
+
+/** Confidence of a probability vector: its top probability. */
+export function topProbability(p: readonly number[]): number {
+  return p.length ? Math.max(...p) : 0;
+}
+
+/** A deterministic [0,1) source for algorithms that sample — the engine's ONE seeded RNG. */
+export function seededUniform(seed: number): () => number {
+  const rng = new SeededRng(seed);
+  return () => rng.next();
+}
+
+/**
+ * Average path length of an unsuccessful BST search over n points — the
+ * isolation-forest normaliser c(n).
+ */
+export function averagePathLength(n: number): number {
+  if (n <= 1) return 0;
+  if (n === 2) return 1;
+  const harmonic = Math.log(n - 1) + 0.5772156649;
+  return 2 * harmonic - (2 * (n - 1)) / n;
+}

package/src/ml/classical/naive_bayes.ts

@@ -0,0 +1,84 @@
+/**
+ * ml/classical/naive_bayes.ts — Gaussian naive Bayes.
+ *
+ * Per class: a weighted prior, and an independent Gaussian per feature. Variance
+ * is smoothed by a fraction of the largest feature variance (as scikit-learn's
+ * `var_smoothing`), so a constant feature never divides by zero.
+ *
+ * A class with no training weight has prior −∞ and probability exactly 0: its
+ * Gaussian is a placeholder (mean 0, variance ≈ the smoothing floor), which would
+ * otherwise out-score every real class on an input near zero.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { classCount, featureDim, softmax, topProbability } from "./math.js";
+
+export interface NaiveBayesOptions {
+  classes?: number;
+  /** Fraction of the largest feature variance added to every variance. Default 1e-9. */
+  varSmoothing?: number;
+}
+
+export class NaiveBayesModel implements MlPredictor {
+  constructor(
+    readonly logPrior: Float64Array,
+    readonly mean: Float64Array[],
+    readonly variance: Float64Array[],
+  ) {}
+
+  /** Per-class joint log-likelihood log P(c) + Σ log N(x_i | μ, σ²); −∞ for an unseen class. */
+  jointLogLikelihood(x: ArrayLike<number>): number[] {
+    return this.mean.map((mu, c) => {
+      const v = this.variance[c]!;
+      let ll = this.logPrior[c]!;
+      if (ll === -Infinity) return ll;
+      for (let i = 0; i < mu.length; i++) {
+        const d = (x[i] ?? 0) - mu[i]!;
+        ll += -0.5 * Math.log(2 * Math.PI * v[i]!) - (d * d) / (2 * v[i]!);
+      }
+      return ll;
+    });
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const scores = Array.from(softmax(this.jointLogLikelihood(x)));
+    return { scores, confidence: topProbability(scores) };
+  }
+}
+
+export function fitNaiveBayes(samples: readonly MlSample[], opts: NaiveBayesOptions = {}): NaiveBayesModel {
+  const d = featureDim(samples.map((s) => s.x));
+  const k = opts.classes ?? classCount(samples.map((s) => s.y));
+  const wSum = new Float64Array(k);
+  const mean = Array.from({ length: k }, () => new Float64Array(d));
+  const variance = Array.from({ length: k }, () => new Float64Array(d));
+
+  for (const s of samples) {
+    const w = s.weight ?? 1;
+    wSum[s.y] = wSum[s.y]! + w;
+    for (let i = 0; i < d; i++) mean[s.y]![i] = mean[s.y]![i]! + w * s.x[i]!;
+  }
+  for (let c = 0; c < k; c++) if (wSum[c]! > 0) for (let i = 0; i < d; i++) mean[c]![i] = mean[c]![i]! / wSum[c]!;
+  for (const s of samples) {
+    const w = s.weight ?? 1;
+    for (let i = 0; i < d; i++) {
+      const diff = s.x[i]! - mean[s.y]![i]!;
+      variance[s.y]![i] = variance[s.y]![i]! + w * diff * diff;
+    }
+  }
+  let maxVar = 0;
+  for (let c = 0; c < k; c++) {
+    for (let i = 0; i < d; i++) {
+      variance[c]![i] = wSum[c]! > 0 ? variance[c]![i]! / wSum[c]! : 0;
+      maxVar = Math.max(maxVar, variance[c]![i]!);
+    }
+  }
+  const eps = (opts.varSmoothing ?? 1e-9) * Math.max(maxVar, 1e-12) + 1e-12;
+  for (let c = 0; c < k; c++) for (let i = 0; i < d; i++) variance[c]![i] = variance[c]![i]! + eps;
+
+  const total = wSum.reduce((a, b) => a + b, 0);
+  if (!(total > 0)) throw new Error("fitNaiveBayes: the samples carry no weight");
+  // An unseen class is masked out (−∞, so softmax gives it exactly 0). At least one
+  // class has weight, so softmax always has a finite maximum.
+  const logPrior = Float64Array.from(wSum, (w) => (w > 0 ? Math.log(w / total) : -Infinity));
+  return new NaiveBayesModel(logPrior, mean, variance);
+}

package/src/ml/classical/robust_z.ts

@@ -0,0 +1,74 @@
+/**
+ * ml/classical/robust_z.ts — robust (median/MAD) z-scores for anomaly detection.
+ *
+ * Per feature: z = |x − median| / (1.4826 · MAD). Median and MAD are not dragged
+ * by the very outliers being looked for, unlike mean and standard deviation. When
+ * MAD is 0 (more than half the history identical) the mean absolute deviation
+ * stands in, then two floors: a fraction of |median| (relative) and `minScale`
+ * (absolute, in the feature's own units). Without the absolute one a history that
+ * is all zeros — no tool failures, ever — gets a scale of ~1e-9, and the first
+ * small non-zero value scores astronomically.
+ *
+ * Prediction: `scores[0] = max_i z_i / threshold` — ≥ 1 is anomalous.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { featureDim, median } from "./math.js";
+
+/** MAD → standard deviation for normally-distributed data. */
+const MAD_TO_SD = 1.4826;
+/** Mean absolute deviation → standard deviation for normally-distributed data. */
+const MEANAD_TO_SD = 1.2533;
+
+export interface RobustZOptions {
+  /** z at which a feature counts as anomalous. Default 3.5 (Iglewicz & Hoaglin). */
+  threshold?: number;
+  /** Smallest scale per feature, as a fraction of |median| (plus 1e-9). Default 0.01. */
+  minScaleFraction?: number;
+  /**
+   * Smallest scale per feature in absolute feature units. Default 0 — the algorithm
+   * cannot know the units; a task on a fixed scale sets it (`run.anomaly` does).
+   */
+  minScale?: number;
+}
+
+export class RobustZModel implements MlPredictor {
+  constructor(
+    readonly center: Float64Array,
+    readonly scale: Float64Array,
+    readonly threshold: number,
+  ) {}
+
+  /** Per-feature robust z-scores (absolute). */
+  zScores(x: ArrayLike<number>): number[] {
+    return Array.from(this.center, (c, i) => Math.abs((x[i] ?? 0) - c) / this.scale[i]!);
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const score = Math.max(0, ...this.zScores(x)) / this.threshold;
+    return { scores: [score], confidence: anomalyConfidence(score) };
+  }
+}
+
+/** Confidence of an anomaly score normalised so 1 is the threshold: distance from it, capped. */
+export function anomalyConfidence(score: number): number {
+  return Math.max(0, Math.min(1, Math.abs(score - 1)));
+}
+
+export function fitRobustZ(samples: readonly MlSample[], opts: RobustZOptions = {}): RobustZModel {
+  const X = samples.map((s) => s.x);
+  const d = featureDim(X);
+  const minFrac = opts.minScaleFraction ?? 0.01;
+  const minAbs = opts.minScale ?? 0;
+  const center = new Float64Array(d);
+  const scale = new Float64Array(d);
+  for (let i = 0; i < d; i++) {
+    const col = X.map((x) => x[i]!);
+    const med = median(col);
+    const dev = col.map((v) => Math.abs(v - med));
+    let s = MAD_TO_SD * median(dev);
+    if (!(s > 0)) s = MEANAD_TO_SD * (dev.reduce((a, b) => a + b, 0) / dev.length);
+    center[i] = med;
+    scale[i] = Math.max(s, minFrac * Math.abs(med) + 1e-9, minAbs);
+  }
+  return new RobustZModel(center, scale, opts.threshold ?? 3.5);
+}

package/src/ml/dense_head.ts

@@ -0,0 +1,157 @@
+/**
+ * ml/dense_head.ts — the catalog's trainable head: linear, or one tanh hidden layer,
+ * over a feature vector (usually an experience embedding).
+ *
+ * It is a {@link TrainableHead} (so the ONE {@link HeadTrainer} fits it, on the
+ * GPU when there is one) and an {@link MlPredictor} (so the runner answers with
+ * it). Its parameters flatten to one vector — the unit that federates.
+ */
+import { gaussianArray, SeededRng } from "../utils/rng.js";
+import { softmax } from "../training/cpu_ops.js";
+import { assignParams, flattenParams, type HeadParam, type TrainableHead } from "./head_trainer.js";
+import type { MlPrediction, MlPredictor, MlSample } from "./types.js";
+
+export interface DenseHeadConfig {
+  inputDim: number;
+  /** Hidden width; 0 = a linear head. */
+  hiddenDim: number;
+  /** Classes (softmax) or 1 (mse regression). */
+  outputDim: number;
+  /** `softmax` = classification over `outputDim` classes; `mse` = scalar regression. */
+  objective: "softmax" | "mse";
+  seed?: number;
+}
+
+export class DenseHead implements TrainableHead<MlSample>, MlPredictor {
+  readonly config: Required<DenseHeadConfig>;
+  private readonly _params: HeadParam[];
+  private readonly _grads: HeadParam[];
+
+  constructor(config: DenseHeadConfig) {
+    this.config = { seed: 0x4e4d, ...config };
+    const { inputDim, hiddenDim, outputDim, objective } = this.config;
+    if (objective === "mse" && outputDim !== 1) throw new Error("DenseHead: mse objective needs outputDim 1");
+    if (objective === "softmax" && outputDim < 2) throw new Error("DenseHead: softmax objective needs outputDim ≥ 2");
+    const rng = new SeededRng(this.config.seed);
+    const next = () => rng.next();
+    const inner = hiddenDim > 0 ? hiddenDim : inputDim;
+    const shapes: [string, number, number][] = [
+      ...(hiddenDim > 0
+        ? ([
+            ["w1", hiddenDim * inputDim, 1 / Math.sqrt(inputDim)],
+            ["b1", hiddenDim, 0],
+          ] as [string, number, number][])
+        : []),
+      ["w2", outputDim * inner, 1 / Math.sqrt(inner)],
+      ["b2", outputDim, 0],
+    ];
+    this._params = shapes.map(([name, n, std]) => ({ name, numel: n, data: std > 0 ? gaussianArray(n, std, next) : new Float32Array(n) }));
+    this._grads = shapes.map(([name, n]) => ({ name, numel: n, data: new Float32Array(n) }));
+  }
+
+  private _p(name: string): Float32Array {
+    return this._params.find((p) => p.name === name)!.data;
+  }
+
+  private _g(name: string): Float32Array {
+    return this._grads.find((p) => p.name === name)!.data;
+  }
+
+  parameters(): HeadParam[] {
+    return this._params;
+  }
+
+  gradients(): HeadParam[] {
+    return this._grads;
+  }
+
+  zeroGrad(): void {
+    for (const g of this._grads) g.data.fill(0);
+  }
+
+  /** Hidden activation (or the input itself for a linear head) and the output logits/value. */
+  private _forward(x: ArrayLike<number>): { h: Float32Array; z: Float32Array } {
+    const { inputDim, hiddenDim, outputDim } = this.config;
+    let h: Float32Array;
+    if (hiddenDim > 0) {
+      const w1 = this._p("w1");
+      const b1 = this._p("b1");
+      h = new Float32Array(hiddenDim);
+      for (let j = 0; j < hiddenDim; j++) {
+        let s = b1[j]!;
+        for (let i = 0; i < inputDim; i++) s += w1[j * inputDim + i]! * (x[i] ?? 0);
+        h[j] = Math.tanh(s);
+      }
+    } else {
+      h = Float32Array.from({ length: inputDim }, (_, i) => x[i] ?? 0);
+    }
+    const w2 = this._p("w2");
+    const b2 = this._p("b2");
+    const z = new Float32Array(outputDim);
+    for (let k = 0; k < outputDim; k++) {
+      let s = b2[k]!;
+      for (let j = 0; j < h.length; j++) s += w2[k * h.length + j]! * h[j]!;
+      z[k] = s;
+    }
+    return { h, z };
+  }
+
+  /** Loss and dLoss/dz of one sample (unweighted). */
+  private _lossGrad(z: Float32Array, y: number): { loss: number; dz: Float32Array } {
+    if (this.config.objective === "mse") {
+      const d = z[0]! - y;
+      return { loss: 0.5 * d * d, dz: Float32Array.of(d) };
+    }
+    const p = softmax(z);
+    const dz = Float32Array.from(p, (v, k) => v - (k === y ? 1 : 0));
+    return { loss: -Math.log(Math.max(p[y] ?? 0, 1e-12)), dz };
+  }
+
+  loss(s: MlSample): number {
+    return (s.weight ?? 1) * this._lossGrad(this._forward(s.x).z, s.y).loss;
+  }
+
+  accumulate(s: MlSample): number {
+    const w = s.weight ?? 1;
+    const { inputDim, hiddenDim, outputDim } = this.config;
+    const { h, z } = this._forward(s.x);
+    const { loss, dz } = this._lossGrad(z, s.y);
+    const w2 = this._p("w2");
+    const gW2 = this._g("w2");
+    const gB2 = this._g("b2");
+    const dh = new Float32Array(h.length);
+    for (let k = 0; k < outputDim; k++) {
+      const g = w * dz[k]!;
+      gB2[k] = gB2[k]! + g;
+      for (let j = 0; j < h.length; j++) {
+        gW2[k * h.length + j] = gW2[k * h.length + j]! + g * h[j]!;
+        dh[j] = dh[j]! + g * w2[k * h.length + j]!;
+      }
+    }
+    if (hiddenDim > 0) {
+      const gW1 = this._g("w1");
+      const gB1 = this._g("b1");
+      for (let j = 0; j < hiddenDim; j++) {
+        const dpre = dh[j]! * (1 - h[j]! * h[j]!);
+        gB1[j] = gB1[j]! + dpre;
+        for (let i = 0; i < inputDim; i++) gW1[j * inputDim + i] = gW1[j * inputDim + i]! + dpre * (s.x[i] ?? 0);
+      }
+    }
+    return w * loss;
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const { z } = this._forward(x);
+    if (this.config.objective === "mse") return { scores: [z[0]!], confidence: 1 };
+    const scores = Array.from(softmax(z));
+    return { scores, confidence: Math.max(...scores) };
+  }
+
+  exportParams(): Float32Array {
+    return flattenParams(this._params);
+  }
+
+  importParams(params: ArrayLike<number>): void {
+    assignParams(this._params, params);
+  }
+}

package/src/ml/eval_loss.ts

@@ -0,0 +1,27 @@
+/**
+ * ml/eval_loss.ts — the ONE held-out loss for catalog models.
+ *
+ * What the trainer reports as `holdoutLoss`, what a federated merge is gated on, and
+ * what `LogisticModel.loss` returns. A leaf (types only), so a classical algorithm can
+ * use it without importing the trainer that imports the algorithms.
+ */
+import type { MlPredictor, MlSample, MlTaskKind } from "./types.js";
+
+/**
+ * Mean loss of `predictor` on `samples` for a task of `kind` — classify: weighted
+ * cross-entropy of the true class; regress: weighted ½·squared error. Null for
+ * kinds without a supervised loss, or an empty (or zero-weight) set.
+ */
+export function mlEvalLoss(kind: MlTaskKind, predictor: MlPredictor, samples: readonly MlSample[]): number | null {
+  if (samples.length === 0 || (kind !== "classify" && kind !== "regress")) return null;
+  let sum = 0;
+  let wSum = 0;
+  for (const s of samples) {
+    const w = s.weight ?? 1;
+    const p = predictor.predict(s.x);
+    const loss = kind === "classify" ? -Math.log(Math.max(p.scores[s.y] ?? 0, 1e-12)) : 0.5 * (p.scores[0]! - s.y) ** 2;
+    sum += w * loss;
+    wSum += w;
+  }
+  return wSum > 0 ? sum / wSum : null;
+}

package/src/ml/features.ts

@@ -0,0 +1,61 @@
+/**
+ * ml/features.ts — how an input becomes a feature vector.
+ *
+ * Text goes through the existing CPU embedder seam ({@link TextEmbedder}, which
+ * `EvermindTextEmbedder` implements: the person's own Evermind turns text into
+ * an L2-normalised vector with no GPU and no network). Numeric fields are
+ * appended as the task supplies them — on a FIXED scale (see {@link logScale}),
+ * never one fitted to local data, so a federated weight means the same thing on
+ * every machine.
+ */
+import type { TextEmbedder } from "../lm/text_embedder.js";
+import type { FeatureSpec } from "./types.js";
+
+export type { TextEmbedder } from "../lm/text_embedder.js";
+
+/** Feature vector of one input: `[embed(text) …, numeric …]`. */
+export async function extractFeatures<I>(spec: FeatureSpec<I>, input: I, embedder?: TextEmbedder): Promise<Float32Array> {
+  const parts: ArrayLike<number>[] = [];
+  if (spec.text) {
+    if (!embedder) throw new Error("extractFeatures: this task embeds text but no embedder was supplied");
+    parts.push(await embedder.embed(spec.text(input)));
+  }
+  if (spec.numeric) {
+    const nums = spec.numeric(input);
+    for (const v of nums) if (!Number.isFinite(v)) throw new Error(`extractFeatures: non-finite numeric feature ${v}`);
+    parts.push(nums);
+  }
+  if (parts.length === 0) throw new Error("extractFeatures: the feature spec has neither text nor numeric fields");
+  const out = new Float32Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+  }
+  return out;
+}
+
+/** Feature vectors of many inputs, in order. */
+export async function extractFeatureMatrix<I>(
+  spec: FeatureSpec<I>,
+  inputs: readonly I[],
+  embedder?: TextEmbedder,
+): Promise<Float32Array[]> {
+  const out: Float32Array[] = [];
+  for (const i of inputs) out.push(await extractFeatures(spec, i, embedder));
+  return out;
+}
+
+/**
+ * A count or size on a fixed log scale: log1p(max(v, 0)) / log1p(ref). `ref` is
+ * the value that maps to 1 (e.g. 100k tokens), so the scale is the same everywhere.
+ */
+export function logScale(v: number, ref: number): number {
+  return Math.log1p(Math.max(0, v)) / Math.log1p(Math.max(ref, 1));
+}
+
+/** A ratio clamped to [0, max] — fill fractions, success rates. */
+export function clampRatio(numerator: number, denominator: number, max = 4): number {
+  if (!(denominator > 0)) return 0;
+  return Math.max(0, Math.min(max, numerator / denominator));
+}

package/src/ml/federate.ts

@@ -0,0 +1,130 @@
+/**
+ * ml/federate.ts — trained ML heads federate like the model's own weights.
+ *
+ * A head's trained state is ONE flat f32 vector (`MlPredictor.exportParams`),
+ * stored as a CRC-trailed checkpoint so it is the same shape the delta pipeline
+ * already handles: a learner diffs its trained copy against the version it
+ * started from (`diffCheckpoints`), ships it on the existing delta wire with
+ * `target: "ml:<task>"`, and the writer folds N of them with the existing FedAvg
+ * (`mergeCheckpointDiffsGated` → `mergeCheckpointDiffs`), refusing a merge whose
+ * held-out loss regresses. No second wire, no second merge.
+ *
+ * The head's manifest entry and checkpoint format live with the artifact
+ * (`evermind/ml_head.ts`); this module only imports evermind/, never the reverse.
+ */
+import {
+  buildDeltaLearnPayload,
+  decodeDeltaPayload,
+  deltaTargetMismatch,
+  deltaUnusableReason,
+  mlHeadTarget,
+  type DeltaLearnPayload,
+} from "../evermind/delta_wire.js";
+import { mergeCheckpointDiffsGated, type GatedMergeResult, type MergeGateOptions } from "../evermind/merge.js";
+import { headCheckpoint, headParams, type EvermindMlHead } from "../evermind/ml_head.js";
+import type { EvermindModelPackage } from "../evermind/package.js";
+import { base64ToBytes, bytesToBase64 } from "../utils/base64.js";
+import { diffCheckpoints } from "../utils/delta.js";
+
+export { headCheckpoint, headParams, mlHeadUnusableReason } from "../evermind/ml_head.js";
+export type { EvermindMlHead } from "../evermind/ml_head.js";
+
+/** A manifest entry for a head's current parameters. */
+export function mlHeadEntry(
+  task: string,
+  engine: string,
+  version: number,
+  params: ArrayLike<number>,
+  shape: Record<string, number> = {},
+  evalLoss?: number,
+): EvermindMlHead {
+  return {
+    task,
+    engine,
+    version,
+    shape,
+    params: bytesToBase64(headCheckpoint(params)),
+    ...(evalLoss != null && Number.isFinite(evalLoss) ? { evalLoss } : {}),
+  };
+}
+
+/** The entry's flat parameters. */
+export function mlHeadParams(entry: EvermindMlHead): Float32Array {
+  return headParams(base64ToBytes(entry.params));
+}
+
+/** The head a package carries for `task`, if any. */
+export function packageMlHead(pkg: EvermindModelPackage, task: string): EvermindMlHead | undefined {
+  return pkg.manifest.mlHeads?.find((h) => h.task === task);
+}
+
+/** `pkg` with `entry` as its head for `entry.task` (replacing the old one). */
+export function withPackageMlHead(pkg: EvermindModelPackage, entry: EvermindMlHead): EvermindModelPackage {
+  return pkg.withMlHeads([...(pkg.manifest.mlHeads ?? []).filter((h) => h.task !== entry.task), entry]);
+}
+
+/**
+ * The delta-wire payload for a locally trained head: its new parameters diffed
+ * against the version it started from. The caller owns the size guard, as for LM deltas.
+ */
+export function buildMlHeadDelta(base: EvermindMlHead, trained: ArrayLike<number>, weight?: number, label?: string): DeltaLearnPayload {
+  const diff = diffCheckpoints(base64ToBytes(base.params), headCheckpoint(trained));
+  return buildDeltaLearnPayload(diff, base.version, weight, label ?? `ml head ${base.task}`, mlHeadTarget(base.task));
+}
+
+export interface MlHeadMergeOutcome {
+  /** The head after the round: version + 1 when accepted, the base unchanged when refused. */
+  head: EvermindMlHead;
+  merge: GatedMergeResult;
+  /** Contributions left out of the batch, by index, with why. */
+  rejected: { index: number; reason: string }[];
+}
+
+/**
+ * One federated round for a head: validate each contribution ON ITS OWN (wrong
+ * target, stale base or a malformed diff costs only itself), FedAvg the rest, and
+ * keep the result only if `score` (held-out loss of a parameter vector, lower is
+ * better) does not regress.
+ *
+ * Fails CLOSED: `requireEval` defaults to true here, so a round `score` cannot judge
+ * (null — e.g. `mlEvalLoss` for an anomaly/cluster head or an empty holdout — or a
+ * non-finite loss) is refused. A caller that federates an unscorable head on purpose
+ * passes `{ requireEval: false }` explicitly.
+ */
+export function mergeMlHeadDeltas(
+  base: EvermindMlHead,
+  payloads: readonly DeltaLearnPayload[],
+  score: (params: Float32Array) => number | null,
+  opts: MergeGateOptions = {},
+): MlHeadMergeOutcome {
+  const baseCp = base64ToBytes(base.params);
+  const target = mlHeadTarget(base.task);
+  const diffs: ArrayBuffer[] = [];
+  const weights: number[] = [];
+  const rejected: { index: number; reason: string }[] = [];
+  payloads.forEach((p, index) => {
+    const wrongTarget = deltaTargetMismatch(p.target, target);
+    if (wrongTarget) return void rejected.push({ index, reason: wrongTarget });
+    if (p.baseVersion !== base.version) return void rejected.push({ index, reason: `stale base version ${p.baseVersion} (head is ${base.version})` });
+    let diff: ArrayBuffer;
+    try {
+      diff = decodeDeltaPayload(p);
+    } catch (error) {
+      return void rejected.push({ index, reason: `diff is not base64: ${error instanceof Error ? error.message : String(error)}` });
+    }
+    const why = deltaUnusableReason(diff, baseCp);
+    if (why) return void rejected.push({ index, reason: why });
+    diffs.push(diff);
+    weights.push(p.weight ?? 1);
+  });
+
+  const merge = mergeCheckpointDiffsGated(baseCp, diffs, weights, (cp) => score(headParams(cp)), { ...opts, requireEval: opts.requireEval ?? true });
+  if (!merge.accepted) return { head: base, merge, rejected };
+  const head: EvermindMlHead = {
+    ...base,
+    version: base.version + 1,
+    params: bytesToBase64(merge.checkpoint),
+    ...(merge.newLoss != null ? { evalLoss: merge.newLoss } : {}),
+  };
+  return { head, merge, rejected };
+}