@seanhogg/builderforce-memory-engine 2026.10.1 → 2026.10.3

package/src/ml/train.ts

@@ -12,10 +12,11 @@
  */
 import { fitClassical, type ClassicalOptions } from "./classical/index.js";
 import { DenseHead } from "./dense_head.js";
+import { mlEvalLoss } from "./eval_loss.js";
 import { extractFeatureMatrix, type TextEmbedder } from "./features.js";
 import { HeadTrainer, type HeadTrainOptions } from "./head_trainer.js";
 import type { MlModelStore } from "./run.js";
-import { engineKey, type MlEngineRef, type MlPredictor, type MlSample, type MlTask, type MlTaskKind } from "./types.js";
+import { engineKey, type MlEngineRef, type MlPredictor, type MlSample, type MlTask } from "./types.js";
 
 /** One labelled example in input space. */
 export interface MlTrainExample<I> {
@@ -48,26 +49,15 @@ export interface MlTrainResult {
   /** Size of the held-out tail, and the model's loss on it (null when none was held out). */
   holdout: number;
   holdoutLoss: number | null;
+  /**
+   * Head engines: parameter elements the final fit skipped for a non-finite gradient
+   * ({@link HeadTrainer.skippedNonFinite}) — above 0, the fit diverged somewhere. 0
+   * for classical engines and task-owned fits.
+   */
+  skippedNonFinite: number;
 }
 
-/**
- * Mean loss of `predictor` on `samples` for a task of `kind` — classify: weighted
- * cross-entropy of the true class; regress: weighted ½·squared error. Null for
- * kinds without a supervised loss, or an empty set.
- */
-export function mlEvalLoss(kind: MlTaskKind, predictor: MlPredictor, samples: readonly MlSample[]): number | null {
-  if (samples.length === 0 || (kind !== "classify" && kind !== "regress")) return null;
-  let sum = 0;
-  let wSum = 0;
-  for (const s of samples) {
-    const w = s.weight ?? 1;
-    const p = predictor.predict(s.x);
-    const loss = kind === "classify" ? -Math.log(Math.max(p.scores[s.y] ?? 0, 1e-12)) : 0.5 * (p.scores[0]! - s.y) ** 2;
-    sum += w * loss;
-    wSum += w;
-  }
-  return wSum > 0 ? sum / wSum : null;
-}
+export { mlEvalLoss } from "./eval_loss.js";
 
 /** The task's first local engine the seam can train. */
 function defaultEngine(task: MlTask<any, any>): MlEngineRef {
@@ -76,9 +66,14 @@ function defaultEngine(task: MlTask<any, any>): MlEngineRef {
   return e;
 }
 
-async function fitEngine(task: MlTask<any, any>, ref: MlEngineRef, samples: MlSample[], opts: MlTrainOptions): Promise<MlPredictor> {
-  if (task.train?.fit) return task.train.fit(samples, ref);
-  if (ref.engine === "classical") return fitClassical(ref.algorithm, samples, opts.classical);
+interface FittedEngine {
+  predictor: MlPredictor;
+  skippedNonFinite: number;
+}
+
+async function fitEngine(task: MlTask<any, any>, ref: MlEngineRef, samples: MlSample[], opts: MlTrainOptions): Promise<FittedEngine> {
+  if (task.train?.fit) return { predictor: await task.train.fit(samples, ref), skippedNonFinite: 0 };
+  if (ref.engine === "classical") return { predictor: fitClassical(ref.algorithm, samples, opts.classical), skippedNonFinite: 0 };
   if (ref.engine === "head") {
     const objective = task.kind === "classify" ? "softmax" : task.kind === "regress" ? "mse" : null;
     if (!objective) throw new Error(`trainMlTask(${task.id}): a head engine trains classify or regress tasks only`);
@@ -89,8 +84,9 @@ async function fitEngine(task: MlTask<any, any>, ref: MlEngineRef, samples: MlSa
       objective,
       ...(opts.head?.seed != null ? { seed: opts.head.seed } : {}),
     });
-    await new HeadTrainer(head, opts.device ?? null, `trainMlTask(${task.id})`).train(samples, opts.head?.train);
-    return head;
+    const trainer = new HeadTrainer(head, opts.device ?? null, `trainMlTask(${task.id})`);
+    await trainer.train(samples, opts.head?.train);
+    return { predictor: head, skippedNonFinite: trainer.skippedNonFinite };
   }
   throw new Error(`trainMlTask(${task.id}): engine '${engineKey(ref)}' is not trained here`);
 }
@@ -123,14 +119,21 @@ export async function trainMlTask<I>(
   if (nHold >= 1 && samples.length - nHold >= 1) {
     const train = samples.slice(0, samples.length - nHold);
     const hold = samples.slice(samples.length - nHold);
-    const predictor = await fitEngine(task, ref, train, opts);
-    holdoutLoss = mlEvalLoss(task.kind, predictor, hold);
+    const fit = await fitEngine(task, ref, train, opts);
+    holdoutLoss = mlEvalLoss(task.kind, fit.predictor, hold);
     if (opts.refitOnAll === false) {
-      opts.models?.set(task.id, engineKey(ref), predictor);
-      return { predictor, engine: ref, samples: train.length, holdout: nHold, holdoutLoss };
+      opts.models?.set(task.id, engineKey(ref), fit.predictor);
+      return { predictor: fit.predictor, engine: ref, samples: train.length, holdout: nHold, holdoutLoss, skippedNonFinite: fit.skippedNonFinite };
     }
   }
-  const predictor = await fitEngine(task, ref, samples, opts);
-  opts.models?.set(task.id, engineKey(ref), predictor);
-  return { predictor, engine: ref, samples: samples.length, holdout: nHold >= 1 ? nHold : 0, holdoutLoss };
+  const fit = await fitEngine(task, ref, samples, opts);
+  opts.models?.set(task.id, engineKey(ref), fit.predictor);
+  return {
+    predictor: fit.predictor,
+    engine: ref,
+    samples: samples.length,
+    holdout: nHold >= 1 ? nHold : 0,
+    holdoutLoss,
+    skippedNonFinite: fit.skippedNonFinite,
+  };
 }

package/src/ml/types.ts

@@ -1,132 +1,135 @@
-/**
- * ml/types.ts — the ML task catalog contract (docs/ml-task-catalog.md §3).
- *
- * One bounded question Evermind answers without an LLM is ONE data row: how its
- * input becomes a vector, which engines may answer it (in preference order), how
- * it trains, and what its output means. Pure types — no vscode, no DOM, no network.
- */
-
-/** The shape of the question. */
-export type MlTaskKind = "classify" | "regress" | "cluster" | "anomaly" | "rank";
-
-/** Pure-TypeScript algorithms that run everywhere (`ml/classical/`). */
-export type ClassicalAlgorithm =
-  | "knn"
-  | "naive-bayes"
-  | "logistic"
-  | "linear"
-  | "kmeans"
-  | "robust-z"
-  | "ewma"
-  | "isolation-forest"
-  | "gbm-small";
-
-/** An engine that can answer a task. Cloud engines are a port the HOST supplies. */
-export type MlEngineRef =
-  | { tier: "local"; engine: "classical"; algorithm: ClassicalAlgorithm }
-  | { tier: "local"; engine: "head"; head: "mlp" | "linear" }
-  | { tier: "local"; engine: "onnx"; model: string }
-  | { tier: "cloud"; engine: "workers-ai"; model: string };
-
-/**
- * Which engines a run may use — the person's inference setting.
- *  - `local-only`: local tiers only, never the network.
- *  - `hybrid`: local first, the cloud port when no local engine can answer (or the
- *    local answer is below the caller's confidence floor).
- *  - `specific`: exactly the engine the caller names.
- */
-export type InferenceMode = "local-only" | "hybrid" | "specific";
-
-/** What an engine returns before the task decodes it. */
-export interface MlPrediction {
-  /**
-   * classify: one probability per label; regress: the predicted value(s);
-   * cluster: `[clusterId]`; anomaly: `[score]` where ≥ 1 is anomalous;
-   * rank: one score per candidate.
-   */
-  scores: number[];
-  /** Calibrated confidence in [0, 1]. */
-  confidence: number;
-}
-
-/** A fitted model that answers on a feature vector. */
-export interface MlPredictor {
-  predict(x: Float32Array): MlPrediction;
-  /** Trainable state as one flat vector — present on models that federate. */
-  exportParams?(): Float32Array;
-  /** Load a flat vector produced by {@link exportParams} (e.g. after a merge). */
-  importParams?(params: ArrayLike<number>): void;
-}
-
-/** How an input becomes a vector: an embedded text part, numeric fields, or both. */
-export interface FeatureSpec<I> {
-  /** Text to embed (needs an embedder in the run context). */
-  text?: (input: I) => string;
-  /** Numeric fields, already on a stable scale (so federated weights mean the same thing everywhere). */
-  numeric?: (input: I) => number[];
-  /** Names of the numeric fields, index-aligned — documentation and Insights labels. */
-  numericNames?: readonly string[];
-}
-
-/** One labelled training example in feature space. */
-export interface MlSample {
-  x: Float32Array;
-  /** classify: class index; regress: target value; cluster/anomaly: ignored. */
-  y: number;
-  /** Sample weight (default 1). */
-  weight?: number;
-}
-
-/** How a task trains. Absent on the task = rule-based or pre-trained only. */
-export interface TrainSpec {
-  /** Fewer labelled examples than this and the task stays untrained. */
-  minSamples: number;
-  /** Fraction held out for the eval gate (default 0.2). */
-  holdoutFraction?: number;
-  /**
-   * A task-specific fit (e.g. a composite of two classical detectors). When absent
-   * the trainer fits the engine named by the run (`ml/train.ts`).
-   */
-  fit?: (samples: readonly MlSample[], engine: MlEngineRef) => MlPredictor;
-  /** Who trains it when not `ml/train.ts` (e.g. `LimbicTrainer` for `limbic.affect`). */
-  trainedBy?: string;
-}
-
-/** What a task's answer means. */
-export interface OutputSpec<O> {
-  /** Label set for classify tasks (index-aligned with `MlPrediction.scores`). */
-  labels?: readonly string[];
-  /** Decode an engine prediction into the task's output. */
-  decode(p: MlPrediction): O;
-}
-
-/** One bounded question Evermind can answer without an LLM. DATA, not a class tree. */
-export interface MlTask<I = unknown, O = unknown> {
-  kind: MlTaskKind;
-  /** Stable id, e.g. `experience.quality`. */
-  id: string;
-  /** One line on what it answers. */
-  description: string;
-  features: FeatureSpec<I>;
-  /** In preference order; filtered by the inference mode. */
-  engines: readonly MlEngineRef[];
-  train?: TrainSpec;
-  output: OutputSpec<O>;
-}
-
-/** Task ids: lowercase dotted segments, e.g. `run.local-success`. */
-export const ML_TASK_ID_RE = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
-
-/** A stable string key for an engine ref, e.g. `local:classical:logistic`. */
-export function engineKey(ref: MlEngineRef): string {
-  switch (ref.engine) {
-    case "classical":
-      return `local:classical:${ref.algorithm}`;
-    case "head":
-      return `local:head:${ref.head}`;
-    case "onnx":
-      return `local:onnx:${ref.model}`;
-    case "workers-ai":
-      return `cloud:workers-ai:${ref.model}`;
-  }
-}
+/**
+ * ml/types.ts — the ML task catalog contract (docs/ml-task-catalog.md §3).
+ *
+ * One bounded question Evermind answers without an LLM is ONE data row: how its
+ * input becomes a vector, which engines may answer it (in preference order), how
+ * it trains, and what its output means. Pure types — no vscode, no DOM, no network.
+ * (Imports only the leaf `evermind/ml_head.ts`; evermind/ never imports ml/.)
+ */
+
+/** The shape of the question. */
+export type MlTaskKind = "classify" | "regress" | "cluster" | "anomaly" | "rank";
+
+/** Pure-TypeScript algorithms that run everywhere (`ml/classical/`). */
+export type ClassicalAlgorithm =
+  | "knn"
+  | "naive-bayes"
+  | "logistic"
+  | "linear"
+  | "kmeans"
+  | "robust-z"
+  | "ewma"
+  /** robust z + EWMA as one fitted engine (`classical/anomaly_composite.ts`). */
+  | "anomaly-composite"
+  | "isolation-forest"
+  | "gbm-small";
+
+/** An engine that can answer a task. Cloud engines are a port the HOST supplies. */
+export type MlEngineRef =
+  | { tier: "local"; engine: "classical"; algorithm: ClassicalAlgorithm }
+  | { tier: "local"; engine: "head"; head: "mlp" | "linear" }
+  | { tier: "local"; engine: "onnx"; model: string }
+  | { tier: "cloud"; engine: "workers-ai"; model: string };
+
+/**
+ * Which engines a run may use — the person's inference setting.
+ *  - `local-only`: local tiers only, never the network.
+ *  - `hybrid`: local first, the cloud port when no local engine can answer (or the
+ *    local answer is below the caller's confidence floor).
+ *  - `specific`: exactly the engine the caller names.
+ */
+export type InferenceMode = "local-only" | "hybrid" | "specific";
+
+/** What an engine returns before the task decodes it. */
+export interface MlPrediction {
+  /**
+   * classify: one probability per label; regress: the predicted value(s);
+   * cluster: `[clusterId]`; anomaly: `[score]` where ≥ 1 is anomalous;
+   * rank: one score per candidate.
+   */
+  scores: number[];
+  /** Calibrated confidence in [0, 1]. */
+  confidence: number;
+}
+
+/** A fitted model that answers on a feature vector. */
+export interface MlPredictor {
+  predict(x: Float32Array): MlPrediction;
+  /** Trainable state as one flat vector — present on models that federate. */
+  exportParams?(): Float32Array;
+  /** Load a flat vector produced by {@link exportParams} (e.g. after a merge). */
+  importParams?(params: ArrayLike<number>): void;
+}
+
+/** How an input becomes a vector: an embedded text part, numeric fields, or both. */
+export interface FeatureSpec<I> {
+  /** Text to embed (needs an embedder in the run context). */
+  text?: (input: I) => string;
+  /** Numeric fields, already on a stable scale (so federated weights mean the same thing everywhere). */
+  numeric?: (input: I) => number[];
+  /** Names of the numeric fields, index-aligned — documentation and Insights labels. */
+  numericNames?: readonly string[];
+}
+
+/** One labelled training example in feature space. */
+export interface MlSample {
+  x: Float32Array;
+  /** classify: class index; regress: target value; cluster/anomaly: ignored. */
+  y: number;
+  /** Sample weight (default 1). */
+  weight?: number;
+}
+
+/** How a task trains. Absent on the task = rule-based or pre-trained only. */
+export interface TrainSpec {
+  /** Fewer labelled examples than this and the task stays untrained. */
+  minSamples: number;
+  /** Fraction held out for the eval gate (default 0.2). */
+  holdoutFraction?: number;
+  /**
+   * A task-specific fit (e.g. a composite of two classical detectors). When absent
+   * the trainer fits the engine named by the run (`ml/train.ts`).
+   */
+  fit?: (samples: readonly MlSample[], engine: MlEngineRef) => MlPredictor;
+  /** Who trains it when not `ml/train.ts` (e.g. `LimbicTrainer` for `limbic.affect`). */
+  trainedBy?: string;
+}
+
+/** What a task's answer means. */
+export interface OutputSpec<O> {
+  /** Label set for classify tasks (index-aligned with `MlPrediction.scores`). */
+  labels?: readonly string[];
+  /** Decode an engine prediction into the task's output. */
+  decode(p: MlPrediction): O;
+}
+
+/** One bounded question Evermind can answer without an LLM. DATA, not a class tree. */
+export interface MlTask<I = unknown, O = unknown> {
+  kind: MlTaskKind;
+  /** Stable id, e.g. `experience.quality`. */
+  id: string;
+  /** One line on what it answers. */
+  description: string;
+  features: FeatureSpec<I>;
+  /** In preference order; filtered by the inference mode. */
+  engines: readonly MlEngineRef[];
+  train?: TrainSpec;
+  output: OutputSpec<O>;
+}
+
+/** Task ids: lowercase dotted segments — defined once with the artifact's head contract. */
+export { ML_TASK_ID_RE } from "../evermind/ml_head.js";
+
+/** A stable string key for an engine ref, e.g. `local:classical:logistic`. */
+export function engineKey(ref: MlEngineRef): string {
+  switch (ref.engine) {
+    case "classical":
+      return `local:classical:${ref.algorithm}`;
+    case "head":
+      return `local:head:${ref.head}`;
+    case "onnx":
+      return `local:onnx:${ref.model}`;
+    case "workers-ai":
+      return `cloud:workers-ai:${ref.model}`;
+  }
+}

package/src/optim/adamw.ts

@@ -138,20 +138,29 @@ export interface AdamWKernelStep {
   gradScale?: number;
 }
 
+/** Largest finite f32 — a moment above it would be stored as ±Inf. */
+const F32_MAX = 3.4028234663852886e38;
+
 /**
  * One AdamW step over a single parameter tensor — the exact CPU mirror of the
- * `adamw_update` entry point in `WEIGHT_UPDATE_WGSL`, including its two safety
+ * `adamw_update` entry point in `WEIGHT_UPDATE_WGSL`, including its safety
  * properties:
  *
- *   • the **NaN/Inf guard** — a non-finite step is dropped rather than written
- *     into a weight, so one bad gradient cannot permanently poison the model;
+ *   • the **non-finite gradient skip** — an element whose gradient is NaN/±Inf
+ *     (or whose new moments would overflow f32) is skipped ENTIRELY: m, v and the
+ *     weight keep their values (no decay either). Writing the moment first and
+ *     dropping only the step stored NaN in m/v, and every later step of that
+ *     element was then NaN too — silently dropped, so the weight froze forever;
+ *   • the **NaN/Inf step guard** — a non-finite step from finite moments is
+ *     dropped rather than written into a weight;
  *   • the **trust region** — `maxDelta` bounds how far a single step can move a
  *     weight, which is what keeps repeated write-through adapts reversible.
  *
  * Decoupled weight decay (`θ * (1 - lr·wd)`), matching the kernel — deliberately
  * NOT the coupled form {@link AdamW} uses for the MoE/EvermindLM trainers.
  *
- * `param`, `m` and `v` are updated in place.
+ * `param`, `m` and `v` are updated in place. Returns how many elements were skipped
+ * for a non-finite gradient (0 on a healthy step).
  */
 export function adamwUpdateInPlace(
   param: Float32Array,
@@ -159,15 +168,21 @@ export function adamwUpdateInPlace(
   m: Float32Array,
   v: Float32Array,
   hp: AdamWKernelStep,
-): void {
+): number {
   const { lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t, maxDelta } = hp;
   const gradScale = hp.gradScale ?? 1;
   const bc1 = 1 - beta1_t;
   const bc2 = 1 - beta2_t;
+  let skipped = 0;
   for (let i = 0; i < param.length; i++) {
     const g = grad[i]! * gradScale;
     const mNew = beta1 * m[i]! + (1 - beta1) * g;
     const vNew = beta2 * v[i]! + (1 - beta2) * g * g;
+    // NaN fails every comparison, so this also catches a NaN gradient.
+    if (!(Math.abs(mNew) <= F32_MAX && vNew <= F32_MAX)) {
+      skipped++;
+      continue;
+    }
     m[i] = mNew;
     v[i] = vNew;
 
@@ -177,4 +192,5 @@ export function adamwUpdateInPlace(
 
     param[i] = param[i]! * (1 - lr * weightDecay) - step;
   }
+  return skipped;
 }