@seanhogg/builderforce-memory-engine 2026.9.34 → 2026.10.2

package/src/limbic/limbic_task.ts

@@ -0,0 +1,62 @@
+/**
+ * limbic/limbic_task.ts — `limbic.affect`, the ML catalog's first row, registered
+ * by limbic/ itself.
+ *
+ * Nothing about the affect head changes: the row describes it (input = experience
+ * embedding + affective state, output = bounded affect delta + reward), the
+ * predictor adapter lets the ONE runner answer with an existing `LimbicModel`, and
+ * training stays `LimbicTrainer` (itself a thin registration over `HeadTrainer`).
+ * Its flat parameters are what federate when the head travels with the model.
+ */
+import { assignParams, flattenParams } from "../ml/head_trainer.js";
+import type { MlPrediction, MlPredictor, MlTask } from "../ml/types.js";
+import type { LimbicModel } from "./limbic_model.js";
+
+export interface LimbicAffectInput {
+  /** Experience embedding (length = model.inputDim). */
+  embedding: ArrayLike<number>;
+  /** Current affective state (length = model.stateDim). */
+  state: ArrayLike<number>;
+}
+
+export interface LimbicAffectOutput {
+  /** Bounded affect delta in (-1, 1) per state dim. */
+  delta: Float32Array;
+  /** Reward prediction. */
+  reward: number;
+}
+
+export const LIMBIC_AFFECT_TASK: MlTask<LimbicAffectInput, LimbicAffectOutput> = {
+  kind: "regress",
+  id: "limbic.affect",
+  description: "How an experience moves the agent's affective state, and how rewarding it was.",
+  features: { numeric: (i) => [...Array.from(i.embedding), ...Array.from(i.state)] },
+  engines: [{ tier: "local", engine: "head", head: "mlp" }],
+  train: { minSamples: 1, trainedBy: "LimbicTrainer" },
+  output: {
+    decode: (p: MlPrediction) => ({
+      delta: Float32Array.from(p.scores.slice(0, -1)),
+      reward: p.scores[p.scores.length - 1] ?? 0,
+    }),
+  },
+};
+
+/**
+ * Answer `limbic.affect` with `model`. The feature vector is `[embedding, state]`;
+ * the hidden scratch resets per call, exactly as the trainer treats each sample.
+ * Confidence is 1: a deterministic regression head has no calibrated uncertainty.
+ */
+export function limbicAffectPredictor(model: LimbicModel): MlPredictor {
+  const { inputDim, stateDim } = model.config;
+  return {
+    predict(x: Float32Array): MlPrediction {
+      if (x.length !== inputDim + stateDim) {
+        throw new Error(`limbic.affect: expected ${inputDim + stateDim} features (embedding ${inputDim} + state ${stateDim}), got ${x.length}`);
+      }
+      const f = model.forward(x.subarray(0, inputDim), model.initHidden(), x.subarray(inputDim));
+      return { scores: [...Array.from(f.delta), f.reward], confidence: 1 };
+    },
+    exportParams: () => flattenParams(model.parameters()),
+    importParams: (params) => assignParams(model.parameters(), params),
+  };
+}

package/src/limbic/limbic_trainer.ts

@@ -3,26 +3,17 @@
  *
  * Trains the affect head to predict affect deltas and reward from
  * (experience embedding, current state) pairs, using full-batch gradient
- * descent with AdamW. When a GPUDevice is supplied the optimiser step runs on
- * the GPU via the shared WEIGHT_UPDATE_WGSL kernel (real WebGPU training); with
- * no device it uses a numerically-equivalent CPU AdamW so training works
- * everywhere (CI, Node without @webgpu/node, etc.).
+ * descent with AdamW — through the shared {@link HeadTrainer} (`ml/head_trainer.ts`),
+ * which runs the optimiser step on the GPU via WEIGHT_UPDATE_WGSL when a device is
+ * supplied and on a numerically-equivalent CPU AdamW otherwise. This file is only
+ * the limbic registration: the head adapter and the public trainer surface.
  *
  * The objective is MSE (regression), not the cross-entropy used by the
  * language-model {@link MambaTrainer} — a limbic experience has continuous
  * targets, not a next-token distribution.
  */
 
-import {
-  createUniformBuffer,
-  createStorageBuffer,
-  createComputePipeline,
-  createBindGroup,
-  dispatchKernel,
-  readBuffer,
-  cdiv,
-} from "../utils/gpu_utils.js";
-import { WEIGHT_UPDATE_WGSL } from "../kernels/weight_update.js";
+import { HeadTrainer, type HeadTrainOptions, type TrainableHead } from "../ml/head_trainer.js";
 import type { LimbicModel, LimbicParam } from "./limbic_model.js";
 
 /** One training example: an experience and the affect change it should produce. */
@@ -37,222 +28,64 @@ export interface LimbicSample {
   reward: number;
 }
 
-export interface LimbicTrainOptions {
-  learningRate?: number;
-  epochs?: number;
-  weightDecay?: number;
-  beta1?: number;
-  beta2?: number;
-  eps?: number;
-  /** Max global gradient L2 norm before the optimiser step. Default 1.0. */
-  maxGradNorm?: number;
-  /** Per-epoch hook. `gradNorm` is the pre-clip gradient L2 norm this epoch (the
-   *  instability early-warning) — computed CPU-side so it's always available, unlike
-   *  the GPU trainer where it's opt-in. */
-  onEpochEnd?: ((epoch: number, loss: number, gradNorm?: number) => void) | null;
-}
-
-interface AdamMoment {
-  m: Float32Array;
-  v: Float32Array;
-}
+/** The limbic trainer's options are the shared head trainer's. */
+export type LimbicTrainOptions = HeadTrainOptions;
 
-function packAdamParams(
-  numElements: number,
-  lr: number,
-  beta1: number,
-  beta2: number,
-  eps: number,
-  weightDecay: number,
-  beta1_t: number,
-  beta2_t: number,
-): ArrayBuffer {
-  const buf = new ArrayBuffer(32);
-  new Uint32Array(buf, 0, 1).set([numElements]);
-  new Float32Array(buf, 4, 7).set([lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t]);
-  return buf;
+/**
+ * The limbic model as a {@link TrainableHead}. Each sample is one experience
+ * appraisal: cross-experience memory flows through the affective state `s` (fed
+ * back by the runtime), not through the hidden scratch `h`, so the hidden state
+ * resets per sample. This also makes BPTT(1) exact — there is no truncated carry.
+ */
+export function limbicHead(model: LimbicModel): TrainableHead<LimbicSample> {
+  return {
+    parameters: (): LimbicParam[] => model.parameters(),
+    gradients: (): LimbicParam[] => model.gradients(),
+    zeroGrad: () => model.zeroGrad(),
+    accumulate: (s) =>
+      model.backwardStep(s.input, model.initHidden(), s.state, s.deltaTarget, s.reward).loss,
+    loss: (s) => {
+      const { rewardWeight } = model.config;
+      const f = model.forward(s.input, model.initHidden(), s.state);
+      let loss = 0;
+      for (let k = 0; k < f.delta.length; k++) {
+        const d = f.delta[k]! - (s.deltaTarget[k] ?? 0);
+        loss += 0.5 * d * d;
+      }
+      const rd = f.reward - s.reward;
+      loss += 0.5 * rewardWeight * rd * rd;
+      return loss;
+    },
+  };
 }
 
+/** Thin registration of the limbic head over the shared {@link HeadTrainer}. */
 export class LimbicTrainer {
   readonly model: LimbicModel;
   readonly device: GPUDevice | null;
-  private _moments: AdamMoment[] | null = null;
-  private _step = 0;
-  private readonly _adamwPipeline: GPUComputePipeline | null;
+  private readonly _trainer: HeadTrainer<LimbicSample>;
 
   constructor(model: LimbicModel, device: GPUDevice | null = null) {
     this.model = model;
     this.device = device;
-    this._adamwPipeline = device
-      ? createComputePipeline(device, WEIGHT_UPDATE_WGSL, "adamw_update")
-      : null;
+    this._trainer = new HeadTrainer(limbicHead(model), device, "LimbicTrainer");
   }
 
   /** Whether the optimiser step runs on the GPU. */
   get gpuTraining(): boolean {
-    return this.device != null && this._adamwPipeline != null;
-  }
-
-  private _initMoments(): void {
-    if (this._moments) return;
-    this._moments = this.model.parameters().map((p) => ({
-      m: new Float32Array(p.numel),
-      v: new Float32Array(p.numel),
-    }));
+    return this._trainer.gpuTraining;
   }
 
   /**
    * Train on a batch of samples for `epochs` passes. Returns the per-epoch mean
-   * loss (monotonically decreasing on a learnable mapping). Full-batch: grads
-   * accumulate across the whole sequence (recurrent hidden carried, reset per
-   * epoch), are averaged, clipped, then applied once per epoch.
+   * loss (monotonically decreasing on a learnable mapping).
    */
-  async train(samples: LimbicSample[], opts: LimbicTrainOptions = {}): Promise<number[]> {
-    if (samples.length === 0) throw new Error("LimbicTrainer.train: no samples");
-    const {
-      learningRate = 0.05,
-      epochs = 50,
-      weightDecay = 0.0,
-      beta1 = 0.9,
-      beta2 = 0.999,
-      eps = 1e-8,
-      maxGradNorm = 1.0,
-      onEpochEnd = null,
-    } = opts;
-
-    this._initMoments();
-    const losses: number[] = [];
-
-    for (let epoch = 0; epoch < epochs; epoch++) {
-      this.model.zeroGrad();
-      let epochLoss = 0;
-
-      // Each sample is one experience appraisal: cross-experience memory flows
-      // through the affective state `s` (fed back by the runtime), not through
-      // the hidden scratch `h`, so the hidden state resets per sample. This also
-      // makes BPTT(1) exact — there is no truncated carry.
-      for (const s of samples) {
-        const { loss } = this.model.backwardStep(
-          s.input,
-          this.model.initHidden(),
-          s.state,
-          s.deltaTarget,
-          s.reward,
-        );
-        epochLoss += loss;
-      }
-
-      // Average gradients over the batch.
-      const grads = this.model.gradients();
-      const invN = 1 / samples.length;
-      for (const g of grads) {
-        for (let i = 0; i < g.data.length; i++) g.data[i]! *= invN;
-      }
-
-      const gradNorm = this._clipGradients(grads, maxGradNorm);
-
-      this._step++;
-      const beta1_t = Math.pow(beta1, this._step);
-      const beta2_t = Math.pow(beta2, this._step);
-      const hp = { learningRate, weightDecay, beta1, beta2, eps, beta1_t, beta2_t };
-      if (this.gpuTraining) {
-        await this._adamwStepGpu(grads, hp);
-      } else {
-        this._adamwStepCpu(grads, hp);
-      }
-
-      const avg = epochLoss / samples.length;
-      losses.push(avg);
-      if (onEpochEnd) onEpochEnd(epoch + 1, avg, gradNorm);
-    }
-    return losses;
+  train(samples: LimbicSample[], opts: LimbicTrainOptions = {}): Promise<number[]> {
+    return this._trainer.train(samples, opts);
   }
 
   /** Mean MSE loss over samples (no weight update). Hidden resets per sample. */
   evaluate(samples: LimbicSample[]): number {
-    if (samples.length === 0) return 0;
-    let total = 0;
-    const { rewardWeight } = this.model.config;
-    for (const s of samples) {
-      const f = this.model.forward(s.input, this.model.initHidden(), s.state);
-      let loss = 0;
-      for (let k = 0; k < f.delta.length; k++) {
-        const d = f.delta[k]! - (s.deltaTarget[k] ?? 0);
-        loss += 0.5 * d * d;
-      }
-      const rd = f.reward - s.reward;
-      loss += 0.5 * rewardWeight * rd * rd;
-      total += loss;
-    }
-    return total / samples.length;
-  }
-
-  /** Clip grads to `maxNorm` in place; returns the PRE-clip L2 norm (the signal). */
-  private _clipGradients(grads: LimbicParam[], maxNorm: number): number {
-    let normSq = 0;
-    for (const g of grads) for (let i = 0; i < g.data.length; i++) normSq += g.data[i]! * g.data[i]!;
-    const norm = Math.sqrt(normSq);
-    if (norm > maxNorm && norm > 0) {
-      const scale = maxNorm / norm;
-      for (const g of grads) for (let i = 0; i < g.data.length; i++) g.data[i]! *= scale;
-    }
-    return norm;
-  }
-
-  private _adamwStepCpu(
-    grads: LimbicParam[],
-    hp: { learningRate: number; weightDecay: number; beta1: number; beta2: number; eps: number; beta1_t: number; beta2_t: number },
-  ): void {
-    const params = this.model.parameters();
-    const { learningRate: lr, weightDecay: wd, beta1, beta2, eps, beta1_t, beta2_t } = hp;
-    for (let pi = 0; pi < params.length; pi++) {
-      const p = params[pi]!.data;
-      const g = grads[pi]!.data;
-      const mom = this._moments![pi]!;
-      for (let i = 0; i < p.length; i++) {
-        const gi = g[i]!;
-        mom.m[i] = beta1 * mom.m[i]! + (1 - beta1) * gi;
-        mom.v[i] = beta2 * mom.v[i]! + (1 - beta2) * gi * gi;
-        const mHat = mom.m[i]! / (1 - beta1_t);
-        const vHat = mom.v[i]! / (1 - beta2_t);
-        p[i] = p[i]! * (1 - lr * wd) - (lr * mHat) / (Math.sqrt(vHat) + eps);
-      }
-    }
-  }
-
-  /** AdamW on the GPU via the shared WEIGHT_UPDATE_WGSL kernel. Awaited per step. */
-  private async _adamwStepGpu(
-    grads: LimbicParam[],
-    hp: { learningRate: number; weightDecay: number; beta1: number; beta2: number; eps: number; beta1_t: number; beta2_t: number },
-  ): Promise<void> {
-    const device = this.device!;
-    const pipeline = this._adamwPipeline!;
-    const params = this.model.parameters();
-    const { learningRate: lr, weightDecay: wd, beta1, beta2, eps, beta1_t, beta2_t } = hp;
-
-    for (let pi = 0; pi < params.length; pi++) {
-      const p = params[pi]!;
-      const mom = this._moments![pi]!;
-      const paramBuf = createStorageBuffer(device, p.data, true);
-      const gradBuf = createStorageBuffer(device, grads[pi]!.data, false);
-      const mBuf = createStorageBuffer(device, mom.m, true);
-      const vBuf = createStorageBuffer(device, mom.v, true);
-      const uni = createUniformBuffer(
-        device,
-        packAdamParams(p.numel, lr, beta1, beta2, eps, wd, beta1_t, beta2_t),
-      );
-      const bg = createBindGroup(device, pipeline, [uni, paramBuf, gradBuf, mBuf, vBuf]);
-      dispatchKernel(device, pipeline, bg, [cdiv(p.numel, 256), 1, 1]);
-
-      p.data.set((await readBuffer(device, paramBuf, p.numel * 4)).subarray(0, p.numel));
-      mom.m.set((await readBuffer(device, mBuf, p.numel * 4)).subarray(0, p.numel));
-      mom.v.set((await readBuffer(device, vBuf, p.numel * 4)).subarray(0, p.numel));
-
-      paramBuf.destroy();
-      gradBuf.destroy();
-      mBuf.destroy();
-      vBuf.destroy();
-      uni.destroy();
-    }
+    return this._trainer.evaluate(samples);
   }
 }

package/src/ml/classical/anomaly_composite.ts

@@ -0,0 +1,46 @@
+/**
+ * ml/classical/anomaly_composite.ts — robust z and EWMA as ONE anomaly engine.
+ *
+ * Two detectors, one answer: robust z (median/MAD over the whole history — "far
+ * from normal") and EWMA (the recent trend — "drifting away from lately"). The
+ * score is the larger of the two normalised scores, so either one can flag. It is
+ * one engine because it is one fitted thing: a task that lists it gets back exactly
+ * what it stores under `local:classical:anomaly-composite`.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { EwmaModel, fitEwma, type EwmaOptions } from "./ewma.js";
+import { anomalyConfidence, fitRobustZ, RobustZModel, type RobustZOptions } from "./robust_z.js";
+
+export interface AnomalyCompositeOptions {
+  robustZ?: RobustZOptions;
+  ewma?: EwmaOptions;
+}
+
+export class AnomalyCompositeModel implements MlPredictor {
+  constructor(
+    readonly population: RobustZModel,
+    readonly trend: EwmaModel,
+  ) {}
+
+  /** Per feature, per detector: z / threshold (≥ 1 = out of range). */
+  featureScores(x: ArrayLike<number>): { population: number; trend: number }[] {
+    const pz = this.population.zScores(x);
+    const tz = this.trend.zScores(x);
+    return pz.map((z, i) => ({ population: z / this.population.threshold, trend: tz[i]! / this.trend.threshold }));
+  }
+
+  /** Fold a finished, non-anomalous observation into the trend. */
+  observe(x: ArrayLike<number>): void {
+    this.trend.update(x);
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const score = Math.max(this.population.predict(x).scores[0]!, this.trend.predict(x).scores[0]!);
+    return { scores: [score], confidence: anomalyConfidence(score) };
+  }
+}
+
+/** Fit both detectors on a chronological history (feature vectors, oldest first). */
+export function fitAnomalyComposite(samples: readonly MlSample[], opts: AnomalyCompositeOptions = {}): AnomalyCompositeModel {
+  return new AnomalyCompositeModel(fitRobustZ(samples, opts.robustZ), fitEwma(samples, opts.ewma));
+}

package/src/ml/classical/ewma.ts

@@ -0,0 +1,74 @@
+/**
+ * ml/classical/ewma.ts — exponentially-weighted moving average + variance, for
+ * drift anomalies in an ordered series (a run's cost creeping up over the week).
+ *
+ * Per feature, over the history IN ORDER: diff = x − μ; μ += α·diff;
+ * σ² = (1 − α)(σ² + α·diff²). A new point scores z = |x − μ| / σ against the
+ * state BEFORE it is folded in. Prediction: `scores[0] = max_i z_i / threshold`.
+ * σ is floored like robust z's scale: a fraction of |μ|, and `minScale` in absolute
+ * units — σ² starts at 0, so a constant history would otherwise flag any change.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { featureDim } from "./math.js";
+import { anomalyConfidence } from "./robust_z.js";
+
+export interface EwmaOptions {
+  /** Smoothing factor in (0, 1]. Default 0.3. */
+  alpha?: number;
+  /** z at which a feature counts as anomalous. Default 3. */
+  threshold?: number;
+  /** Smallest σ per feature, as a fraction of |μ| (plus 1e-9). Default 0.01. */
+  minScaleFraction?: number;
+  /** Smallest σ per feature in absolute feature units. Default 0 (see `RobustZOptions.minScale`). */
+  minScale?: number;
+}
+
+export class EwmaModel implements MlPredictor {
+  constructor(
+    readonly mean: Float64Array,
+    readonly variance: Float64Array,
+    readonly alpha: number,
+    readonly threshold: number,
+    readonly minScaleFraction: number,
+    readonly minScale: number = 0,
+  ) {
+    if (!(alpha > 0 && alpha <= 1)) throw new Error(`EwmaModel: alpha must be in (0, 1] (got ${alpha})`);
+  }
+
+  zScores(x: ArrayLike<number>): number[] {
+    return Array.from(this.mean, (m, i) => {
+      const sd = Math.max(Math.sqrt(this.variance[i]!), this.minScaleFraction * Math.abs(m) + 1e-9, this.minScale);
+      return Math.abs((x[i] ?? 0) - m) / sd;
+    });
+  }
+
+  /** Fold one observation into the running state. */
+  update(x: ArrayLike<number>): void {
+    for (let i = 0; i < this.mean.length; i++) {
+      const diff = (x[i] ?? 0) - this.mean[i]!;
+      const incr = this.alpha * diff;
+      this.mean[i] = this.mean[i]! + incr;
+      this.variance[i] = (1 - this.alpha) * (this.variance[i]! + diff * incr);
+    }
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const score = Math.max(0, ...this.zScores(x)) / this.threshold;
+    return { scores: [score], confidence: anomalyConfidence(score) };
+  }
+}
+
+/** Fit over `samples` in the given (chronological) order. */
+export function fitEwma(samples: readonly MlSample[], opts: EwmaOptions = {}): EwmaModel {
+  const d = featureDim(samples.map((s) => s.x));
+  const model = new EwmaModel(
+    Float64Array.from(samples[0]!.x),
+    new Float64Array(d),
+    opts.alpha ?? 0.3,
+    opts.threshold ?? 3,
+    opts.minScaleFraction ?? 0.01,
+    opts.minScale ?? 0,
+  );
+  for (let i = 1; i < samples.length; i++) model.update(samples[i]!.x);
+  return model;
+}

package/src/ml/classical/gbm.ts

@@ -0,0 +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;
+  }
+  // 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);
+}