@seanhogg/builderforce-memory-engine 2026.9.34 → 2026.10.1

package/src/ml/classical/gbm.ts

@@ -0,0 +1,143 @@
+/**
+ * ml/classical/gbm.ts — a small gradient-boosted tree ensemble.
+ *
+ * Depth-limited regression trees fitted to the loss gradient, one after another,
+ * shrunk by a learning rate. Objectives: `binary` (log-loss, Newton leaf values)
+ * and `regression` (squared error). Exhaustive split search over midpoints —
+ * fine for the catalog's small numeric feature sets, not for wide embeddings.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { featureDim, sigmoid, type Vec } from "./math.js";
+
+export type GbmObjective = "binary" | "regression";
+
+export interface GbmOptions {
+  objective?: GbmObjective;
+  trees?: number;
+  maxDepth?: number;
+  learningRate?: number;
+  /** Minimum summed sample weight in a leaf. Default 1. */
+  minLeafWeight?: number;
+  /** L2 on leaf values (Newton denominator). Default 1. */
+  lambda?: number;
+}
+
+type RTree = { value: number } | { feature: number; split: number; left: RTree; right: RTree };
+
+interface Row {
+  x: Vec;
+  g: number; // gradient
+  h: number; // hessian
+  w: number;
+}
+
+function leafValue(rows: readonly Row[], lambda: number): number {
+  let g = 0;
+  let h = 0;
+  for (const r of rows) {
+    g += r.w * r.g;
+    h += r.w * r.h;
+  }
+  return -g / (h + lambda);
+}
+
+/** XGBoost-style structure score G²/(H+λ) of a node. */
+function gain(g: number, h: number, lambda: number): number {
+  return (g * g) / (h + lambda);
+}
+
+function buildTree(rows: Row[], depth: number, opts: Required<Omit<GbmOptions, "objective" | "trees" | "learningRate">>): RTree {
+  if (depth >= opts.maxDepth || rows.length < 2) return { value: leafValue(rows, opts.lambda) };
+  let G = 0;
+  let H = 0;
+  let W = 0;
+  for (const r of rows) {
+    G += r.w * r.g;
+    H += r.w * r.h;
+    W += r.w;
+  }
+  const parent = gain(G, H, opts.lambda);
+  let best: { feature: number; split: number; score: number } | null = null;
+  const d = rows[0]!.x.length;
+  for (let f = 0; f < d; f++) {
+    const sorted = [...rows].sort((a, b) => a.x[f]! - b.x[f]!);
+    let gl = 0;
+    let hl = 0;
+    let wl = 0;
+    for (let i = 0; i < sorted.length - 1; i++) {
+      const r = sorted[i]!;
+      gl += r.w * r.g;
+      hl += r.w * r.h;
+      wl += r.w;
+      const a = r.x[f]!;
+      const b = sorted[i + 1]!.x[f]!;
+      if (a === b) continue;
+      if (wl < opts.minLeafWeight || W - wl < opts.minLeafWeight) continue;
+      const score = gain(gl, hl, opts.lambda) + gain(G - gl, H - hl, opts.lambda) - parent;
+      if (score > 1e-12 && (!best || score > best.score)) best = { feature: f, split: (a + b) / 2, score };
+    }
+  }
+  if (!best) return { value: leafValue(rows, opts.lambda) };
+  const left = rows.filter((r) => r.x[best!.feature]! < best!.split);
+  const right = rows.filter((r) => r.x[best!.feature]! >= best!.split);
+  return { feature: best.feature, split: best.split, left: buildTree(left, depth + 1, opts), right: buildTree(right, depth + 1, opts) };
+}
+
+function treeValue(t: RTree, x: Vec): number {
+  while (!("value" in t)) t = x[t.feature]! < t.split ? t.left : t.right;
+  return t.value;
+}
+
+export class GbmModel implements MlPredictor {
+  constructor(
+    readonly objective: GbmObjective,
+    readonly base: number,
+    readonly trees: readonly RTree[],
+    readonly learningRate: number,
+  ) {}
+
+  /** The raw additive score (log-odds for `binary`). */
+  margin(x: Vec): number {
+    let s = this.base;
+    for (const t of this.trees) s += this.learningRate * treeValue(t, x);
+    return s;
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const m = this.margin(x);
+    if (this.objective === "regression") return { scores: [m], confidence: 1 };
+    const p = sigmoid(m);
+    return { scores: [1 - p, p], confidence: Math.max(p, 1 - p) };
+  }
+}
+
+export function fitGbm(samples: readonly MlSample[], opts: GbmOptions = {}): GbmModel {
+  featureDim(samples.map((s) => s.x));
+  const objective = opts.objective ?? "binary";
+  const lr = opts.learningRate ?? 0.3;
+  const treeOpts = { maxDepth: opts.maxDepth ?? 2, minLeafWeight: opts.minLeafWeight ?? 1, lambda: opts.lambda ?? 1 };
+
+  let wSum = 0;
+  let ySum = 0;
+  for (const s of samples) {
+    wSum += s.weight ?? 1;
+    ySum += (s.weight ?? 1) * s.y;
+  }
+  const yMean = ySum / wSum;
+  const base = objective === "binary" ? Math.log(Math.max(yMean, 1e-6) / Math.max(1 - yMean, 1e-6)) : yMean;
+  const margins = samples.map(() => base);
+  const trees: RTree[] = [];
+  for (let t = 0; t < (opts.trees ?? 50); t++) {
+    const rows: Row[] = samples.map((s, i) => {
+      if (objective === "binary") {
+        const p = sigmoid(margins[i]!);
+        return { x: s.x, g: p - s.y, h: Math.max(p * (1 - p), 1e-6), w: s.weight ?? 1 };
+      }
+      return { x: s.x, g: margins[i]! - s.y, h: 1, w: s.weight ?? 1 };
+    });
+    const tree = buildTree(rows, 0, treeOpts);
+    trees.push(tree);
+    samples.forEach((s, i) => (margins[i] = margins[i]! + lr * treeValue(tree, s.x)));
+  }
+  return new GbmModel(objective, base, trees, lr);
+}

package/src/ml/classical/index.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 { 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 { 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;
+  "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 "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,102 @@
+/**
+ * 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) {
+      let r = rnd() * total;
+      for (pick = 0; pick < X.length - 1; pick++) {
+        r -= nearest[pick]!;
+        if (r <= 0) break;
+      }
+    } 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);
+  const maxIt = opts.maxIterations ?? 100;
+  for (let it = 0; it < maxIt; it++) {
+    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;
+      }
+    });
+    if (!changed) 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]!;
+    });
+  }
+
+  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,98 @@
+/**
+ * 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 5 (capped at the sample count). */
+  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 model = new KnnModel(Math.min(opts.k ?? 5, 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);
+}