@seanhogg/builderforce-memory-engine 2026.10.1 → 2026.10.3

package/src/ml/classical/gbm.ts

@@ -1,143 +1,144 @@
-/**
- * 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);
-}
+/**
+ * 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;
+  }
+  // All-zero weights would make this 0/0: fall back to the unweighted mean.
+  const yMean = wSum > 0 ? ySum / wSum : samples.reduce((a, s) => a + s.y, 0) / samples.length;
+  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

@@ -10,6 +10,7 @@ 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";
 
@@ -23,10 +24,12 @@ 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 { RobustZModel, fitRobustZ, anomalyConfidence, minScaleAt } from "./robust_z.js";
+export type { RobustZOptions, MinScale } 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";
@@ -42,6 +45,7 @@ export interface ClassicalOptions {
   kmeans?: KMeansOptions;
   "robust-z"?: RobustZOptions;
   ewma?: EwmaOptions;
+  "anomaly-composite"?: AnomalyCompositeOptions;
   "isolation-forest"?: IsolationForestOptions;
   "gbm-small"?: GbmOptions;
 }
@@ -68,6 +72,8 @@ export function fitClassical(
       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":

package/src/ml/classical/kmeans.ts

@@ -57,11 +57,17 @@ export function fitKMeans(samples: readonly MlSample[], opts: KMeansOptions = {}
     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;
-      for (pick = 0; pick < X.length - 1; pick++) {
+      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
     }
@@ -71,8 +77,8 @@ export function fitKMeans(samples: readonly MlSample[], opts: KMeansOptions = {}
   }
 
   const assign = new Int32Array(X.length).fill(-1);
-  const maxIt = opts.maxIterations ?? 100;
-  for (let it = 0; it < maxIt; it++) {
+  /** 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) => {
@@ -82,7 +88,15 @@ export function fitKMeans(samples: readonly MlSample[], opts: KMeansOptions = {}
         changed = true;
       }
     });
-    if (!changed) break;
+    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) => {
@@ -96,6 +110,10 @@ export function fitKMeans(samples: readonly MlSample[], opts: KMeansOptions = {}
     });
   }
 
+  // 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

@@ -11,7 +11,10 @@ import { classCount, cosine, featureDim, squaredDistance, topProbability, type V
 export type KnnMetric = "cosine" | "euclidean";
 
 export interface KnnOptions {
-  /** Neighbours that vote. Default 5 (capped at the sample count). */
+  /**
+   * 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). */
@@ -53,9 +56,12 @@ export class KnnModel implements MlPredictor {
     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) }));
+  /** The `k` closest points, closest first — never the point at `exclude` (leave-one-out). */
+  neighbours(x: Vec, k: number = this.k, exclude?: number): Neighbour[] {
+    const all: Neighbour[] = [];
+    for (let index = 0; index < this._x.length; index++) {
+      if (index !== exclude) all.push({ index, similarity: this.similarity(x, this._x[index]!) });
+    }
     all.sort((a, b) => b.similarity - a.similarity || a.index - b.index);
     return all.slice(0, Math.min(k, all.length));
   }
@@ -70,10 +76,15 @@ export class KnnModel implements MlPredictor {
     return this._y[index]!;
   }
 
-  /** Class probabilities from similarity-weighted votes (uniform when empty). */
-  proba(x: Vec): number[] {
+  /**
+   * Class probabilities from similarity-weighted votes (uniform when empty). With
+   * `exclude`, the point at that index does not vote — the leave-one-out score of a
+   * point that is itself in the index, which would otherwise vote for itself at
+   * similarity 1.
+   */
+  proba(x: Vec, exclude?: number): number[] {
     const votes = new Array<number>(this.classes).fill(0);
-    for (const n of this.neighbours(x)) {
+    for (const n of this.neighbours(x, this.k, exclude)) {
       // 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;
@@ -86,13 +97,25 @@ export class KnnModel implements MlPredictor {
     const scores = this.proba(x);
     return { scores, confidence: topProbability(scores) };
   }
+
+  /** This index as a predictor that leaves the point at `index` out of every vote. */
+  excluding(index: number): MlPredictor {
+    if (!(index >= 0 && index < this._x.length)) throw new Error(`KnnModel.excluding: no point ${index} (size ${this._x.length})`);
+    return {
+      predict: (x: Float32Array): MlPrediction => {
+        const scores = this.proba(x, index);
+        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);
+  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/logistic.ts

@@ -6,6 +6,7 @@
  * 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";
 
@@ -50,16 +51,9 @@ export class LogisticModel implements MlPredictor {
     return { scores, confidence: topProbability(scores) };
   }
 
-  /** Weighted mean cross-entropy over `samples` (the eval-gate loss). */
+  /** Weighted mean cross-entropy over `samples` — exactly the eval-gate loss ({@link mlEvalLoss}); 0 for an empty set. */
   loss(samples: readonly MlSample[]): number {
-    let sum = 0;
-    let wSum = 0;
-    for (const s of samples) {
-      const w = s.weight ?? 1;
-      sum += -w * Math.log(Math.max(this.proba(s.x)[s.y] ?? 0, 1e-12));
-      wSum += w;
-    }
-    return wSum > 0 ? sum / wSum : 0;
+    return mlEvalLoss("classify", this, samples) ?? 0;
   }
 
   /** One full-batch gradient step; returns the pre-step mean loss. */
@@ -115,6 +109,12 @@ export function fitLogistic(
 ): 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;