@seanhogg/builderforce-memory-engine 2026.9.34 → 2026.10.1

package/src/index.ts

@@ -45,6 +45,9 @@ export {
     deltaUnusableReason,
     MAX_DELTA_B64_CHARS,
     mergeCheckpointDiffs,
+    mergeCheckpointDiffsGated,
+    DELTA_TARGET_RE,
+    mlHeadTarget,
     meanEvalLoss,
 } from './evermind/index.js';
 export type {
@@ -61,6 +64,8 @@ export type {
     DeltaLearnPayload,
     DeltaParseResult,
     MergeResult,
+    GatedMergeResult,
+    MergeGateOptions,
     EvalExample,
     EvalTokenizer,
 } from './evermind/index.js';
@@ -103,7 +108,7 @@ export type {
 } from './training/mamba1_cpu.js';
 export {
     linearForward, linearBackward, rmsNormForward, rmsNormBackward,
-    silu, siluGrad, softplus, sigmoid, RMSNORM_EPS,
+    silu, siluGrad, softplus, sigmoid, softmax, RMSNORM_EPS,
 } from './training/cpu_ops.js';
 export {
     Tensor,
@@ -372,6 +377,9 @@ export {
     DEFAULT_LIMBIC_CONFIG,
     DEFAULT_LIMBIC_SEED,
     LimbicTrainer,
+    limbicHead,
+    LIMBIC_AFFECT_TASK,
+    limbicAffectPredictor,
 } from './limbic/index.js';
 export type {
     Region,
@@ -388,6 +396,8 @@ export type {
     LimbicParam,
     LimbicSample,
     LimbicTrainOptions,
+    LimbicAffectInput,
+    LimbicAffectOutput,
 } from './limbic/index.js';
 
 export { LIMBIC_AFFECT_WGSL } from './kernels/limbic_affect.js';
@@ -396,3 +406,7 @@ export { LIMBIC_AFFECT_WGSL } from './kernels/limbic_affect.js';
 // ── Experience (demonstrations, Train Once skills, runs) ─────────────────────
 
 export * from './experience/index.js';
+
+// ── ML task catalog (non-LLM learning: registry, runner, trainer, federation) ──
+
+export * from './ml/index.js';

package/src/limbic/index.ts

@@ -54,3 +54,8 @@ export type { LimbicModelConfig, LimbicForward, LimbicParam } from "./limbic_mod
 
 export { LimbicTrainer } from "./limbic_trainer.js";
 export type { LimbicSample, LimbicTrainOptions } from "./limbic_trainer.js";
+export { limbicHead } from "./limbic_trainer.js";
+
+// The ML catalog row for the affect head (`ml/`), registered by limbic itself.
+export { LIMBIC_AFFECT_TASK, limbicAffectPredictor } from "./limbic_task.js";
+export type { LimbicAffectInput, LimbicAffectOutput } from "./limbic_task.js";

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

@@ -1,258 +1,91 @@
-/**
- * limbic_trainer.ts – LimbicTrainer: gradient-based training for the LimbicModel.
- *
- * 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.).
- *
- * 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 type { LimbicModel, LimbicParam } from "./limbic_model.js";
-
-/** One training example: an experience and the affect change it should produce. */
-export interface LimbicSample {
-  /** Experience embedding (length = model.inputDim). */
-  input: ArrayLike<number>;
-  /** Affective state at the time of the experience (length = model.stateDim). */
-  state: ArrayLike<number>;
-  /** Observed affect delta target in (-1, 1) per state dim (length = model.stateDim). */
-  deltaTarget: ArrayLike<number>;
-  /** Observed scalar reward for the experience. */
-  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;
-}
-
-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;
-}
-
-export class LimbicTrainer {
-  readonly model: LimbicModel;
-  readonly device: GPUDevice | null;
-  private _moments: AdamMoment[] | null = null;
-  private _step = 0;
-  private readonly _adamwPipeline: GPUComputePipeline | null;
-
-  constructor(model: LimbicModel, device: GPUDevice | null = null) {
-    this.model = model;
-    this.device = device;
-    this._adamwPipeline = device
-      ? createComputePipeline(device, WEIGHT_UPDATE_WGSL, "adamw_update")
-      : null;
-  }
-
-  /** 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),
-    }));
-  }
-
-  /**
-   * 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.
-   */
-  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;
-  }
-
-  /** 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();
-    }
-  }
-}
+/**
+ * limbic_trainer.ts – LimbicTrainer: gradient-based training for the LimbicModel.
+ *
+ * Trains the affect head to predict affect deltas and reward from
+ * (experience embedding, current state) pairs, using full-batch gradient
+ * 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 { 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. */
+export interface LimbicSample {
+  /** Experience embedding (length = model.inputDim). */
+  input: ArrayLike<number>;
+  /** Affective state at the time of the experience (length = model.stateDim). */
+  state: ArrayLike<number>;
+  /** Observed affect delta target in (-1, 1) per state dim (length = model.stateDim). */
+  deltaTarget: ArrayLike<number>;
+  /** Observed scalar reward for the experience. */
+  reward: number;
+}
+
+/** The limbic trainer's options are the shared head trainer's. */
+export type LimbicTrainOptions = HeadTrainOptions;
+
+/**
+ * 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 readonly _trainer: HeadTrainer<LimbicSample>;
+
+  constructor(model: LimbicModel, device: GPUDevice | null = null) {
+    this.model = model;
+    this.device = device;
+    this._trainer = new HeadTrainer(limbicHead(model), device, "LimbicTrainer");
+  }
+
+  /** Whether the optimiser step runs on the GPU. */
+  get gpuTraining(): boolean {
+    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).
+   */
+  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 {
+    return this._trainer.evaluate(samples);
+  }
+}

package/src/ml/classical/ewma.ts

@@ -0,0 +1,68 @@
+/**
+ * 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`.
+ */
+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;
+}
+
+export class EwmaModel implements MlPredictor {
+  constructor(
+    readonly mean: Float64Array,
+    readonly variance: Float64Array,
+    readonly alpha: number,
+    readonly threshold: number,
+    readonly minScaleFraction: number,
+  ) {
+    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);
+      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,
+  );
+  for (let i = 1; i < samples.length; i++) model.update(samples[i]!.x);
+  return model;
+}