@seanhogg/builderforce-memory-engine 2026.10.1 → 2026.10.3

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

@@ -5,11 +5,13 @@
  * 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 type { CurationRecord } from "../../experience/store.js";
+import type { CuratedOut, 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 MlModelStore, type MlRunContext } from "../run.js";
+import { trainMlTask, type MlTrainExample } from "../train.js";
 import type { MlPrediction, MlPredictor, MlTask } from "../types.js";
 
 // ── experience.quality ────────────────────────────────────────────────────────
@@ -37,14 +39,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 }),
@@ -76,6 +84,14 @@ export function experienceQualityLabel(i: ExperienceQualityInput): number | null
   return i.succeeded / i.runs >= 0.5 ? 1 : 0;
 }
 
+/**
+ * From this many finished runs, curation judges a procedure by its OBSERVED success
+ * rate (`succeeded / runs`) instead of the model: the label is then known, and better
+ * than any guess from neighbours. The model only scores procedures with 1–4 runs;
+ * never-run ones (0) are kept.
+ */
+export const QUALITY_OBSERVED_MIN_RUNS = 5;
+
 /** Labelled examples for `experience.quality` — only the inputs that have run outcomes. */
 export function experienceQualityExamples(inputs: readonly ExperienceQualityInput[]): MlTrainExample<ExperienceQualityInput>[] {
   return inputs.flatMap((input) => {
@@ -140,21 +156,72 @@ export interface CurationOptions {
   /** 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.
+   * Quality filter. A document whose P(high) is below `minPHigh` (default 0.5) is
+   * dropped. P(high) is the OBSERVED success rate once it has
+   * {@link QUALITY_OBSERVED_MIN_RUNS} finished runs; with 1–4 it is the runner's
+   * answer, and one the runner cannot score (no trained engine) is kept. An UNSCORED
+   * document (`runs === 0` — never run is unknown, not bad) is always kept.
    */
   quality?: {
     ctx: MlRunContext;
     input: (doc: ExperienceDocument) => ExperienceQualityInput;
     minPHigh?: number;
+    /**
+     * The ids of the documents the quality model was trained on, in training order. A
+     * document among them is scored LEAVE-ONE-OUT — its own example does not vote, or
+     * a kNN would count it at similarity 1. Exact for the kNN engine (the one
+     * {@link curatePendingExperience} trains); another engine answers as fitted.
+     */
+    trainedIds?: readonly string[];
   };
   /** 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;
+
+/** One document curation left out, and why. */
+export interface CurationDrop {
+  id: string;
+  reason: CuratedOut["reason"];
+  of?: string;
+  score?: number;
 }
 
 export interface CurationResult {
   kept: ExperienceDocument[];
-  dropped: { id: string; reason: "duplicate" | "low-quality" | "excluded"; of?: string; score?: number }[];
+  dropped: CurationDrop[];
+  /**
+   * Documents an EARLIER curation left out whose verdict still stands (see
+   * {@link CuratedOut}) — skipped without being embedded or judged again. Only
+   * {@link curatePendingExperience} fills it, from the snapshot's `curated` records.
+   */
+  alreadyDropped?: CurationDrop[];
+}
+
+/** A model store whose kNN for `taskId` leaves the point at `index` out of every vote. */
+function leaveOneOut(models: MlModelStore, taskId: string, index: number): MlModelStore {
+  return {
+    get: (t, e) => {
+      const p = models.get(t, e);
+      return t === taskId && p instanceof KnnModel && index < p.size ? p.excluding(index) : p;
+    },
+    set: (t, e, p) => models.set(t, e, p),
+  };
 }
 
 /** Memoise an embedder for one call, so curation embeds each text once. */
@@ -171,19 +238,47 @@ function memoEmbedder(e: TextEmbedder): TextEmbedder {
   };
 }
 
+/**
+ * P(high) of one quality input, or null when it cannot be judged (never run, or no
+ * trained engine). Observed rate from {@link QUALITY_OBSERVED_MIN_RUNS} runs; the
+ * runner's answer below that, leave-one-out when the document is training example
+ * `trainedIndex`.
+ */
+async function qualityScore(input: ExperienceQualityInput, ctx: MlRunContext, trainedIndex: number | undefined): Promise<number | null> {
+  // Never run ⇒ no outcome to judge it by: keep it rather than let a guess drop it.
+  if (input.runs <= 0) return null;
+  if (input.runs >= QUALITY_OBSERVED_MIN_RUNS) return input.succeeded / input.runs;
+  const runCtx = trainedIndex == null || !ctx.models ? ctx : { ...ctx, models: leaveOneOut(ctx.models, EXPERIENCE_QUALITY_TASK.id, trainedIndex) };
+  try {
+    return (await runMlTask<ExperienceQuality>(EXPERIENCE_QUALITY_TASK.id, input, runCtx)).output.pHigh;
+  } catch (error) {
+    if (!(error instanceof MlEngineUnavailableError)) throw error;
+    return null;
+  }
+}
+
 /**
  * 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 trainedAt = new Map((opts.quality?.trainedIds ?? []).map((id, i) => [id, i] as const));
+  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 +286,128 @@ 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;
-        }
-      } catch (error) {
-        if (!(error instanceof MlEngineUnavailableError)) throw error;
+      const pHigh = await qualityScore(opts.quality.input(doc), qctx, trainedAt.get(doc.id));
+      if (pHigh != null && pHigh < (opts.quality.minPHigh ?? 0.5)) {
+        dropped.push({ id: doc.id, reason: "low-quality", score: pHigh });
+        continue;
       }
     }
-    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[];
+  /** Earlier curations' verdicts (the snapshot's `curated`); a standing one is skipped. */
+  curated?: Readonly<Record<string, CuratedOut>>;
+}
+
+/**
+ * Whether an earlier `curated_out` verdict still stands (see {@link CuratedOut}): a
+ * duplicate while what it repeats is learned (in `learnedIds`), a low-quality one
+ * while its finished-run count is unchanged. An exclusion is always reconsidered.
+ */
+export function curationStands(verdict: CuratedOut | undefined, finishedRuns: number, learnedIds: ReadonlySet<string>): boolean {
+  if (!verdict || verdict.status !== "curated_out") return false;
+  if (verdict.reason === "duplicate") return verdict.of != null && learnedIds.has(verdict.of);
+  if (verdict.reason === "low-quality") return verdict.runs === finishedRuns;
+  return false;
+}
+
+/**
+ * The whole curation step a host runs in front of the adaptation passes, so every
+ * host wires it the same way:
+ *
+ *   1. skip each pending document whose earlier `curated_out` verdict still stands
+ *      ({@link curationStands}) — reported in `alreadyDropped`, never re-embedded;
+ *   2. train `experience.quality` on the run outcomes of at most
+ *      {@link CURATION_KNOWN_LIMIT} scored procedures — the pending ones, then the
+ *      learned ones most recently learned first (it stays untrained below its
+ *      `minSamples`, and then only the observed-rate rule drops for quality);
+ *   3. {@link curateExperience} the rest with it — leave-one-out for a document in
+ *      that training set — 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));
+  // A document with no joined input (not in the snapshot) counts as never run.
+  const inputOf = (doc: ExperienceDocument): ExperienceQualityInput => byId.get(doc.id) ?? { doc, steps: 0, runs: 0, succeeded: 0, failed: 0 };
+
+  const learnedIds = new Set((opts.known ?? []).map((d) => d.id));
+  const alreadyDropped: CurationDrop[] = [];
+  const toCurate: ExperienceDocument[] = [];
+  for (const doc of pending) {
+    const verdict = source.curated?.[doc.id];
+    if (verdict && curationStands(verdict, inputOf(doc).runs, learnedIds)) {
+      alreadyDropped.push({ id: doc.id, reason: verdict.reason, ...(verdict.of != null ? { of: verdict.of } : {}), ...(verdict.score != null ? { score: verdict.score } : {}) });
+    } else toCurate.push(doc);
+  }
+
+  // The bounded training set: newest first (pending, then most recently learned),
+  // scored only, then reversed — trainMlTask holds out the chronological tail.
+  const recentFirst = [...pending, ...(opts.known ?? [])]
+    .map((d) => byId.get(d.id))
+    .filter((i): i is ExperienceQualityInput => i != null && experienceQualityLabel(i) != null)
+    .slice(0, CURATION_KNOWN_LIMIT);
+  const train = experienceQualityExamples(recentFirst.reverse());
+
+  const registry = new MlTaskRegistry();
+  registry.register(EXPERIENCE_QUALITY_TASK);
+  const models = new InMemoryMlModels();
+  const fitted = await trainMlTask(EXPERIENCE_QUALITY_TASK, train, { embedder, models });
+  const r = await curateExperience(toCurate, {
+    embedder,
+    ...(known ? { known } : {}),
+    ...(opts.dedupeThreshold != null ? { dedupeThreshold: opts.dedupeThreshold } : {}),
+    quality: {
+      ctx: { registry, mode: "local-only", models },
+      input: inputOf,
+      ...(opts.minPHigh != null ? { minPHigh: opts.minPHigh } : {}),
+      // The refit on all examples keeps their order, so kNN point i is train[i].
+      ...(fitted ? { trainedIds: train.map((e) => e.input.doc.id) } : {}),
+    },
+  });
+  return { ...r, alreadyDropped };
+}
+
+/**
+ * The `curated_out` records a host persists (`ExperienceStore.recordCuration`) for one
+ * curation result: each dropped document with its verdict and finished-run count, and
+ * the kept ids (whose earlier verdicts clear).
+ */
+export function curationRecords(result: CurationResult, source: Pick<ExperienceCurationSource, "runs">, at: number): CurationRecord {
+  const finished = new Map<string, number>();
+  for (const run of source.runs) if (run.status !== "running") finished.set(run.skillId, (finished.get(run.skillId) ?? 0) + 1);
+  const dropped: Record<string, CuratedOut> = {};
+  for (const d of result.dropped) {
+    dropped[d.id] = {
+      status: "curated_out",
+      reason: d.reason,
+      ...(d.of != null ? { of: d.of } : {}),
+      ...(d.score != null ? { score: d.score } : {}),
+      runs: finished.get(d.id) ?? 0,
+      at,
+    };
+  }
+  return { dropped, kept: result.kept.map((d) => d.id) };
+}

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 {
@@ -28,43 +30,68 @@ export interface RunAnomaly {
 
 export const RUN_ANOMALY_METRICS = ["cost", "duration", "toolFailures"] as const;
 
+/** The fixed log references: cost in cents ($10), duration in ms (one hour), tool failures (50). */
+const COST_REF_CENTS = 1000;
+const DURATION_REF_MS = 3_600_000;
+const FAILURES_REF = 50;
+
 /** 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)];
+  return [
+    logScale(m.costUsd * 100, COST_REF_CENTS),
+    logScale(m.durationMs, DURATION_REF_MS),
+    logScale(m.toolFailures, FAILURES_REF),
+  ];
 }
 
-/** 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 multiplicative jump in cost or duration that flags against a constant history.
+ * A constant history has MAD = mean-AD = 0 and EWMA σ = 0, so the floor below IS the
+ * scale both detectors divide by.
+ */
+export const RUN_ANOMALY_FLAG_RATIO = 3;
+
+/**
+ * The smallest per-metric scale (σ) both detectors use, in the fixed log units above —
+ * ONE PER METRIC, because each metric is divided by a different reference: a feature
+ * unit is log1p(ref) nats, i.e. log1p(1000) ≈ 6.909 nats for cost but log1p(3.6e6) ≈
+ * 15.096 nats for duration. One scalar floor (it was 0.1) therefore meant ~0.69 nats
+ * (2×) on cost but ~1.51 nats (4.5×) on duration, and a 10 s → 15 min run (4.5 nats,
+ * z ≈ 3.0) slipped under EWMA's 3.
+ *
+ * Derivation, cost and duration: for values well above 1, a k× jump moves log1p by
+ * ≈ ln k nats = ln k / log1p(ref) feature units. The composite flags at the smaller of
+ * the two thresholds (EWMA 3; robust z is 3.5), so the floor that flags a 3× jump is
+ *   floor = ln 3 / (3 · log1p(ref))
+ *   cost:     1.0986 / (3 · 6.9088)  ≈ 0.0530   (robust z alone flags from ≈ 3.6×)
+ *   duration: 1.0986 / (3 · 15.0964) ≈ 0.0243   (robust z alone flags from ≈ 3.6×)
+ * A 1.5× wobble (0.405 nats) scores z ≈ 1.1 on either — normal.
+ *
+ * Tool failures keep the absolute 0.1: from a clean history one or two failures
+ * (log1p(1|2)/log1p(50) ≈ 0.18 | 0.28) stay normal (z ≈ 1.8 / 2.8) and three or more
+ * (≈ 0.35) flag. (0.05 was too tight: it flagged a single failure.)
+ */
+export const RUN_ANOMALY_MIN_SCALE: readonly number[] = [
+  Math.log(RUN_ANOMALY_FLAG_RATIO) / (3 * Math.log1p(COST_REF_CENTS)),
+  Math.log(RUN_ANOMALY_FLAG_RATIO) / (3 * Math.log1p(DURATION_REF_MS)),
+  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 per metric 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 +99,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 }) },
 };