@seanhogg/builderforce-memory-engine 2026.9.33 → 2026.10.1

package/dist/ml/head_trainer.js

@@ -0,0 +1,182 @@
+/**
+ * ml/head_trainer.ts — HeadTrainer: the ONE gradient trainer for a small head over
+ * an embedding (extracted from the limbic affect trainer, which is now a thin
+ * registration over it).
+ *
+ * Full-batch gradient descent with AdamW. When a GPUDevice is supplied the
+ * optimiser step runs on the GPU via the shared WEIGHT_UPDATE_WGSL kernel; with
+ * no device it uses a numerically-equivalent CPU AdamW, so training works
+ * everywhere (CI, Node without @webgpu/node, a laptop with no GPU).
+ *
+ * The head owns its forward/backward and its loss (MSE for regression, BCE /
+ * softmax cross-entropy for classification); this file owns only the loop:
+ * zero → accumulate per sample → average → clip → AdamW step.
+ */
+import { createUniformBuffer, createStorageBuffer, createComputePipeline, createBindGroup, dispatchKernel, readBuffer, cdiv, } from "../utils/gpu_utils.js";
+import { WEIGHT_UPDATE_WGSL } from "../kernels/weight_update.js";
+function packAdamParams(numElements, lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t) {
+    const buf = new ArrayBuffer(32);
+    new Uint32Array(buf, 0, 1).set([numElements]);
+    new Float32Array(buf, 4, 7).set([lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t]);
+    return buf;
+}
+export class HeadTrainer {
+    label;
+    head;
+    device;
+    _moments = null;
+    _step = 0;
+    _adamwPipeline;
+    constructor(head, device = null, 
+    /** Name used in error messages (the registration that owns this trainer). */
+    label = "HeadTrainer") {
+        this.label = label;
+        this.head = head;
+        this.device = device;
+        this._adamwPipeline = device
+            ? createComputePipeline(device, WEIGHT_UPDATE_WGSL, "adamw_update")
+            : null;
+    }
+    /** Whether the optimiser step runs on the GPU. */
+    get gpuTraining() {
+        return this.device != null && this._adamwPipeline != null;
+    }
+    _initMoments() {
+        if (this._moments)
+            return;
+        this._moments = this.head.parameters().map((p) => ({
+            m: new Float32Array(p.numel),
+            v: new Float32Array(p.numel),
+        }));
+    }
+    /**
+     * Train on `samples` for `epochs` passes; returns the per-epoch mean loss.
+     * Full-batch: grads accumulate over every sample, are averaged, clipped, then
+     * applied once per epoch.
+     */
+    async train(samples, opts = {}) {
+        if (samples.length === 0)
+            throw new Error(`${this.label}.train: no samples`);
+        const { learningRate = 0.05, epochs = 50, weightDecay = 0.0, beta1 = 0.9, beta2 = 0.999, eps = 1e-8, maxGradNorm = 1.0, onEpochEnd = null, } = opts;
+        this._initMoments();
+        const losses = [];
+        for (let epoch = 0; epoch < epochs; epoch++) {
+            this.head.zeroGrad();
+            let epochLoss = 0;
+            for (const s of samples)
+                epochLoss += this.head.accumulate(s);
+            const grads = this.head.gradients();
+            const invN = 1 / samples.length;
+            for (const g of grads) {
+                for (let i = 0; i < g.data.length; i++)
+                    g.data[i] *= invN;
+            }
+            const gradNorm = clipGradients(grads, maxGradNorm);
+            this._step++;
+            const beta1_t = Math.pow(beta1, this._step);
+            const beta2_t = Math.pow(beta2, this._step);
+            const hp = { learningRate, weightDecay, beta1, beta2, eps, beta1_t, beta2_t };
+            if (this.gpuTraining) {
+                await this._adamwStepGpu(grads, hp);
+            }
+            else {
+                this._adamwStepCpu(grads, hp);
+            }
+            const avg = epochLoss / samples.length;
+            losses.push(avg);
+            if (onEpochEnd)
+                onEpochEnd(epoch + 1, avg, gradNorm);
+        }
+        return losses;
+    }
+    /** Mean loss over samples (no weight update). 0 for an empty set. */
+    evaluate(samples) {
+        if (samples.length === 0)
+            return 0;
+        let total = 0;
+        for (const s of samples)
+            total += this.head.loss(s);
+        return total / samples.length;
+    }
+    _adamwStepCpu(grads, hp) {
+        const params = this.head.parameters();
+        const { learningRate: lr, weightDecay: wd, beta1, beta2, eps, beta1_t, beta2_t } = hp;
+        for (let pi = 0; pi < params.length; pi++) {
+            const p = params[pi].data;
+            const g = grads[pi].data;
+            const mom = this._moments[pi];
+            for (let i = 0; i < p.length; i++) {
+                const gi = g[i];
+                mom.m[i] = beta1 * mom.m[i] + (1 - beta1) * gi;
+                mom.v[i] = beta2 * mom.v[i] + (1 - beta2) * gi * gi;
+                const mHat = mom.m[i] / (1 - beta1_t);
+                const vHat = mom.v[i] / (1 - beta2_t);
+                p[i] = p[i] * (1 - lr * wd) - (lr * mHat) / (Math.sqrt(vHat) + eps);
+            }
+        }
+    }
+    /** AdamW on the GPU via the shared WEIGHT_UPDATE_WGSL kernel. Awaited per step. */
+    async _adamwStepGpu(grads, hp) {
+        const device = this.device;
+        const pipeline = this._adamwPipeline;
+        const params = this.head.parameters();
+        const { learningRate: lr, weightDecay: wd, beta1, beta2, eps, beta1_t, beta2_t } = hp;
+        for (let pi = 0; pi < params.length; pi++) {
+            const p = params[pi];
+            const mom = this._moments[pi];
+            const paramBuf = createStorageBuffer(device, p.data, true);
+            const gradBuf = createStorageBuffer(device, grads[pi].data, false);
+            const mBuf = createStorageBuffer(device, mom.m, true);
+            const vBuf = createStorageBuffer(device, mom.v, true);
+            const uni = createUniformBuffer(device, packAdamParams(p.numel, lr, beta1, beta2, eps, wd, beta1_t, beta2_t));
+            const bg = createBindGroup(device, pipeline, [uni, paramBuf, gradBuf, mBuf, vBuf]);
+            dispatchKernel(device, pipeline, bg, [cdiv(p.numel, 256), 1, 1]);
+            p.data.set((await readBuffer(device, paramBuf, p.numel * 4)).subarray(0, p.numel));
+            mom.m.set((await readBuffer(device, mBuf, p.numel * 4)).subarray(0, p.numel));
+            mom.v.set((await readBuffer(device, vBuf, p.numel * 4)).subarray(0, p.numel));
+            paramBuf.destroy();
+            gradBuf.destroy();
+            mBuf.destroy();
+            vBuf.destroy();
+            uni.destroy();
+        }
+    }
+}
+/** Clip grads to `maxNorm` in place; returns the PRE-clip L2 norm (the signal). */
+function clipGradients(grads, maxNorm) {
+    let normSq = 0;
+    for (const g of grads)
+        for (let i = 0; i < g.data.length; i++)
+            normSq += g.data[i] * g.data[i];
+    const norm = Math.sqrt(normSq);
+    if (norm > maxNorm && norm > 0) {
+        const scale = maxNorm / norm;
+        for (const g of grads)
+            for (let i = 0; i < g.data.length; i++)
+                g.data[i] *= scale;
+    }
+    return norm;
+}
+/** Concatenate a head's parameters into one flat vector (the federation unit). */
+export function flattenParams(params) {
+    const out = new Float32Array(params.reduce((n, p) => n + p.numel, 0));
+    let o = 0;
+    for (const p of params) {
+        out.set(p.data, o);
+        o += p.numel;
+    }
+    return out;
+}
+/** Write a flat vector back into a head's parameters (inverse of {@link flattenParams}). */
+export function assignParams(params, flat) {
+    const total = params.reduce((n, p) => n + p.numel, 0);
+    if (flat.length !== total)
+        throw new Error(`assignParams: expected ${total} values, got ${flat.length}`);
+    let o = 0;
+    for (const p of params) {
+        for (let i = 0; i < p.numel; i++)
+            p.data[i] = flat[o + i];
+        o += p.numel;
+    }
+}
+//# sourceMappingURL=head_trainer.js.map

package/dist/ml/head_trainer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"head_trainer.js","sourceRoot":"","sources":["../../src/ml/head_trainer.ts"],"names":[],"mappings":"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"}

package/dist/ml/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ml — the ML task catalog (docs/ml-task-catalog.md): small, purpose-built models
+ * for bounded questions, answered on the person's own machine without a GPU or an
+ * LLM call. ONE registry, ONE runner, ONE trainer seam; trained heads federate on
+ * the existing delta wire. Pure and portable: no vscode, no DOM, no network.
+ */
+export type { MlTask, MlTaskKind, MlEngineRef, ClassicalAlgorithm, InferenceMode, MlPrediction, MlPredictor, FeatureSpec, MlSample, TrainSpec, OutputSpec, } from "./types.js";
+export { engineKey, ML_TASK_ID_RE } from "./types.js";
+export { MlTaskRegistry } from "./registry.js";
+export { runMlTask, candidateEngines, InMemoryMlModels, MlDecisionLog, MlEngineUnavailableError, } from "./run.js";
+export type { MlRunContext, MlResult, MlModelStore, MlCloudPort, MlDecision, MlDecisionSink, MlSkipReason } from "./run.js";
+export { trainMlTask, mlEvalLoss } from "./train.js";
+export type { MlTrainExample, MlTrainOptions, MlTrainResult } from "./train.js";
+export { HeadTrainer, flattenParams, assignParams } from "./head_trainer.js";
+export type { HeadParam, TrainableHead, HeadTrainOptions } from "./head_trainer.js";
+export { DenseHead } from "./dense_head.js";
+export type { DenseHeadConfig } from "./dense_head.js";
+export { extractFeatures, extractFeatureMatrix, logScale, clampRatio } from "./features.js";
+export * from "./classical/index.js";
+export { headCheckpoint, headParams, mlHeadEntry, mlHeadParams, mlHeadUnusableReason, packageMlHead, withPackageMlHead, buildMlHeadDelta, mergeMlHeadDeltas, } from "./federate.js";
+export type { EvermindMlHead, MlHeadMergeOutcome } from "./federate.js";
+export * from "./tasks/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/ml/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ml/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EACV,MAAM,EACN,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,WAAW,EACX,WAAW,EACX,QAAQ,EACR,SAAS,EACT,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE5H,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC7E,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE5F,cAAc,sBAAsB,CAAC;AAErC,OAAO,EACL,cAAc,EACd,UAAU,EACV,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExE,cAAc,kBAAkB,CAAC"}

package/dist/ml/index.js

@@ -0,0 +1,11 @@
+export { engineKey, ML_TASK_ID_RE } from "./types.js";
+export { MlTaskRegistry } from "./registry.js";
+export { runMlTask, candidateEngines, InMemoryMlModels, MlDecisionLog, MlEngineUnavailableError, } from "./run.js";
+export { trainMlTask, mlEvalLoss } from "./train.js";
+export { HeadTrainer, flattenParams, assignParams } from "./head_trainer.js";
+export { DenseHead } from "./dense_head.js";
+export { extractFeatures, extractFeatureMatrix, logScale, clampRatio } from "./features.js";
+export * from "./classical/index.js";
+export { headCheckpoint, headParams, mlHeadEntry, mlHeadParams, mlHeadUnusableReason, packageMlHead, withPackageMlHead, buildMlHeadDelta, mergeMlHeadDeltas, } from "./federate.js";
+export * from "./tasks/index.js";
+//# sourceMappingURL=index.js.map

package/dist/ml/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ml/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE5F,cAAc,sBAAsB,CAAC;AAErC,OAAO,EACL,cAAc,EACd,UAAU,EACV,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAGvB,cAAc,kBAAkB,CAAC"}

package/dist/ml/registry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { type MlTask } from "./types.js";
+export declare class MlTaskRegistry {
+    private readonly _tasks;
+    /** 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>;
+    /** The row for `id`, or undefined. */
+    get<I = unknown, O = unknown>(id: string): MlTask<I, O> | undefined;
+    /** The row for `id`; throws when it is not registered. */
+    require<I = unknown, O = unknown>(id: string): MlTask<I, O>;
+    has(id: string): boolean;
+    /** Every row, in registration order. */
+    list(): MlTask<any, any>[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/ml/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/ml/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAExD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D,yFAAyF;IACzF,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAWhD,sCAAsC;IACtC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS;IAInE,0DAA0D;IAC1D,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAM3D,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,wCAAwC;IACxC,IAAI,IAAI,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE;CAG3B"}

package/dist/ml/registry.js

@@ -0,0 +1,43 @@
+/**
+ * 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 } from "./types.js";
+export class MlTaskRegistry {
+    _tasks = new Map();
+    /** Register a row. Throws on a malformed id, a duplicate id, or a row with no engine. */
+    register(task) {
+        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(id) {
+        return this._tasks.get(id);
+    }
+    /** The row for `id`; throws when it is not registered. */
+    require(id) {
+        const t = this.get(id);
+        if (!t)
+            throw new Error(`MlTaskRegistry: unknown task '${id}'`);
+        return t;
+    }
+    has(id) {
+        return this._tasks.has(id);
+    }
+    /** Every row, in registration order. */
+    list() {
+        return [...this._tasks.values()];
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/ml/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/ml/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAe,MAAM,YAAY,CAAC;AAExD,MAAM,OAAO,cAAc;IACR,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IAE9D,yFAAyF;IACzF,QAAQ,CAAO,IAAkB;QAC/B,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACpG,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,CAAC,EAAE,yBAAyB,CAAC,CAAC;QACzG,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC;QACpG,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC;YACxF,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,CAAC,EAAE,oCAAoC,CAAC,CAAC;QACjG,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,sCAAsC;IACtC,GAAG,CAA2B,EAAU;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAA6B,CAAC;IACzD,CAAC;IAED,0DAA0D;IAC1D,OAAO,CAA2B,EAAU;QAC1C,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAO,EAAE,CAAC,CAAC;QAC7B,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,EAAE,GAAG,CAAC,CAAC;QAChE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IAED,wCAAwC;IACxC,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACnC,CAAC;CACF"}

package/dist/ml/run.d.ts

@@ -0,0 +1,94 @@
+/**
+ * ml/run.ts — the ONE runner: `runMlTask(id, input, ctx)`.
+ *
+ * Picks the first engine the inference mode allows that can answer (Local only:
+ * local tiers; Hybrid: local first, then the host's cloud port; Specific: exactly
+ * the named engine), returns `{ output, confidence, engine }`, and records the
+ * decision so routing can be evaluated later. The cloud is a PORT the host
+ * supplies — nothing here touches the network.
+ */
+import { type TextEmbedder } from "./features.js";
+import type { MlTaskRegistry } from "./registry.js";
+import { type InferenceMode, type MlEngineRef, type MlPrediction, type MlPredictor, type MlTask } from "./types.js";
+/** Fitted local models, per (task id, engine key). */
+export interface MlModelStore {
+    get(taskId: string, engine: string): MlPredictor | undefined;
+    set(taskId: string, engine: string, predictor: MlPredictor): void;
+}
+/** The plain in-process store. */
+export declare class InMemoryMlModels implements MlModelStore {
+    private readonly _m;
+    get(taskId: string, engine: string): MlPredictor | undefined;
+    set(taskId: string, engine: string, predictor: MlPredictor): void;
+}
+/** A cloud engine, supplied by the host (Builderforce.ai passes its gateway client). */
+export interface MlCloudPort {
+    run(request: {
+        taskId: string;
+        engine: MlEngineRef;
+        input: unknown;
+    }): Promise<MlPrediction>;
+}
+/** Why the runner moved past an engine. */
+export type MlSkipReason = "unavailable" | "low-confidence" | "error";
+/** One routing decision, recorded for eval. */
+export interface MlDecision {
+    taskId: string;
+    mode: InferenceMode;
+    /** The engine that answered (key), or null when none could. */
+    engine: string | null;
+    tier: "local" | "cloud" | null;
+    confidence: number | null;
+    /** Engines passed over before the answer, with why. */
+    skipped: {
+        engine: string;
+        reason: MlSkipReason;
+        detail?: string;
+    }[];
+}
+export interface MlDecisionSink {
+    record(decision: MlDecision): void;
+}
+/** A bounded in-memory decision log with a per-task summary. */
+export declare class MlDecisionLog implements MlDecisionSink {
+    readonly capacity: number;
+    private readonly _d;
+    constructor(capacity?: number);
+    record(decision: MlDecision): void;
+    list(): readonly MlDecision[];
+    /** Per task: how many runs, which engines answered, mean confidence, unanswered count. */
+    summary(): Record<string, {
+        runs: number;
+        byEngine: Record<string, number>;
+        unanswered: number;
+        meanConfidence: number | null;
+    }>;
+}
+export interface MlRunContext {
+    registry: MlTaskRegistry;
+    mode: InferenceMode;
+    /** For `specific`: the engine (ref or key) to use. */
+    engine?: MlEngineRef | string;
+    models?: MlModelStore;
+    embedder?: TextEmbedder;
+    cloud?: MlCloudPort;
+    /** Hybrid only: a local answer below this confidence defers to the cloud when it can answer. */
+    minConfidence?: number;
+    decisions?: MlDecisionSink;
+}
+export interface MlResult<O> {
+    output: O;
+    confidence: number;
+    engine: MlEngineRef;
+}
+/** No engine allowed by the mode could answer. */
+export declare class MlEngineUnavailableError extends Error {
+    readonly taskId: string;
+    readonly decision: MlDecision;
+    constructor(taskId: string, decision: MlDecision);
+}
+/** The task's engines the mode allows, in the order the runner tries them. */
+export declare function candidateEngines(task: MlTask<any, any>, mode: InferenceMode, specific?: MlEngineRef | string): MlEngineRef[];
+/** Answer task `id` for `input` with the first engine the mode allows that can. */
+export declare function runMlTask<O = unknown, I = unknown>(id: string, input: I, ctx: MlRunContext): Promise<MlResult<O>>;
+//# sourceMappingURL=run.d.ts.map

package/dist/ml/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/ml/run.ts"],"names":[],"mappings":"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"}

package/dist/ml/run.js

@@ -0,0 +1,130 @@
+/**
+ * ml/run.ts — the ONE runner: `runMlTask(id, input, ctx)`.
+ *
+ * Picks the first engine the inference mode allows that can answer (Local only:
+ * local tiers; Hybrid: local first, then the host's cloud port; Specific: exactly
+ * the named engine), returns `{ output, confidence, engine }`, and records the
+ * decision so routing can be evaluated later. The cloud is a PORT the host
+ * supplies — nothing here touches the network.
+ */
+import { extractFeatures } from "./features.js";
+import { engineKey } from "./types.js";
+/** The plain in-process store. */
+export class InMemoryMlModels {
+    _m = new Map();
+    get(taskId, engine) {
+        return this._m.get(`${taskId}|${engine}`);
+    }
+    set(taskId, engine, predictor) {
+        this._m.set(`${taskId}|${engine}`, predictor);
+    }
+}
+/** A bounded in-memory decision log with a per-task summary. */
+export class MlDecisionLog {
+    capacity;
+    _d = [];
+    constructor(capacity = 500) {
+        this.capacity = capacity;
+    }
+    record(decision) {
+        this._d.push(decision);
+        if (this._d.length > this.capacity)
+            this._d.splice(0, this._d.length - this.capacity);
+    }
+    list() {
+        return this._d;
+    }
+    /** Per task: how many runs, which engines answered, mean confidence, unanswered count. */
+    summary() {
+        const out = {};
+        const sums = {};
+        for (const d of this._d) {
+            const t = (out[d.taskId] ??= { runs: 0, byEngine: {}, unanswered: 0, meanConfidence: null });
+            t.runs++;
+            if (d.engine == null) {
+                t.unanswered++;
+                continue;
+            }
+            t.byEngine[d.engine] = (t.byEngine[d.engine] ?? 0) + 1;
+            const c = (sums[d.taskId] ??= { s: 0, n: 0 });
+            c.s += d.confidence ?? 0;
+            c.n++;
+            t.meanConfidence = c.s / c.n;
+        }
+        return out;
+    }
+}
+/** No engine allowed by the mode could answer. */
+export class MlEngineUnavailableError extends Error {
+    taskId;
+    decision;
+    constructor(taskId, decision) {
+        super(`runMlTask(${taskId}): no engine could answer in '${decision.mode}' mode (${decision.skipped.map((s) => `${s.engine}: ${s.reason}`).join(", ") || "none allowed"})`);
+        this.taskId = taskId;
+        this.decision = decision;
+        this.name = "MlEngineUnavailableError";
+    }
+}
+/** The task's engines the mode allows, in the order the runner tries them. */
+export function candidateEngines(task, mode, specific) {
+    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;
+}
+/** Answer task `id` for `input` with the first engine the mode allows that can. */
+export async function runMlTask(id, input, ctx) {
+    const task = ctx.registry.require(id);
+    const engines = candidateEngines(task, ctx.mode, ctx.engine);
+    const skipped = [];
+    let features = null;
+    let deferred = null;
+    const finish = (ref, p) => {
+        ctx.decisions?.record({ taskId: id, mode: ctx.mode, engine: engineKey(ref), tier: ref.tier, confidence: p.confidence, skipped });
+        return { output: task.output.decode(p), confidence: p.confidence, engine: ref };
+    };
+    for (let i = 0; i < engines.length; i++) {
+        const ref = engines[i];
+        const key = engineKey(ref);
+        if (ref.tier === "local") {
+            const predictor = ctx.models?.get(id, key);
+            if (!predictor) {
+                skipped.push({ engine: key, reason: "unavailable" });
+                continue;
+            }
+            features ??= await extractFeatures(task.features, input, ctx.embedder);
+            const p = predictor.predict(features);
+            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) });
+                deferred ??= { ref, p };
+                continue;
+            }
+            return finish(ref, p);
+        }
+        if (!ctx.cloud) {
+            skipped.push({ engine: key, reason: "unavailable" });
+            continue;
+        }
+        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) });
+        }
+    }
+    // The cloud could not answer after a low-confidence local one: the local answer stands.
+    if (deferred)
+        return finish(deferred.ref, deferred.p);
+    const decision = { taskId: id, mode: ctx.mode, engine: null, tier: null, confidence: null, skipped };
+    ctx.decisions?.record(decision);
+    throw new MlEngineUnavailableError(id, decision);
+}
+//# sourceMappingURL=run.js.map

package/dist/ml/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/ml/run.ts"],"names":[],"mappings":"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"}