@seanhogg/builderforce-memory-engine 2026.9.34 → 2026.10.2

package/src/ml/classical/index.ts

@@ -0,0 +1,82 @@
+/**
+ * ml/classical — pure-TypeScript algorithms, one file each, and the ONE dispatch
+ * from a {@link ClassicalAlgorithm} name to its fit.
+ */
+import type { ClassicalAlgorithm, MlPredictor, MlSample } from "../types.js";
+import { fitKnn, type KnnOptions } from "./knn.js";
+import { fitNaiveBayes, type NaiveBayesOptions } from "./naive_bayes.js";
+import { fitLogistic, type LogisticOptions } from "./logistic.js";
+import { fitLinear, type LinearOptions } from "./linear.js";
+import { fitKMeans, type KMeansOptions } from "./kmeans.js";
+import { fitRobustZ, type RobustZOptions } from "./robust_z.js";
+import { fitEwma, type EwmaOptions } from "./ewma.js";
+import { fitAnomalyComposite, type AnomalyCompositeOptions } from "./anomaly_composite.js";
+import { fitIsolationForest, type IsolationForestOptions } from "./isolation_forest.js";
+import { fitGbm, type GbmOptions } from "./gbm.js";
+
+export { KnnModel, fitKnn } from "./knn.js";
+export type { KnnOptions, KnnMetric, Neighbour } from "./knn.js";
+export { NaiveBayesModel, fitNaiveBayes } from "./naive_bayes.js";
+export type { NaiveBayesOptions } from "./naive_bayes.js";
+export { LogisticModel, fitLogistic } from "./logistic.js";
+export type { LogisticOptions } from "./logistic.js";
+export { LinearModel, fitLinear, solveLinearSystem } from "./linear.js";
+export type { LinearOptions } from "./linear.js";
+export { KMeansModel, fitKMeans } from "./kmeans.js";
+export type { KMeansOptions } from "./kmeans.js";
+export { RobustZModel, fitRobustZ, anomalyConfidence } from "./robust_z.js";
+export type { RobustZOptions } from "./robust_z.js";
+export { EwmaModel, fitEwma } from "./ewma.js";
+export type { EwmaOptions } from "./ewma.js";
+export { AnomalyCompositeModel, fitAnomalyComposite } from "./anomaly_composite.js";
+export type { AnomalyCompositeOptions } from "./anomaly_composite.js";
+export { IsolationForestModel, fitIsolationForest } from "./isolation_forest.js";
+export type { IsolationForestOptions } from "./isolation_forest.js";
+export { GbmModel, fitGbm } from "./gbm.js";
+export type { GbmOptions, GbmObjective } from "./gbm.js";
+export { cosine, dot } from "./math.js";
+
+/** Per-algorithm options, keyed by algorithm name. */
+export interface ClassicalOptions {
+  knn?: KnnOptions;
+  "naive-bayes"?: NaiveBayesOptions;
+  logistic?: LogisticOptions;
+  linear?: LinearOptions;
+  kmeans?: KMeansOptions;
+  "robust-z"?: RobustZOptions;
+  ewma?: EwmaOptions;
+  "anomaly-composite"?: AnomalyCompositeOptions;
+  "isolation-forest"?: IsolationForestOptions;
+  "gbm-small"?: GbmOptions;
+}
+
+/** Fit `algorithm` on `samples`. Unsupervised algorithms ignore `y`. */
+export function fitClassical(
+  algorithm: ClassicalAlgorithm,
+  samples: readonly MlSample[],
+  opts: ClassicalOptions = {},
+): MlPredictor {
+  if (samples.length === 0) throw new Error(`fitClassical(${algorithm}): no samples`);
+  switch (algorithm) {
+    case "knn":
+      return fitKnn(samples, opts.knn);
+    case "naive-bayes":
+      return fitNaiveBayes(samples, opts["naive-bayes"]);
+    case "logistic":
+      return fitLogistic(samples, opts.logistic);
+    case "linear":
+      return fitLinear(samples, opts.linear);
+    case "kmeans":
+      return fitKMeans(samples, opts.kmeans);
+    case "robust-z":
+      return fitRobustZ(samples, opts["robust-z"]);
+    case "ewma":
+      return fitEwma(samples, opts.ewma);
+    case "anomaly-composite":
+      return fitAnomalyComposite(samples, opts["anomaly-composite"]);
+    case "isolation-forest":
+      return fitIsolationForest(samples, opts["isolation-forest"]);
+    case "gbm-small":
+      return fitGbm(samples, opts["gbm-small"]);
+  }
+}

package/src/ml/classical/isolation_forest.ts

@@ -0,0 +1,88 @@
+/**
+ * ml/classical/isolation_forest.ts — Isolation Forest (Liu, Ting & Zhou 2008).
+ *
+ * Anomalies are few and different, so random axis-aligned splits isolate them in
+ * fewer steps. Score s(x) = 2^(−E[h(x)] / c(ψ)): near 1 = anomalous, ≤ 0.5 =
+ * normal. Prediction: `scores[0] = s / threshold` — ≥ 1 is anomalous.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { averagePathLength, featureDim, seededUniform, type Vec } from "./math.js";
+import { anomalyConfidence } from "./robust_z.js";
+
+export interface IsolationForestOptions {
+  trees?: number;
+  /** Subsample size ψ per tree. Default min(256, n). */
+  sampleSize?: number;
+  /** Raw score at which a point is anomalous. Default 0.6. */
+  threshold?: number;
+  seed?: number;
+}
+
+type ITree = { size: number } | { feature: number; split: number; left: ITree; right: ITree };
+
+function buildTree(X: Vec[], depth: number, limit: number, rnd: () => number): ITree {
+  if (depth >= limit || X.length <= 1) return { size: X.length };
+  const d = X[0]!.length;
+  // Only features that still vary can split; none left = an isolated leaf.
+  const varying: { f: number; lo: number; hi: number }[] = [];
+  for (let f = 0; f < d; f++) {
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (const x of X) {
+      lo = Math.min(lo, x[f]!);
+      hi = Math.max(hi, x[f]!);
+    }
+    if (hi > lo) varying.push({ f, lo, hi });
+  }
+  if (varying.length === 0) return { size: X.length };
+  const { f, lo, hi } = varying[Math.floor(rnd() * varying.length)]!;
+  const split = lo + rnd() * (hi - lo);
+  const left = X.filter((x) => x[f]! < split);
+  const right = X.filter((x) => x[f]! >= split);
+  return { feature: f, split, left: buildTree(left, depth + 1, limit, rnd), right: buildTree(right, depth + 1, limit, rnd) };
+}
+
+function pathLength(tree: ITree, x: Vec, depth = 0): number {
+  if ("size" in tree) return depth + averagePathLength(tree.size);
+  return pathLength(x[tree.feature]! < tree.split ? tree.left : tree.right, x, depth + 1);
+}
+
+export class IsolationForestModel implements MlPredictor {
+  constructor(
+    readonly trees: readonly ITree[],
+    readonly sampleSize: number,
+    readonly threshold: number,
+  ) {}
+
+  /** The raw isolation score in (0, 1]. */
+  score(x: Vec): number {
+    const c = averagePathLength(this.sampleSize);
+    if (c === 0) return 0.5;
+    const mean = this.trees.reduce((s, t) => s + pathLength(t, x), 0) / this.trees.length;
+    return Math.pow(2, -mean / c);
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const s = this.score(x) / this.threshold;
+    return { scores: [s], confidence: anomalyConfidence(s) };
+  }
+}
+
+export function fitIsolationForest(samples: readonly MlSample[], opts: IsolationForestOptions = {}): IsolationForestModel {
+  const X = samples.map((s) => s.x);
+  featureDim(X);
+  const rnd = seededUniform(opts.seed ?? 0x15f0);
+  const psi = Math.min(opts.sampleSize ?? 256, X.length);
+  const limit = Math.ceil(Math.log2(Math.max(psi, 2)));
+  const trees: ITree[] = [];
+  for (let t = 0; t < (opts.trees ?? 100); t++) {
+    // Sample ψ points without replacement (partial Fisher–Yates over indices).
+    const idx = X.map((_, i) => i);
+    for (let i = 0; i < psi; i++) {
+      const j = i + Math.floor(rnd() * (idx.length - i));
+      [idx[i], idx[j]] = [idx[j]!, idx[i]!];
+    }
+    trees.push(buildTree(idx.slice(0, psi).map((i) => X[i]!), 0, limit, rnd));
+  }
+  return new IsolationForestModel(trees, psi, opts.threshold ?? 0.6);
+}

package/src/ml/classical/kmeans.ts

@@ -0,0 +1,120 @@
+/**
+ * ml/classical/kmeans.ts — k-means clustering (k-means++ seeding, Lloyd iterations).
+ *
+ * Deterministic for a given seed. A prediction is the nearest centroid; its
+ * confidence is how much closer that centroid is than the runner-up.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { featureDim, seededUniform, squaredDistance, type Vec } from "./math.js";
+
+export interface KMeansOptions {
+  /** Clusters. Default round(√(n/2)), at least 1. */
+  k?: number;
+  maxIterations?: number;
+  seed?: number;
+}
+
+export class KMeansModel implements MlPredictor {
+  constructor(
+    readonly centroids: Float32Array[],
+    /** Sum of squared distances of the fitted points to their centroid. */
+    readonly inertia: number,
+  ) {}
+
+  /** Nearest centroid index and the two smallest squared distances. */
+  assign(x: Vec): { cluster: number; d1: number; d2: number } {
+    let cluster = 0;
+    let d1 = Infinity;
+    let d2 = Infinity;
+    this.centroids.forEach((c, i) => {
+      const d = squaredDistance(x, c);
+      if (d < d1) {
+        d2 = d1;
+        d1 = d;
+        cluster = i;
+      } else if (d < d2) d2 = d;
+    });
+    return { cluster, d1, d2 };
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const { cluster, d1, d2 } = this.assign(x);
+    const confidence = Number.isFinite(d2) && d2 > 0 ? 1 - Math.sqrt(d1) / Math.sqrt(d2) : 1;
+    return { scores: [cluster], confidence: Math.max(0, Math.min(1, confidence)) };
+  }
+}
+
+export function fitKMeans(samples: readonly MlSample[], opts: KMeansOptions = {}): KMeansModel {
+  const X = samples.map((s) => s.x);
+  const d = featureDim(X);
+  const k = Math.min(X.length, Math.max(1, opts.k ?? Math.round(Math.sqrt(X.length / 2))));
+  const rnd = seededUniform(opts.seed ?? 0x6b6d);
+
+  // k-means++: first centroid uniformly, the rest ∝ squared distance to the nearest chosen one.
+  const centroids: Float32Array[] = [Float32Array.from(X[Math.floor(rnd() * X.length)]!)];
+  const nearest = X.map((x) => squaredDistance(x, centroids[0]!));
+  while (centroids.length < k) {
+    const total = nearest.reduce((a, b) => a + b, 0);
+    let pick = 0;
+    if (total > 0) {
+      // Walk only points with weight: a zero-distance point (already a centroid) can
+      // never be picked, even when rnd() returns 0 and r starts at 0.
+      let r = rnd() * total;
+      let last = -1;
+      for (pick = 0; pick < X.length; pick++) {
+        if (!(nearest[pick]! > 0)) continue;
+        last = pick;
+        r -= nearest[pick]!;
+        if (r <= 0) break;
+      }
+      if (pick >= X.length) pick = last; // float round-off left r > 0: take the last weighted point
+    } else {
+      pick = centroids.length; // every point coincides with a centroid; take the next index
+    }
+    const c = Float32Array.from(X[pick]!);
+    centroids.push(c);
+    X.forEach((x, i) => (nearest[i] = Math.min(nearest[i]!, squaredDistance(x, c))));
+  }
+
+  const assign = new Int32Array(X.length).fill(-1);
+  /** Assign every point to its nearest current centroid; true when any assignment moved. */
+  const reassign = (): boolean => {
+    let changed = false;
+    const model = new KMeansModel(centroids, 0);
+    X.forEach((x, i) => {
+      const c = model.assign(x).cluster;
+      if (assign[i] !== c) {
+        assign[i] = c;
+        changed = true;
+      }
+    });
+    return changed;
+  };
+  const maxIt = opts.maxIterations ?? 100;
+  let converged = false;
+  for (let it = 0; it < maxIt; it++) {
+    if (!reassign()) {
+      converged = true;
+      break;
+    }
+    const sums = centroids.map(() => new Float64Array(d));
+    const counts = new Array<number>(k).fill(0);
+    X.forEach((x, i) => {
+      const c = assign[i]!;
+      counts[c] = counts[c]! + 1;
+      for (let j = 0; j < d; j++) sums[c]![j] = sums[c]![j]! + x[j]!;
+    });
+    // An emptied cluster keeps its previous centroid.
+    centroids.forEach((c, ci) => {
+      if (counts[ci]! > 0) for (let j = 0; j < d; j++) c[j] = sums[ci]![j]! / counts[ci]!;
+    });
+  }
+
+  // Stopped on maxIterations: the centroids moved after the last assignment, so
+  // assign once more — inertia (and the stored model) must describe the same state.
+  if (!converged) reassign();
+
+  let inertia = 0;
+  X.forEach((x, i) => (inertia += squaredDistance(x, centroids[assign[i]!]!)));
+  return new KMeansModel(centroids, inertia);
+}

package/src/ml/classical/knn.ts

@@ -0,0 +1,102 @@
+/**
+ * ml/classical/knn.ts — k-nearest-neighbours classification over feature vectors.
+ *
+ * Votes are similarity-weighted (cosine similarity, or 1/(1+distance) for the
+ * euclidean metric), so a close neighbour counts for more than a far one. The
+ * same index answers "what is my nearest neighbour?" — the de-duplication query.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { classCount, cosine, featureDim, squaredDistance, topProbability, type Vec } from "./math.js";
+
+export type KnnMetric = "cosine" | "euclidean";
+
+export interface KnnOptions {
+  /**
+   * Neighbours that vote. Default min(5, ⌊√n⌋), at least 1: with a small set a fixed
+   * 5 makes EVERY point vote, and the answer collapses to the class prior.
+   */
+  k?: number;
+  metric?: KnnMetric;
+  /** Number of classes (default: inferred from the labels, at least 2). */
+  classes?: number;
+}
+
+export interface Neighbour {
+  index: number;
+  /** Higher = closer: cosine similarity, or 1/(1+distance) for euclidean. */
+  similarity: number;
+}
+
+export class KnnModel implements MlPredictor {
+  private readonly _x: Float32Array[] = [];
+  private readonly _y: number[] = [];
+  private readonly _w: number[] = [];
+
+  constructor(
+    readonly k: number,
+    readonly metric: KnnMetric,
+    readonly classes: number,
+  ) {
+    if (!(k >= 1)) throw new Error(`KnnModel: k must be ≥ 1 (got ${k})`);
+  }
+
+  /** How many points the index holds. */
+  get size(): number {
+    return this._x.length;
+  }
+
+  /** Add one labelled point (online — the index never needs a refit). */
+  add(x: Vec, y = 0, weight = 1): void {
+    this._x.push(Float32Array.from(x));
+    this._y.push(y);
+    this._w.push(weight);
+  }
+
+  similarity(a: Vec, b: Vec): number {
+    return this.metric === "cosine" ? cosine(a, b) : 1 / (1 + Math.sqrt(squaredDistance(a, b)));
+  }
+
+  /** The `k` closest points, closest first. */
+  neighbours(x: Vec, k: number = this.k): Neighbour[] {
+    const all = this._x.map((p, index) => ({ index, similarity: this.similarity(x, p) }));
+    all.sort((a, b) => b.similarity - a.similarity || a.index - b.index);
+    return all.slice(0, Math.min(k, all.length));
+  }
+
+  /** The single closest point, or null when the index is empty. */
+  nearest(x: Vec): Neighbour | null {
+    return this.neighbours(x, 1)[0] ?? null;
+  }
+
+  /** The label of an indexed point. */
+  labelOf(index: number): number {
+    return this._y[index]!;
+  }
+
+  /** Class probabilities from similarity-weighted votes (uniform when empty). */
+  proba(x: Vec): number[] {
+    const votes = new Array<number>(this.classes).fill(0);
+    for (const n of this.neighbours(x)) {
+      // Shift cosine into (0, 2] so an orthogonal neighbour still casts a small vote.
+      const w = (this.metric === "cosine" ? n.similarity + 1 : n.similarity) * this._w[n.index]! + 1e-9;
+      votes[this._y[n.index]!]! += w;
+    }
+    const sum = votes.reduce((a, b) => a + b, 0);
+    return sum > 0 ? votes.map((v) => v / sum) : votes.map(() => 1 / this.classes);
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const scores = this.proba(x);
+    return { scores, confidence: topProbability(scores) };
+  }
+}
+
+/** Index `samples` for kNN classification. */
+export function fitKnn(samples: readonly MlSample[], opts: KnnOptions = {}): KnnModel {
+  featureDim(samples.map((s) => s.x));
+  const classes = opts.classes ?? classCount(samples.map((s) => s.y));
+  const k = opts.k ?? Math.min(5, Math.max(1, Math.floor(Math.sqrt(samples.length))));
+  const model = new KnnModel(Math.min(k, samples.length), opts.metric ?? "cosine", classes);
+  for (const s of samples) model.add(s.x, s.y, s.weight ?? 1);
+  return model;
+}

package/src/ml/classical/linear.ts

@@ -0,0 +1,119 @@
+/**
+ * ml/classical/linear.ts — ridge linear regression, closed form.
+ *
+ * Solves (XᵀWX + λI)w = XᵀWy with an unpenalised intercept by Gaussian
+ * elimination with partial pivoting. Small dims only (the catalog's numeric
+ * tasks), which is exactly where a closed form beats iterating.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { featureDim } from "./math.js";
+
+export interface LinearOptions {
+  /** L2 penalty on weights (not the intercept). Default 1e-6. */
+  l2?: number;
+}
+
+export class LinearModel implements MlPredictor {
+  constructor(
+    readonly weights: Float32Array,
+    public intercept: number,
+    /** Coefficient of determination on the fitted data, clamped to [0, 1]. */
+    readonly r2: number,
+  ) {}
+
+  value(x: ArrayLike<number>): number {
+    let s = this.intercept;
+    for (let i = 0; i < this.weights.length; i++) s += this.weights[i]! * (x[i] ?? 0);
+    return s;
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    return { scores: [this.value(x)], confidence: this.r2 };
+  }
+
+  exportParams(): Float32Array {
+    const out = new Float32Array(this.weights.length + 1);
+    out.set(this.weights, 0);
+    out[this.weights.length] = this.intercept;
+    return out;
+  }
+
+  importParams(params: ArrayLike<number>): void {
+    if (params.length !== this.weights.length + 1) {
+      throw new Error(`LinearModel.importParams: expected ${this.weights.length + 1} values, got ${params.length}`);
+    }
+    for (let i = 0; i < this.weights.length; i++) this.weights[i] = params[i]!;
+    this.intercept = params[this.weights.length]!;
+  }
+}
+
+/** Solve A·x = b in place (A is n×n row-major). Throws when singular. */
+export function solveLinearSystem(A: Float64Array, b: Float64Array, n: number): Float64Array {
+  for (let col = 0; col < n; col++) {
+    let piv = col;
+    for (let r = col + 1; r < n; r++) if (Math.abs(A[r * n + col]!) > Math.abs(A[piv * n + col]!)) piv = r;
+    if (Math.abs(A[piv * n + col]!) < 1e-12) throw new Error("solveLinearSystem: singular matrix");
+    if (piv !== col) {
+      for (let c = 0; c < n; c++) {
+        const t = A[col * n + c]!;
+        A[col * n + c] = A[piv * n + c]!;
+        A[piv * n + c] = t;
+      }
+      const t = b[col]!;
+      b[col] = b[piv]!;
+      b[piv] = t;
+    }
+    for (let r = col + 1; r < n; r++) {
+      const f = A[r * n + col]! / A[col * n + col]!;
+      if (f === 0) continue;
+      for (let c = col; c < n; c++) A[r * n + c] = A[r * n + c]! - f * A[col * n + c]!;
+      b[r] = b[r]! - f * b[col]!;
+    }
+  }
+  const x = new Float64Array(n);
+  for (let r = n - 1; r >= 0; r--) {
+    let s = b[r]!;
+    for (let c = r + 1; c < n; c++) s -= A[r * n + c]! * x[c]!;
+    x[r] = s / A[r * n + r]!;
+  }
+  return x;
+}
+
+export function fitLinear(samples: readonly MlSample[], opts: LinearOptions = {}): LinearModel {
+  const d = featureDim(samples.map((s) => s.x));
+  const n = d + 1; // last column = intercept
+  const A = new Float64Array(n * n);
+  const b = new Float64Array(n);
+  const row = new Float64Array(n);
+  for (const s of samples) {
+    const w = s.weight ?? 1;
+    for (let i = 0; i < d; i++) row[i] = s.x[i]!;
+    row[d] = 1;
+    for (let i = 0; i < n; i++) {
+      b[i] = b[i]! + w * row[i]! * s.y;
+      for (let j = 0; j < n; j++) A[i * n + j] = A[i * n + j]! + w * row[i]! * row[j]!;
+    }
+  }
+  const l2 = opts.l2 ?? 1e-6;
+  for (let i = 0; i < d; i++) A[i * n + i] = A[i * n + i]! + l2;
+  const sol = solveLinearSystem(A, b, n);
+  const model = new LinearModel(Float32Array.from(sol.subarray(0, d)), sol[d]!, 0);
+
+  // R² on the fitted data — the confidence the runner reports.
+  let wSum = 0;
+  let mean = 0;
+  for (const s of samples) {
+    wSum += s.weight ?? 1;
+    mean += (s.weight ?? 1) * s.y;
+  }
+  mean /= wSum;
+  let ssRes = 0;
+  let ssTot = 0;
+  for (const s of samples) {
+    const w = s.weight ?? 1;
+    ssRes += w * (s.y - model.value(s.x)) ** 2;
+    ssTot += w * (s.y - mean) ** 2;
+  }
+  const r2 = ssTot > 0 ? Math.min(1, Math.max(0, 1 - ssRes / ssTot)) : ssRes < 1e-12 ? 1 : 0;
+  return new LinearModel(model.weights, model.intercept, r2);
+}

package/src/ml/classical/logistic.ts

@@ -0,0 +1,125 @@
+/**
+ * ml/classical/logistic.ts — (multinomial) logistic regression.
+ *
+ * Softmax regression with L2, fitted by full-batch gradient descent; two classes
+ * is ordinary logistic regression. No internal feature scaling: a task supplies
+ * features on a stable scale, so a weight means the same thing on every machine —
+ * which is what lets trained weights FEDERATE (`exportParams` / `importParams`).
+ */
+import { mlEvalLoss } from "../eval_loss.js";
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { classCount, featureDim, softmax, topProbability } from "./math.js";
+
+export interface LogisticOptions {
+  classes?: number;
+  learningRate?: number;
+  epochs?: number;
+  /** L2 penalty on weights (not biases). Default 1e-3. */
+  l2?: number;
+}
+
+export class LogisticModel implements MlPredictor {
+  /** Row-major weights [classes × dim]. */
+  readonly weights: Float32Array;
+  readonly bias: Float32Array;
+
+  constructor(
+    readonly dim: number,
+    readonly classes: number,
+  ) {
+    this.weights = new Float32Array(classes * dim);
+    this.bias = new Float32Array(classes);
+  }
+
+  logits(x: ArrayLike<number>): number[] {
+    const z: number[] = [];
+    for (let c = 0; c < this.classes; c++) {
+      let s = this.bias[c]!;
+      const off = c * this.dim;
+      for (let i = 0; i < this.dim; i++) s += this.weights[off + i]! * (x[i] ?? 0);
+      z.push(s);
+    }
+    return z;
+  }
+
+  proba(x: ArrayLike<number>): number[] {
+    return Array.from(softmax(this.logits(x)));
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const scores = this.proba(x);
+    return { scores, confidence: topProbability(scores) };
+  }
+
+  /** Weighted mean cross-entropy over `samples` — exactly the eval-gate loss ({@link mlEvalLoss}); 0 for an empty set. */
+  loss(samples: readonly MlSample[]): number {
+    return mlEvalLoss("classify", this, samples) ?? 0;
+  }
+
+  /** One full-batch gradient step; returns the pre-step mean loss. */
+  step(samples: readonly MlSample[], learningRate: number, l2: number): number {
+    const gW = new Float64Array(this.weights.length);
+    const gB = new Float64Array(this.classes);
+    let loss = 0;
+    let wSum = 0;
+    for (const s of samples) {
+      const w = s.weight ?? 1;
+      const p = this.proba(s.x);
+      loss += -w * Math.log(Math.max(p[s.y]!, 1e-12));
+      wSum += w;
+      for (let c = 0; c < this.classes; c++) {
+        const g = w * (p[c]! - (c === s.y ? 1 : 0));
+        gB[c] = gB[c]! + g;
+        const off = c * this.dim;
+        for (let i = 0; i < this.dim; i++) gW[off + i] = gW[off + i]! + g * s.x[i]!;
+      }
+    }
+    const inv = wSum > 0 ? 1 / wSum : 0;
+    for (let j = 0; j < this.weights.length; j++) {
+      this.weights[j] = this.weights[j]! - learningRate * (gW[j]! * inv + l2 * this.weights[j]!);
+    }
+    for (let c = 0; c < this.classes; c++) this.bias[c] = this.bias[c]! - learningRate * gB[c]! * inv;
+    return loss * inv;
+  }
+
+  exportParams(): Float32Array {
+    const out = new Float32Array(this.weights.length + this.bias.length);
+    out.set(this.weights, 0);
+    out.set(this.bias, this.weights.length);
+    return out;
+  }
+
+  importParams(params: ArrayLike<number>): void {
+    if (params.length !== this.weights.length + this.bias.length) {
+      throw new Error(`LogisticModel.importParams: expected ${this.weights.length + this.bias.length} values, got ${params.length}`);
+    }
+    for (let j = 0; j < this.weights.length; j++) this.weights[j] = params[j]!;
+    for (let c = 0; c < this.bias.length; c++) this.bias[c] = params[this.weights.length + c]!;
+  }
+}
+
+/**
+ * Fit logistic regression. Pass `init` to continue from existing weights (a local
+ * round on top of a merged federated head).
+ */
+export function fitLogistic(
+  samples: readonly MlSample[],
+  opts: LogisticOptions = {},
+  init?: LogisticModel,
+): LogisticModel {
+  const d = featureDim(samples.map((s) => s.x));
+  const k = opts.classes ?? init?.classes ?? classCount(samples.map((s) => s.y));
+  // A label at or above `classes` has no row of weights: its probability would be
+  // read as undefined and every loss and gradient would turn NaN, silently.
+  const top = classCount(samples.map((s) => s.y));
+  if (top > k && samples.some((s) => s.y >= k)) {
+    throw new Error(`fitLogistic: labels go up to ${top - 1} but the model has ${k} classes`);
+  }
+  const model = init ?? new LogisticModel(d, k);
+  if (model.dim !== d || model.classes !== k) throw new Error(`fitLogistic: init is ${model.dim}×${model.classes}, data is ${d}×${k}`);
+  const lr = opts.learningRate ?? 0.5;
+  const l2 = opts.l2 ?? 1e-3;
+  const epochs = opts.epochs ?? 300;
+  for (let e = 0; e < epochs; e++) model.step(samples, lr, l2);
+  return model;
+}