@seanhogg/builderforce-memory-engine 2026.9.34 → 2026.10.2

package/src/ml/tasks/experience.ts

@@ -0,0 +1,293 @@
+/**
+ * ml/tasks/experience.ts — `experience.quality` and `experience.dedupe`, and the
+ * opt-in curation step that applies them in front of the ONE adaptation recipe
+ * (`evermind/adapt.ts`), so the private model learns from good, varied examples
+ * instead of every transcript. Curation only drops documents; it never rewrites one.
+ */
+import { experienceDocuments, type ExperienceDocument } from "../../experience/corpus.js";
+import type { Episode, Run, Skill } from "../../experience/types.js";
+import { KnnModel } from "../classical/knn.js";
+import { logScale, type TextEmbedder } from "../features.js";
+import { MlTaskRegistry } from "../registry.js";
+import { InMemoryMlModels, MlEngineUnavailableError, runMlTask, type MlRunContext } from "../run.js";
+import { trainMlTask, type MlTrainExample } from "../train.js";
+import type { MlPrediction, MlPredictor, MlTask } from "../types.js";
+
+// ── experience.quality ────────────────────────────────────────────────────────
+
+/** One learnable procedure plus the outcome fields that say how well it went. */
+export interface ExperienceQualityInput {
+  doc: ExperienceDocument;
+  /** Steps in the procedure. */
+  steps: number;
+  /** Runs of the skill (0 for an uncompiled demonstration). */
+  runs: number;
+  succeeded: number;
+  failed: number;
+}
+
+export interface ExperienceQuality {
+  label: "low" | "high";
+  /** P(high). */
+  pHigh: number;
+}
+
+export const EXPERIENCE_QUALITY_TASK: MlTask<ExperienceQualityInput, ExperienceQuality> = {
+  kind: "classify",
+  id: "experience.quality",
+  description: "Is this procedure worth learning from (does it run, and run well)?",
+  features: {
+    text: (i) => i.doc.text,
+    // No success/failure rate: the label IS `succeeded / runs >= 0.5`, so a rate
+    // feature would leak it — the model would learn the label, not the procedure.
+    numeric: (i) => [logScale(i.steps, 50), logScale(i.runs, 20)],
+    numericNames: ["steps", "runs"],
+  },
+  engines: [
+    { tier: "local", engine: "classical", algorithm: "knn" },
+    { tier: "local", engine: "classical", algorithm: "logistic" },
+  ],
+  // Below 12 labelled procedures the task stays untrained and curation keeps
+  // everything. At 12, after the 20% holdout ≈10 remain to fit, both classes can have
+  // several members, and kNN votes with k = ⌊√n⌋ = 3 neighbours rather than the whole
+  // set — with fewer, every point votes and the answer collapses to the class prior.
+  train: { minSamples: 12 },
+  output: {
+    labels: ["low", "high"],
+    decode: (p: MlPrediction) => ({ label: (p.scores[1] ?? 0) >= 0.5 ? "high" : "low", pHigh: p.scores[1] ?? 0 }),
+  },
+};
+
+/** Quality inputs for every learnable document, with run outcomes joined by skill id. */
+export function experienceQualityInputs(episodes: Episode[], skills: Skill[], runs: readonly Run[] = []): ExperienceQualityInput[] {
+  const steps = new Map<string, number>([...skills.map((s) => [s.id, s.steps.length] as const), ...episodes.map((e) => [e.id, e.steps.length] as const)]);
+  const byItem = new Map<string, { runs: number; succeeded: number; failed: number }>();
+  for (const r of runs) {
+    if (r.status === "running") continue;
+    const t = byItem.get(r.skillId) ?? { runs: 0, succeeded: 0, failed: 0 };
+    t.runs++;
+    if (r.status === "succeeded") t.succeeded++;
+    if (r.status === "failed") t.failed++;
+    byItem.set(r.skillId, t);
+  }
+  return experienceDocuments(episodes, skills).map((doc) => ({
+    doc,
+    steps: steps.get(doc.id) ?? 0,
+    ...(byItem.get(doc.id) ?? { runs: 0, succeeded: 0, failed: 0 }),
+  }));
+}
+
+/** The training label of a quality input: 1 (high) when most finished runs succeeded, 0 when not, null with no runs. */
+export function experienceQualityLabel(i: ExperienceQualityInput): number | null {
+  if (i.runs === 0) return null;
+  return i.succeeded / i.runs >= 0.5 ? 1 : 0;
+}
+
+/** Labelled examples for `experience.quality` — only the inputs that have run outcomes. */
+export function experienceQualityExamples(inputs: readonly ExperienceQualityInput[]): MlTrainExample<ExperienceQualityInput>[] {
+  return inputs.flatMap((input) => {
+    const label = experienceQualityLabel(input);
+    return label == null ? [] : [{ input, label }];
+  });
+}
+
+// ── experience.dedupe ─────────────────────────────────────────────────────────
+
+export interface ExperienceDuplicate {
+  /** Index (in keep order) of the nearest already-kept document, or -1 when none. */
+  nearest: number;
+  similarity: number;
+  duplicate: boolean;
+}
+
+/** Cosine similarity at or above which two procedures count as one. */
+export const DEFAULT_DEDUPE_THRESHOLD = 0.97;
+
+export const EXPERIENCE_DEDUPE_TASK: MlTask<ExperienceDocument, ExperienceDuplicate> = {
+  kind: "cluster",
+  id: "experience.dedupe",
+  description: "Is this procedure a near-copy of one already kept?",
+  features: { text: (d) => d.text },
+  engines: [{ tier: "local", engine: "classical", algorithm: "knn" }],
+  output: {
+    decode: (p: MlPrediction) => ({ nearest: p.scores[0] ?? -1, similarity: p.scores[1] ?? 0, duplicate: (p.scores[2] ?? 0) === 1 }),
+  },
+};
+
+/**
+ * The `experience.dedupe` predictor: a cosine nearest-neighbour index of the
+ * documents kept so far. `scores = [nearestIndex, similarity, duplicate ? 1 : 0]`.
+ */
+export class DedupeIndex implements MlPredictor {
+  private readonly _knn = new KnnModel(1, "cosine", 2);
+
+  constructor(readonly threshold: number = DEFAULT_DEDUPE_THRESHOLD) {}
+
+  get size(): number {
+    return this._knn.size;
+  }
+
+  add(x: Float32Array): void {
+    this._knn.add(x);
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const n = this._knn.nearest(x);
+    if (!n) return { scores: [-1, 0, 0], confidence: 1 };
+    const dup = n.similarity >= this.threshold;
+    return { scores: [n.index, n.similarity, dup ? 1 : 0], confidence: Math.abs(n.similarity) };
+  }
+}
+
+// ── curation (opt-in, in front of adaptAndDiff) ─────────────────────────────
+
+export interface CurationOptions {
+  /** Embeds each document once (the person's CPU Evermind: `EvermindTextEmbedder`). */
+  embedder: TextEmbedder;
+  /** Cosine similarity at or above which a document duplicates a kept one. Default {@link DEFAULT_DEDUPE_THRESHOLD}. */
+  dedupeThreshold?: number;
+  /**
+   * Quality filter through the runner. A document whose P(high) is below `minPHigh`
+   * (default 0.5) is dropped; one the runner cannot score (no trained engine) is kept,
+   * and so is an UNSCORED one (`runs === 0` — never run is unknown, not bad).
+   */
+  quality?: {
+    ctx: MlRunContext;
+    input: (doc: ExperienceDocument) => ExperienceQualityInput;
+    minPHigh?: number;
+  };
+  /** Document ids to leave out (e.g. those whose runs `run.anomaly` flagged). */
+  exclude?: ReadonlySet<string>;
+  /**
+   * Documents the model has ALREADY learned. They seed the de-duplication index, so a
+   * pending document that only repeats one of them is dropped (reported `of` that
+   * one); they are never in `kept`. Each is embedded once per call, so this is
+   * bounded — {@link curatePendingExperience} keeps the {@link CURATION_KNOWN_LIMIT}
+   * most recently learned.
+   */
+  known?: readonly ExperienceDocument[];
+}
+
+/**
+ * How many already-learned documents curation de-duplicates against: the most
+ * recently learned ones. Each costs one CPU embed per curation call, and a
+ * repeat of something learned long ago is cheap to relearn, so a recent window is the
+ * trade — 200 embeds of a small Evermind take seconds on a laptop CPU.
+ */
+export const CURATION_KNOWN_LIMIT = 200;
+
+export interface CurationResult {
+  kept: ExperienceDocument[];
+  dropped: { id: string; reason: "duplicate" | "low-quality" | "excluded"; of?: string; score?: number }[];
+}
+
+/** Memoise an embedder for one call, so curation embeds each text once. */
+function memoEmbedder(e: TextEmbedder): TextEmbedder {
+  const cache = new Map<string, Float32Array>();
+  return {
+    dimensions: e.dimensions,
+    fingerprint: e.fingerprint,
+    async embed(text: string) {
+      let v = cache.get(text);
+      if (!v) cache.set(text, (v = await e.embed(text)));
+      return v;
+    },
+  };
+}
+
+/**
+ * Curate documents before they are packed into adaptation passes: drop excluded
+ * ones, low-quality ones (when a quality filter is given), then near-duplicates of
+ * an already-learned one (`known`) or an earlier kept one. Order is preserved, and
+ * the FIRST copy wins — compiled skills come before raw demonstrations in
+ * `experienceDocuments`, so the reviewed version is the one kept.
+ */
+export async function curateExperience(docs: readonly ExperienceDocument[], opts: CurationOptions): Promise<CurationResult> {
+  const embedder = memoEmbedder(opts.embedder);
+  const index = new DedupeIndex(opts.dedupeThreshold ?? DEFAULT_DEDUPE_THRESHOLD);
+  /** Index position → document id: the known documents first, then each kept one. */
+  const indexed: string[] = [];
+  const kept: ExperienceDocument[] = [];
+  const dropped: CurationResult["dropped"] = [];
+  const qctx = opts.quality ? { ...opts.quality.ctx, embedder } : null;
+  const embedDoc = (doc: ExperienceDocument) => embedder.embed(EXPERIENCE_DEDUPE_TASK.features.text!(doc));
+
+  for (const doc of opts.known ?? []) {
+    index.add(await embedDoc(doc));
+    indexed.push(doc.id);
+  }
+
+  for (const doc of docs) {
+    if (opts.exclude?.has(doc.id)) {
+      dropped.push({ id: doc.id, reason: "excluded" });
+      continue;
+    }
+    if (opts.quality && qctx) {
+      const input = opts.quality.input(doc);
+      // Never run ⇒ no outcome to judge it by: keep it rather than let a guess drop it.
+      if (input.runs > 0) {
+        try {
+          const r = await runMlTask<ExperienceQuality>(EXPERIENCE_QUALITY_TASK.id, input, qctx);
+          if (r.output.pHigh < (opts.quality.minPHigh ?? 0.5)) {
+            dropped.push({ id: doc.id, reason: "low-quality", score: r.output.pHigh });
+            continue;
+          }
+        } catch (error) {
+          if (!(error instanceof MlEngineUnavailableError)) throw error;
+        }
+      }
+    }
+    const x = await embedDoc(doc);
+    const d = EXPERIENCE_DEDUPE_TASK.output.decode(index.predict(x));
+    if (d.duplicate) {
+      dropped.push({ id: doc.id, reason: "duplicate", of: indexed[d.nearest]!, score: d.similarity });
+      continue;
+    }
+    index.add(x);
+    indexed.push(doc.id);
+    kept.push(doc);
+  }
+  return { kept, dropped };
+}
+
+/** What {@link curatePendingExperience} reads: the experience snapshot's raw records. */
+export interface ExperienceCurationSource {
+  episodes: Episode[];
+  skills: Skill[];
+  runs: readonly Run[];
+}
+
+/**
+ * The whole curation step a host runs in front of the adaptation passes, so every
+ * host wires it the same way: train `experience.quality` on the run outcomes there
+ * are (it stays untrained below its `minSamples`, and then nothing is dropped for
+ * quality), then {@link curateExperience} the pending documents with it,
+ * de-duplicating against each other and against `known` — the already-learned
+ * documents, MOST RECENTLY LEARNED FIRST; only the first {@link CURATION_KNOWN_LIMIT}
+ * are embedded, so a host can pass its whole ledger.
+ */
+export async function curatePendingExperience(
+  pending: readonly ExperienceDocument[],
+  source: ExperienceCurationSource,
+  opts: { embedder: TextEmbedder; known?: readonly ExperienceDocument[]; dedupeThreshold?: number; minPHigh?: number },
+): Promise<CurationResult> {
+  const known = opts.known?.slice(0, CURATION_KNOWN_LIMIT);
+  const embedder = memoEmbedder(opts.embedder);
+  const inputs = experienceQualityInputs(source.episodes, source.skills, source.runs);
+  const byId = new Map(inputs.map((i) => [i.doc.id, i] as const));
+  const registry = new MlTaskRegistry();
+  registry.register(EXPERIENCE_QUALITY_TASK);
+  const models = new InMemoryMlModels();
+  await trainMlTask(EXPERIENCE_QUALITY_TASK, experienceQualityExamples(inputs), { embedder, models });
+  return curateExperience(pending, {
+    embedder,
+    ...(known ? { known } : {}),
+    ...(opts.dedupeThreshold != null ? { dedupeThreshold: opts.dedupeThreshold } : {}),
+    quality: {
+      ctx: { registry, mode: "local-only", models },
+      // A document with no joined input (not in the snapshot) counts as never run.
+      input: (doc) => byId.get(doc.id) ?? { doc, steps: 0, runs: 0, succeeded: 0, failed: 0 },
+      ...(opts.minPHigh != null ? { minPHigh: opts.minPHigh } : {}),
+    },
+  });
+}

package/src/ml/tasks/index.ts

@@ -0,0 +1,30 @@
+/**
+ * ml/tasks — the built-in catalog rows (docs/ml-task-catalog.md §4), in order.
+ * `limbic.affect` is defined by limbic/ itself; this only lists it.
+ */
+import { LIMBIC_AFFECT_TASK } from "../../limbic/limbic_task.js";
+import { MlTaskRegistry } from "../registry.js";
+import type { MlTask } from "../types.js";
+import { EXPERIENCE_DEDUPE_TASK, EXPERIENCE_QUALITY_TASK } from "./experience.js";
+import { LOCAL_SUCCESS_TASK } from "./local_success.js";
+import { RUN_ANOMALY_TASK } from "./run_anomaly.js";
+
+/** The built-in rows, in catalog order. */
+export const BUILTIN_ML_TASKS: readonly MlTask<any, any>[] = [
+  LIMBIC_AFFECT_TASK,
+  EXPERIENCE_QUALITY_TASK,
+  EXPERIENCE_DEDUPE_TASK,
+  RUN_ANOMALY_TASK,
+  LOCAL_SUCCESS_TASK,
+];
+
+/** A registry holding every built-in row (add host rows with `register`). */
+export function createMlRegistry(): MlTaskRegistry {
+  const r = new MlTaskRegistry();
+  for (const t of BUILTIN_ML_TASKS) r.register(t);
+  return r;
+}
+
+export * from "./experience.js";
+export * from "./run_anomaly.js";
+export * from "./local_success.js";

package/src/ml/tasks/local_success.ts

@@ -0,0 +1,118 @@
+/**
+ * ml/tasks/local_success.ts — `run.local-success`: will this turn succeed on the
+ * local model? Exported for the Hybrid router (Builderforce.ai), which keeps a turn
+ * local when it can and sends it to the cloud when it can't.
+ *
+ * It LEARNS FROM THE CLOUD (docs/ml-task-catalog.md §6): in Hybrid, a turn that
+ * fell back to — or was also served by — the cloud is a training label for the
+ * local predictor, alongside local outcomes. See {@link localSuccessLabel}.
+ */
+import { clampRatio, logScale } from "../features.js";
+import type { MlTrainExample } from "../train.js";
+import type { MlPrediction, MlTask } from "../types.js";
+
+/** What the router knows about a turn before it runs, plus the local model's served context. */
+export interface LocalTurnFeatures {
+  promptTokens: number;
+  /** Tokens of context (history, files, memory) the turn carries. */
+  contextTokens: number;
+  /** The local model's served context window, in tokens. */
+  servedContextTokens: number;
+  /** Tools advertised to the turn. */
+  tools: number;
+  /** Position of the turn in its conversation (0 = first). */
+  turnIndex: number;
+  attachments?: number;
+  /** Recent local success rate for this person/workload in [0, 1], when known. */
+  priorLocalSuccessRate?: number;
+  /** The turn is mostly code (edits, diffs, stack traces). */
+  codeHeavy?: boolean;
+}
+
+export const LOCAL_SUCCESS_FEATURES = [
+  "promptTokens",
+  "contextTokens",
+  "contextFill",
+  "overflows",
+  "tools",
+  "turnIndex",
+  "attachments",
+  "priorLocalSuccessRate",
+  "codeHeavy",
+] as const;
+
+/** Fixed scales — the same on every machine, so the weights federate. */
+export function localSuccessFeatures(t: LocalTurnFeatures): number[] {
+  const fill = clampRatio(t.promptTokens + t.contextTokens, t.servedContextTokens, 4);
+  return [
+    logScale(t.promptTokens, 100_000),
+    logScale(t.contextTokens, 100_000),
+    fill,
+    fill > 1 ? 1 : 0,
+    logScale(t.tools, 64),
+    logScale(t.turnIndex, 100),
+    logScale(t.attachments ?? 0, 16),
+    Math.max(0, Math.min(1, t.priorLocalSuccessRate ?? 0.5)),
+    t.codeHeavy ? 1 : 0,
+  ];
+}
+
+export interface LocalSuccess {
+  succeeds: boolean;
+  /** P(the local model succeeds). */
+  probability: number;
+}
+
+export const LOCAL_SUCCESS_TASK: MlTask<LocalTurnFeatures, LocalSuccess> = {
+  kind: "classify",
+  id: "run.local-success",
+  description: "Will this turn succeed on the local model?",
+  features: { numeric: localSuccessFeatures, numericNames: LOCAL_SUCCESS_FEATURES },
+  engines: [
+    { tier: "local", engine: "classical", algorithm: "logistic" },
+    { tier: "local", engine: "classical", algorithm: "gbm-small" },
+  ],
+  train: { minSamples: 8 },
+  output: {
+    labels: ["fails", "succeeds"],
+    decode: (p: MlPrediction) => ({ succeeds: (p.scores[1] ?? 0) >= 0.5, probability: p.scores[1] ?? 0 }),
+  },
+};
+
+export type TurnResult = "succeeded" | "failed";
+
+/** How one routed turn actually went. */
+export interface LocalSuccessOutcome {
+  turn: LocalTurnFeatures;
+  /** The local model's result, when it ran. */
+  local?: TurnResult;
+  /** The cloud's result, when it ran. */
+  cloud?: TurnResult;
+  /** The local model ran first and the turn was handed to the cloud. */
+  fellBack?: boolean;
+}
+
+/** Weight of a cloud failure on a turn the local model never tried — weak evidence the turn was hard. */
+export const CLOUD_ONLY_FAILURE_WEIGHT = 0.5;
+
+/**
+ * The training label of one outcome, or null when it says nothing about the local model.
+ *  - local ran: its result (1 succeeded / 0 failed);
+ *  - fell back to the cloud: 0 — the local model could not finish it;
+ *  - cloud only, and the cloud failed: 0 at {@link CLOUD_ONLY_FAILURE_WEIGHT};
+ *  - cloud only, and the cloud succeeded: no evidence about local → null.
+ */
+export function localSuccessLabel(o: LocalSuccessOutcome): { label: 0 | 1; weight: number } | null {
+  if (o.local) return { label: o.local === "succeeded" ? 1 : 0, weight: 1 };
+  if (o.fellBack) return { label: 0, weight: 1 };
+  if (o.cloud === "failed") return { label: 0, weight: CLOUD_ONLY_FAILURE_WEIGHT };
+  return null;
+}
+
+/** Labelled examples from routed outcomes (local AND cloud), oldest first. */
+export function localSuccessExamples(outcomes: readonly LocalSuccessOutcome[]): MlTrainExample<LocalTurnFeatures>[] {
+  return outcomes.flatMap((o) => {
+    const l = localSuccessLabel(o);
+    return l ? [{ input: o.turn, label: l.label, weight: l.weight }] : [];
+  });
+}

package/src/ml/tasks/run_anomaly.ts

@@ -0,0 +1,84 @@
+/**
+ * ml/tasks/run_anomaly.ts — `run.anomaly`: a run that cost, took or failed far
+ * outside its normal range. Flags runs to leave out of training and to surface as
+ * Insights.
+ *
+ * ONE engine, `anomaly-composite`: robust z (median/MAD over the whole history —
+ * "far from normal") and EWMA (the recent trend — "drifting away from lately"),
+ * scored as the larger of the two so either one can flag. The row lists exactly
+ * that engine, so the key it is stored under is the key the runner asks for.
+ */
+import type { Run } from "../../experience/types.js";
+import { AnomalyCompositeModel, type AnomalyCompositeOptions } from "../classical/anomaly_composite.js";
+import { fitEwma } from "../classical/ewma.js";
+import { fitRobustZ } from "../classical/robust_z.js";
+import { logScale } from "../features.js";
+import type { MlPrediction, MlSample, MlTask } from "../types.js";
+
+/** What a run cost and how it went — the host supplies cost; the rest is in the run log. */
+export interface RunMetrics {
+  costUsd: number;
+  durationMs: number;
+  toolFailures: number;
+}
+
+export interface RunAnomaly {
+  anomalous: boolean;
+  /** Normalised score: ≥ 1 is anomalous. */
+  score: number;
+}
+
+export const RUN_ANOMALY_METRICS = ["cost", "duration", "toolFailures"] as const;
+
+/** Fixed log scales (a $10 run, a one-hour run, 50 failures map to 1). */
+export function runAnomalyFeatures(m: RunMetrics): number[] {
+  return [logScale(m.costUsd * 100, 1000), logScale(m.durationMs, 3_600_000), logScale(m.toolFailures, 50)];
+}
+
+/**
+ * The smallest per-metric scale (σ) both detectors use, in the fixed log units above.
+ * A history with no tool failures has MAD = mean-AD = 0 and EWMA σ = 0, so without an
+ * absolute floor ONE failure (log1p(1)/log1p(50) ≈ 0.18) scored as a huge outlier and
+ * every run with any failure was flagged. At 0.1, one or two failures after a clean
+ * history stay normal (z ≈ 1.8 / 2.8) and three or more flag (z ≥ 3.5); on cost, 0.1
+ * is ~0.7 nats, so a constant-cost history flags a ~10× jump. (0.05 was too tight: it
+ * still flagged a single failure.)
+ */
+export const RUN_ANOMALY_MIN_SCALE = 0.1;
+
+/** The composite detector with `run.anomaly`'s metric names on its explanation. */
+export class RunAnomalyDetector extends AnomalyCompositeModel {
+  /** Which metrics are out of range, per detector (z / threshold, ≥ 1 = out of range). */
+  explain(x: ArrayLike<number>): { metric: (typeof RUN_ANOMALY_METRICS)[number]; population: number; trend: number }[] {
+    const per = this.featureScores(x);
+    return RUN_ANOMALY_METRICS.map((metric, i) => ({ metric, ...per[i]! }));
+  }
+}
+
+/** Fit both detectors on a chronological history of runs (as feature vectors), floored at {@link RUN_ANOMALY_MIN_SCALE}. */
+export function fitRunAnomaly(samples: readonly MlSample[], opts: AnomalyCompositeOptions = {}): RunAnomalyDetector {
+  return new RunAnomalyDetector(
+    fitRobustZ(samples, { ...opts.robustZ, minScale: opts.robustZ?.minScale ?? RUN_ANOMALY_MIN_SCALE }),
+    fitEwma(samples, { ...opts.ewma, minScale: opts.ewma?.minScale ?? RUN_ANOMALY_MIN_SCALE }),
+  );
+}
+
+export const RUN_ANOMALY_TASK: MlTask<RunMetrics, RunAnomaly> = {
+  kind: "anomaly",
+  id: "run.anomaly",
+  description: "Did this run cost, take or fail far outside its normal range?",
+  features: { numeric: runAnomalyFeatures, numericNames: RUN_ANOMALY_METRICS },
+  engines: [{ tier: "local", engine: "classical", algorithm: "anomaly-composite" }],
+  // The task's own fit: the same composite, with the metric floor and named explanation.
+  train: { minSamples: 5, fit: (samples) => fitRunAnomaly(samples) },
+  output: { decode: (p: MlPrediction) => ({ anomalous: (p.scores[0] ?? 0) >= 1, score: p.scores[0] ?? 0 }) },
+};
+
+/** Duration and tool-failure count of an experience run, with the host's cost. */
+export function experienceRunMetrics(run: Run, costUsd = 0): RunMetrics {
+  return {
+    costUsd,
+    durationMs: run.endedAt != null ? Math.max(0, run.endedAt - run.startedAt) : 0,
+    toolFailures: run.steps.filter((s) => s.outcome === "failed").length,
+  };
+}

package/src/ml/train.ts

@@ -0,0 +1,120 @@
+/**
+ * ml/train.ts — the ONE trainer seam for catalog tasks.
+ *
+ * Classical engines fit in closed form or by small iteration (`classical/`);
+ * head engines train a {@link DenseHead} through the shared {@link HeadTrainer}
+ * (GPU AdamW when a device is supplied, CPU AdamW otherwise). A task can name its
+ * own composite fit (`TrainSpec.fit`), or say that something else trains it
+ * (`TrainSpec.trainedBy`, e.g. `LimbicTrainer` for `limbic.affect`).
+ *
+ * Held-out loss is measured the same way everywhere ({@link mlEvalLoss}) — it is
+ * also what gates a federated merge.
+ */
+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 } from "./types.js";
+
+/** One labelled example in input space. */
+export interface MlTrainExample<I> {
+  input: I;
+  /** classify: class index; regress: target value; cluster/anomaly: ignored (use 0). */
+  label: number;
+  weight?: number;
+}
+
+export interface MlTrainOptions {
+  /** Engine to fit (default: the task's first trainable local engine). */
+  engine?: MlEngineRef;
+  embedder?: TextEmbedder;
+  device?: GPUDevice | null;
+  classical?: ClassicalOptions;
+  head?: { hiddenDim?: number; seed?: number; train?: HeadTrainOptions };
+  /** Overrides the task's `holdoutFraction`. 0 disables the held-out measurement. */
+  holdoutFraction?: number;
+  /** After measuring on the held-out tail, refit on everything. Default true. */
+  refitOnAll?: boolean;
+  /** Store the fitted predictor here under (task id, engine key). */
+  models?: MlModelStore;
+}
+
+export interface MlTrainResult {
+  predictor: MlPredictor;
+  engine: MlEngineRef;
+  /** Examples the final fit saw. */
+  samples: number;
+  /** Size of the held-out tail, and the model's loss on it (null when none was held out). */
+  holdout: number;
+  holdoutLoss: number | null;
+}
+
+export { mlEvalLoss } from "./eval_loss.js";
+
+/** The task's first local engine the seam can train. */
+function defaultEngine(task: MlTask<any, any>): MlEngineRef {
+  const e = task.engines.find((r) => r.tier === "local" && (r.engine === "classical" || r.engine === "head"));
+  if (!e) throw new Error(`trainMlTask(${task.id}): no trainable local engine`);
+  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);
+  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`);
+    const head = new DenseHead({
+      inputDim: samples[0]!.x.length,
+      hiddenDim: ref.head === "linear" ? 0 : (opts.head?.hiddenDim ?? 16),
+      outputDim: objective === "softmax" ? task.output.labels!.length : 1,
+      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;
+  }
+  throw new Error(`trainMlTask(${task.id}): engine '${engineKey(ref)}' is not trained here`);
+}
+
+/**
+ * Fit task `task` on labelled examples. Returns null when there are fewer than
+ * the task's `minSamples` (it stays untrained). Throws for a task with no train
+ * spec, or one another trainer owns.
+ */
+export async function trainMlTask<I>(
+  task: MlTask<I, any>,
+  examples: readonly MlTrainExample<I>[],
+  opts: MlTrainOptions = {},
+): Promise<MlTrainResult | null> {
+  const spec = task.train;
+  if (!spec) throw new Error(`trainMlTask(${task.id}): task is rule-based or pre-trained only`);
+  if (spec.trainedBy) throw new Error(`trainMlTask(${task.id}): trained by ${spec.trainedBy}`);
+  if (examples.length < spec.minSamples) return null;
+
+  const ref = opts.engine ?? defaultEngine(task);
+  const X = await extractFeatureMatrix(task.features, examples.map((e) => e.input), opts.embedder);
+  const samples: MlSample[] = examples.map((e, i) => ({ x: X[i]!, y: e.label, ...(e.weight != null ? { weight: e.weight } : {}) }));
+
+  // Hold out the chronological TAIL: examples arrive oldest first, and the question
+  // is always "does this generalise to what comes next".
+  const supervised = task.kind === "classify" || task.kind === "regress";
+  const frac = supervised ? (opts.holdoutFraction ?? spec.holdoutFraction ?? 0.2) : 0;
+  const nHold = Math.floor(samples.length * frac);
+  let holdoutLoss: number | null = null;
+  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);
+    if (opts.refitOnAll === false) {
+      opts.models?.set(task.id, engineKey(ref), predictor);
+      return { predictor, engine: ref, samples: train.length, holdout: nHold, holdoutLoss };
+    }
+  }
+  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 };
+}