@seanhogg/builderforce-memory-engine 2026.10.1 → 2026.10.2

package/src/ml/registry.ts

@@ -1,44 +1,44 @@
-/**
- * ml/registry.ts — the ONE registry of ML tasks, keyed by task id.
- *
- * A new task is a new row, not a new module. The registry only stores and looks
- * up rows; running lives in `run.ts`, training in `train.ts`.
- */
-import { ML_TASK_ID_RE, type MlTask } from "./types.js";
-
-export class MlTaskRegistry {
-  private readonly _tasks = new Map<string, MlTask<any, any>>();
-
-  /** Register a row. Throws on a malformed id, a duplicate id, or a row with no engine. */
-  register<I, O>(task: MlTask<I, O>): MlTask<I, O> {
-    if (!ML_TASK_ID_RE.test(task.id)) throw new Error(`MlTaskRegistry: malformed task id '${task.id}'`);
-    if (this._tasks.has(task.id)) throw new Error(`MlTaskRegistry: task '${task.id}' is already registered`);
-    if (task.engines.length === 0) throw new Error(`MlTaskRegistry: task '${task.id}' lists no engine`);
-    if (task.kind === "classify" && !(task.output.labels && task.output.labels.length >= 2)) {
-      throw new Error(`MlTaskRegistry: classify task '${task.id}' needs at least two output labels`);
-    }
-    this._tasks.set(task.id, task);
-    return task;
-  }
-
-  /** The row for `id`, or undefined. */
-  get<I = unknown, O = unknown>(id: string): MlTask<I, O> | undefined {
-    return this._tasks.get(id) as MlTask<I, O> | undefined;
-  }
-
-  /** The row for `id`; throws when it is not registered. */
-  require<I = unknown, O = unknown>(id: string): MlTask<I, O> {
-    const t = this.get<I, O>(id);
-    if (!t) throw new Error(`MlTaskRegistry: unknown task '${id}'`);
-    return t;
-  }
-
-  has(id: string): boolean {
-    return this._tasks.has(id);
-  }
-
-  /** Every row, in registration order. */
-  list(): MlTask<any, any>[] {
-    return [...this._tasks.values()];
-  }
-}
+/**
+ * ml/registry.ts — the ONE registry of ML tasks, keyed by task id.
+ *
+ * A new task is a new row, not a new module. The registry only stores and looks
+ * up rows; running lives in `run.ts`, training in `train.ts`.
+ */
+import { ML_TASK_ID_RE, type MlTask } from "./types.js";
+
+export class MlTaskRegistry {
+  private readonly _tasks = new Map<string, MlTask<any, any>>();
+
+  /** Register a row. Throws on a malformed id, a duplicate id, or a row with no engine. */
+  register<I, O>(task: MlTask<I, O>): MlTask<I, O> {
+    if (!ML_TASK_ID_RE.test(task.id)) throw new Error(`MlTaskRegistry: malformed task id '${task.id}'`);
+    if (this._tasks.has(task.id)) throw new Error(`MlTaskRegistry: task '${task.id}' is already registered`);
+    if (task.engines.length === 0) throw new Error(`MlTaskRegistry: task '${task.id}' lists no engine`);
+    if (task.kind === "classify" && !(task.output.labels && task.output.labels.length >= 2)) {
+      throw new Error(`MlTaskRegistry: classify task '${task.id}' needs at least two output labels`);
+    }
+    this._tasks.set(task.id, task);
+    return task;
+  }
+
+  /** The row for `id`, or undefined. */
+  get<I = unknown, O = unknown>(id: string): MlTask<I, O> | undefined {
+    return this._tasks.get(id) as MlTask<I, O> | undefined;
+  }
+
+  /** The row for `id`; throws when it is not registered. */
+  require<I = unknown, O = unknown>(id: string): MlTask<I, O> {
+    const t = this.get<I, O>(id);
+    if (!t) throw new Error(`MlTaskRegistry: unknown task '${id}'`);
+    return t;
+  }
+
+  has(id: string): boolean {
+    return this._tasks.has(id);
+  }
+
+  /** Every row, in registration order. */
+  list(): MlTask<any, any>[] {
+    return [...this._tasks.values()];
+  }
+}

package/src/ml/run.ts

@@ -112,28 +112,54 @@ export class MlEngineUnavailableError extends Error {
     readonly taskId: string,
     readonly decision: MlDecision,
   ) {
-    super(`runMlTask(${taskId}): no engine could answer in '${decision.mode}' mode (${decision.skipped.map((s) => `${s.engine}: ${s.reason}`).join(", ") || "none allowed"})`);
+    super(
+      `runMlTask(${taskId}): no engine could answer in '${decision.mode}' mode (${
+        decision.skipped.map((s) => `${s.engine}: ${s.reason}${s.detail ? ` (${s.detail})` : ""}`).join(", ") || "none allowed"
+      })`,
+    );
     this.name = "MlEngineUnavailableError";
   }
 }
 
-/** The task's engines the mode allows, in the order the runner tries them. */
+/**
+ * The task's engines the mode allows, in the order the runner tries them. Exhaustive:
+ * a mode string outside {@link InferenceMode} (a host passing a stale or mistyped
+ * setting) throws instead of being read as `specific`.
+ */
 export function candidateEngines(task: MlTask<any, any>, mode: InferenceMode, specific?: MlEngineRef | string): MlEngineRef[] {
-  if (mode === "local-only") return task.engines.filter((e) => e.tier === "local");
-  if (mode === "hybrid") return [...task.engines.filter((e) => e.tier === "local"), ...task.engines.filter((e) => e.tier === "cloud")];
-  if (specific == null) throw new Error(`runMlTask(${task.id}): 'specific' mode needs ctx.engine`);
-  const key = typeof specific === "string" ? specific : engineKey(specific);
-  const match = task.engines.filter((e) => engineKey(e) === key);
-  if (match.length === 0) throw new Error(`runMlTask(${task.id}): engine '${key}' is not one of this task's engines`);
-  return match;
+  switch (mode) {
+    case "local-only":
+      return task.engines.filter((e) => e.tier === "local");
+    case "hybrid":
+      return [...task.engines.filter((e) => e.tier === "local"), ...task.engines.filter((e) => e.tier === "cloud")];
+    case "specific": {
+      if (specific == null) throw new Error(`runMlTask(${task.id}): 'specific' mode needs ctx.engine`);
+      const key = typeof specific === "string" ? specific : engineKey(specific);
+      const match = task.engines.filter((e) => engineKey(e) === key);
+      if (match.length === 0) throw new Error(`runMlTask(${task.id}): engine '${key}' is not one of this task's engines`);
+      return match;
+    }
+    default: {
+      const unknown: never = mode;
+      throw new Error(`runMlTask(${task.id}): unknown inference mode '${String(unknown)}'`);
+    }
+  }
 }
 
-/** Answer task `id` for `input` with the first engine the mode allows that can. */
+const errorDetail = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+/**
+ * Answer task `id` for `input` with the first engine the mode allows that can. An
+ * engine that throws (feature extraction or its own predict) is recorded as an
+ * `error` skip and the next allowed engine is tried — in Hybrid, the cloud. Throws
+ * {@link MlEngineUnavailableError}, carrying every engine's reason, only when none answers.
+ */
 export async function runMlTask<O = unknown, I = unknown>(id: string, input: I, ctx: MlRunContext): Promise<MlResult<O>> {
   const task = ctx.registry.require<I, O>(id);
   const engines = candidateEngines(task, ctx.mode, ctx.engine);
   const skipped: MlDecision["skipped"] = [];
   let features: Float32Array | null = null;
+  let featureError: unknown = null;
   let deferred: { ref: MlEngineRef; p: MlPrediction } | null = null;
 
   const finish = (ref: MlEngineRef, p: MlPrediction): MlResult<O> => {
@@ -150,8 +176,26 @@ export async function runMlTask<O = unknown, I = unknown>(id: string, input: I,
         skipped.push({ engine: key, reason: "unavailable" });
         continue;
       }
-      features ??= await extractFeatures(task.features, input, ctx.embedder);
-      const p = predictor.predict(features);
+      // Extract once; a failure (e.g. no embedder) fails every local engine alike, so
+      // it is remembered rather than retried per engine.
+      if (!features && featureError == null) {
+        try {
+          features = await extractFeatures(task.features, input, ctx.embedder);
+        } catch (error) {
+          featureError = error;
+        }
+      }
+      if (!features) {
+        skipped.push({ engine: key, reason: "error", detail: `features: ${errorDetail(featureError)}` });
+        continue;
+      }
+      let p: MlPrediction;
+      try {
+        p = predictor.predict(features);
+      } catch (error) {
+        skipped.push({ engine: key, reason: "error", detail: errorDetail(error) });
+        continue;
+      }
       const cloudLater = ctx.mode === "hybrid" && !!ctx.cloud && engines.slice(i + 1).some((e) => e.tier === "cloud");
       if (ctx.minConfidence != null && p.confidence < ctx.minConfidence && cloudLater) {
         skipped.push({ engine: key, reason: "low-confidence", detail: p.confidence.toFixed(3) });
@@ -167,7 +211,7 @@ export async function runMlTask<O = unknown, I = unknown>(id: string, input: I,
     try {
       return finish(ref, await ctx.cloud.run({ taskId: id, engine: ref, input }));
     } catch (error) {
-      skipped.push({ engine: key, reason: "error", detail: error instanceof Error ? error.message : String(error) });
+      skipped.push({ engine: key, reason: "error", detail: errorDetail(error) });
     }
   }
   // The cloud could not answer after a low-confidence local one: the local answer stands.

package/src/ml/tasks/experience.ts

@@ -7,9 +7,10 @@
 import { experienceDocuments, type ExperienceDocument } from "../../experience/corpus.js";
 import type { Episode, Run, Skill } from "../../experience/types.js";
 import { KnnModel } from "../classical/knn.js";
-import { clampRatio, logScale, type TextEmbedder } from "../features.js";
-import { MlEngineUnavailableError, runMlTask, type MlRunContext } from "../run.js";
-import type { MlTrainExample } from "../train.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 ────────────────────────────────────────────────────────
@@ -37,14 +38,20 @@ export const EXPERIENCE_QUALITY_TASK: MlTask<ExperienceQualityInput, ExperienceQ
   description: "Is this procedure worth learning from (does it run, and run well)?",
   features: {
     text: (i) => i.doc.text,
-    numeric: (i) => [logScale(i.steps, 50), logScale(i.runs, 20), clampRatio(i.succeeded, i.runs, 1), clampRatio(i.failed, i.runs, 1)],
-    numericNames: ["steps", "runs", "successRate", "failureRate"],
+    // 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" },
   ],
-  train: { minSamples: 4 },
+  // 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 }),
@@ -141,7 +148,8 @@ export interface CurationOptions {
   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.
+   * (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;
@@ -150,8 +158,24 @@ export interface CurationOptions {
   };
   /** 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 }[];
@@ -174,16 +198,24 @@ function memoEmbedder(e: TextEmbedder): TextEmbedder {
 /**
  * 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 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.
+ * 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)) {
@@ -191,24 +223,71 @@ export async function curateExperience(docs: readonly ExperienceDocument[], opts
       continue;
     }
     if (opts.quality && qctx) {
-      try {
-        const r = await runMlTask<ExperienceQuality>(EXPERIENCE_QUALITY_TASK.id, opts.quality.input(doc), qctx);
-        if (r.output.pHigh < (opts.quality.minPHigh ?? 0.5)) {
-          dropped.push({ id: doc.id, reason: "low-quality", score: r.output.pHigh });
-          continue;
+      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;
         }
-      } catch (error) {
-        if (!(error instanceof MlEngineUnavailableError)) throw error;
       }
     }
-    const x = await embedder.embed(EXPERIENCE_DEDUPE_TASK.features.text!(doc));
+    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: kept[d.nearest]!.id, score: d.similarity });
+      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/run_anomaly.ts

@@ -3,15 +3,17 @@
  * outside its normal range. Flags runs to leave out of training and to surface as
  * Insights.
  *
- * 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, so either one can flag.
+ * 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 { EwmaModel, fitEwma, type EwmaOptions } from "../classical/ewma.js";
-import { anomalyConfidence, fitRobustZ, RobustZModel, type RobustZOptions } from "../classical/robust_z.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, MlPredictor, MlSample, MlTask } from "../types.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 {
@@ -33,38 +35,32 @@ export function runAnomalyFeatures(m: RunMetrics): number[] {
   return [logScale(m.costUsd * 100, 1000), logScale(m.durationMs, 3_600_000), logScale(m.toolFailures, 50)];
 }
 
-/** Robust z over the history, combined with EWMA over its recent trend. */
-export class RunAnomalyDetector implements MlPredictor {
-  constructor(
-    readonly population: RobustZModel,
-    readonly trend: EwmaModel,
-  ) {}
+/**
+ * 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 pz = this.population.zScores(x);
-    const tz = this.trend.zScores(x);
-    return RUN_ANOMALY_METRICS.map((metric, i) => ({
-      metric,
-      population: pz[i]! / this.population.threshold,
-      trend: tz[i]! / this.trend.threshold,
-    }));
-  }
-
-  /** Fold a finished, non-anomalous run 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) };
+    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). */
-export function fitRunAnomaly(samples: readonly MlSample[], opts: { robustZ?: RobustZOptions; ewma?: EwmaOptions } = {}): RunAnomalyDetector {
-  return new RunAnomalyDetector(fitRobustZ(samples, opts.robustZ), fitEwma(samples, opts.ewma));
+/** 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> = {
@@ -72,10 +68,8 @@ export const RUN_ANOMALY_TASK: MlTask<RunMetrics, RunAnomaly> = {
   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: "robust-z" },
-    { tier: "local", engine: "classical", algorithm: "ewma" },
-  ],
+  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 }) },
 };

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> {
@@ -50,24 +51,7 @@ export interface MlTrainResult {
   holdoutLoss: number | null;
 }
 
-/**
- * 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 {