@seanhogg/builderforce-memory-engine 2026.10.1 → 2026.10.2

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/training/cpu_ops.ts

@@ -1,141 +1,141 @@
-/**
- * cpu_ops.ts — the small set of exact CPU primitives the reference forward and
- * backward passes share (linear, RMSNorm, SiLU, softplus).
- *
- * Each one mirrors a WGSL kernel exactly, so a gradient computed here is the
- * gradient of the function the GPU actually evaluates. They are deliberately
- * plain loops over `Float32Array`: correctness first, and small enough that the
- * finite-difference check in `tests/backprop.test.ts` is meaningful.
- */
-
-/** Epsilon used by `rmsnorm_forward` in `ACTIVATIONS_WGSL`. */
-export const RMSNORM_EPS = 1e-6;
-
-export function sigmoid(x: number): number {
-    return 1 / (1 + Math.exp(-x));
-}
-
-/** Numerically-stable softmax over a flat array. */
-export function softmax(logits: ArrayLike<number>): Float32Array {
-    let max = -Infinity;
-    for (let i = 0; i < logits.length; i++) if (logits[i]! > max) max = logits[i]!;
-    const out = new Float32Array(logits.length);
-    let sum = 0;
-    for (let i = 0; i < logits.length; i++) {
-        out[i] = Math.exp(logits[i]! - max);
-        sum += out[i]!;
-    }
-    for (let i = 0; i < logits.length; i++) out[i] = out[i]! / sum;
-    return out;
-}
-
-/** SiLU(x) = x * sigmoid(x) — mirrors `silu_forward`. */
-export function silu(x: number): number {
-    return x / (1 + Math.exp(-x));
-}
-
-/** d/dx SiLU(x) = sigmoid(x) * (1 + x * (1 - sigmoid(x))). */
-export function siluGrad(x: number): number {
-    const s = sigmoid(x);
-    return s * (1 + x * (1 - s));
-}
-
-/** Numerically stable softplus — mirrors the kernel's `max(x,0) + log1p(exp(-|x|))`. */
-export function softplus(x: number): number {
-    return Math.max(x, 0) + Math.log1p(Math.exp(-Math.abs(x)));
-}
-
-/**
- * Y = X @ W^T + b, mirroring `linear_forward`.
- *
- * @param X   (M, K)
- * @param W   (N, K) row-major
- * @param b   (N,)
- * @param out (M, N) — written, not accumulated
- */
-export function linearForward(
-    X: Float32Array, W: Float32Array, b: Float32Array,
-    M: number, K: number, N: number, out: Float32Array,
-): void {
-    for (let r = 0; r < M; r++) {
-        const xo = r * K;
-        const yo = r * N;
-        for (let n = 0; n < N; n++) {
-            let acc = b[n]!;
-            const wo = n * K;
-            for (let k = 0; k < K; k++) acc += X[xo + k]! * W[wo + k]!;
-            out[yo + n] = acc;
-        }
-    }
-}
-
-/**
- * Backward of {@link linearForward}. `dX` is written; `dW` and `db` are
- * ACCUMULATED into (so one parameter can collect gradient from several call
- * sites without a temporary).
- */
-export function linearBackward(
-    dY: Float32Array, X: Float32Array, W: Float32Array,
-    M: number, K: number, N: number,
-    dX: Float32Array, dW: Float32Array, db: Float32Array,
-): void {
-    dX.fill(0);
-    for (let r = 0; r < M; r++) {
-        const xo = r * K;
-        const yo = r * N;
-        for (let n = 0; n < N; n++) {
-            const g = dY[yo + n]!;
-            if (g === 0) continue;
-            db[n] = db[n]! + g;
-            const wo = n * K;
-            for (let k = 0; k < K; k++) {
-                dX[xo + k] = dX[xo + k]! + g * W[wo + k]!;
-                dW[wo + k] = dW[wo + k]! + g * X[xo + k]!;
-            }
-        }
-    }
-}
-
-/**
- * RMSNorm forward — mirrors `rmsnorm_forward`:
- *   inv[r] = 1 / sqrt(mean(x[r]²) + eps);  y[r,i] = x[r,i] * inv[r] * w[i]
- */
-export function rmsNormForward(
-    x: Float32Array, w: Float32Array, M: number, D: number,
-    out: Float32Array, inv: Float32Array, eps: number = RMSNORM_EPS,
-): void {
-    for (let r = 0; r < M; r++) {
-        const base = r * D;
-        let sq = 0;
-        for (let i = 0; i < D; i++) { const v = x[base + i]!; sq += v * v; }
-        const iv = 1 / Math.sqrt(sq / D + eps);
-        inv[r] = iv;
-        for (let i = 0; i < D; i++) out[base + i] = x[base + i]! * iv * w[i]!;
-    }
-}
-
-/**
- * RMSNorm backward. `dx` and `dw` are ACCUMULATED into — `dx` in particular is
- * usually the residual path, which already carries a gradient.
- */
-export function rmsNormBackward(
-    dY: Float32Array, x: Float32Array, w: Float32Array, inv: Float32Array,
-    M: number, D: number,
-    dx: Float32Array, dw: Float32Array, _eps: number = RMSNORM_EPS,
-): void {
-    for (let r = 0; r < M; r++) {
-        const base = r * D;
-        const iv = inv[r]!;
-        let dot = 0;   // Σ_i (dY[r,i] * w[i]) * x[r,i]
-        for (let i = 0; i < D; i++) {
-            const g = dY[base + i]! * w[i]!;
-            dot += g * x[base + i]!;
-            dw[i] = dw[i]! + dY[base + i]! * x[base + i]! * iv;
-        }
-        const scale = (iv * iv * iv) / D;
-        for (let i = 0; i < D; i++) {
-            const g = dY[base + i]! * w[i]!;
-            dx[base + i] = dx[base + i]! + g * iv - scale * dot * x[base + i]!;
-        }
-    }
-}
+/**
+ * cpu_ops.ts — the small set of exact CPU primitives the reference forward and
+ * backward passes share (linear, RMSNorm, SiLU, softplus).
+ *
+ * Each one mirrors a WGSL kernel exactly, so a gradient computed here is the
+ * gradient of the function the GPU actually evaluates. They are deliberately
+ * plain loops over `Float32Array`: correctness first, and small enough that the
+ * finite-difference check in `tests/backprop.test.ts` is meaningful.
+ */
+
+/** Epsilon used by `rmsnorm_forward` in `ACTIVATIONS_WGSL`. */
+export const RMSNORM_EPS = 1e-6;
+
+export function sigmoid(x: number): number {
+    return 1 / (1 + Math.exp(-x));
+}
+
+/** Numerically-stable softmax over a flat array. */
+export function softmax(logits: ArrayLike<number>): Float32Array {
+    let max = -Infinity;
+    for (let i = 0; i < logits.length; i++) if (logits[i]! > max) max = logits[i]!;
+    const out = new Float32Array(logits.length);
+    let sum = 0;
+    for (let i = 0; i < logits.length; i++) {
+        out[i] = Math.exp(logits[i]! - max);
+        sum += out[i]!;
+    }
+    for (let i = 0; i < logits.length; i++) out[i] = out[i]! / sum;
+    return out;
+}
+
+/** SiLU(x) = x * sigmoid(x) — mirrors `silu_forward`. */
+export function silu(x: number): number {
+    return x / (1 + Math.exp(-x));
+}
+
+/** d/dx SiLU(x) = sigmoid(x) * (1 + x * (1 - sigmoid(x))). */
+export function siluGrad(x: number): number {
+    const s = sigmoid(x);
+    return s * (1 + x * (1 - s));
+}
+
+/** Numerically stable softplus — mirrors the kernel's `max(x,0) + log1p(exp(-|x|))`. */
+export function softplus(x: number): number {
+    return Math.max(x, 0) + Math.log1p(Math.exp(-Math.abs(x)));
+}
+
+/**
+ * Y = X @ W^T + b, mirroring `linear_forward`.
+ *
+ * @param X   (M, K)
+ * @param W   (N, K) row-major
+ * @param b   (N,)
+ * @param out (M, N) — written, not accumulated
+ */
+export function linearForward(
+    X: Float32Array, W: Float32Array, b: Float32Array,
+    M: number, K: number, N: number, out: Float32Array,
+): void {
+    for (let r = 0; r < M; r++) {
+        const xo = r * K;
+        const yo = r * N;
+        for (let n = 0; n < N; n++) {
+            let acc = b[n]!;
+            const wo = n * K;
+            for (let k = 0; k < K; k++) acc += X[xo + k]! * W[wo + k]!;
+            out[yo + n] = acc;
+        }
+    }
+}
+
+/**
+ * Backward of {@link linearForward}. `dX` is written; `dW` and `db` are
+ * ACCUMULATED into (so one parameter can collect gradient from several call
+ * sites without a temporary).
+ */
+export function linearBackward(
+    dY: Float32Array, X: Float32Array, W: Float32Array,
+    M: number, K: number, N: number,
+    dX: Float32Array, dW: Float32Array, db: Float32Array,
+): void {
+    dX.fill(0);
+    for (let r = 0; r < M; r++) {
+        const xo = r * K;
+        const yo = r * N;
+        for (let n = 0; n < N; n++) {
+            const g = dY[yo + n]!;
+            if (g === 0) continue;
+            db[n] = db[n]! + g;
+            const wo = n * K;
+            for (let k = 0; k < K; k++) {
+                dX[xo + k] = dX[xo + k]! + g * W[wo + k]!;
+                dW[wo + k] = dW[wo + k]! + g * X[xo + k]!;
+            }
+        }
+    }
+}
+
+/**
+ * RMSNorm forward — mirrors `rmsnorm_forward`:
+ *   inv[r] = 1 / sqrt(mean(x[r]²) + eps);  y[r,i] = x[r,i] * inv[r] * w[i]
+ */
+export function rmsNormForward(
+    x: Float32Array, w: Float32Array, M: number, D: number,
+    out: Float32Array, inv: Float32Array, eps: number = RMSNORM_EPS,
+): void {
+    for (let r = 0; r < M; r++) {
+        const base = r * D;
+        let sq = 0;
+        for (let i = 0; i < D; i++) { const v = x[base + i]!; sq += v * v; }
+        const iv = 1 / Math.sqrt(sq / D + eps);
+        inv[r] = iv;
+        for (let i = 0; i < D; i++) out[base + i] = x[base + i]! * iv * w[i]!;
+    }
+}
+
+/**
+ * RMSNorm backward. `dx` and `dw` are ACCUMULATED into — `dx` in particular is
+ * usually the residual path, which already carries a gradient.
+ */
+export function rmsNormBackward(
+    dY: Float32Array, x: Float32Array, w: Float32Array, inv: Float32Array,
+    M: number, D: number,
+    dx: Float32Array, dw: Float32Array, _eps: number = RMSNORM_EPS,
+): void {
+    for (let r = 0; r < M; r++) {
+        const base = r * D;
+        const iv = inv[r]!;
+        let dot = 0;   // Σ_i (dY[r,i] * w[i]) * x[r,i]
+        for (let i = 0; i < D; i++) {
+            const g = dY[base + i]! * w[i]!;
+            dot += g * x[base + i]!;
+            dw[i] = dw[i]! + dY[base + i]! * x[base + i]! * iv;
+        }
+        const scale = (iv * iv * iv) / D;
+        for (let i = 0; i < D; i++) {
+            const g = dY[base + i]! * w[i]!;
+            dx[base + i] = dx[base + i]! + g * iv - scale * dot * x[base + i]!;
+        }
+    }
+}