@seanhogg/builderforce-memory-engine 2026.10.1 → 2026.10.3

package/dist/ml/eval_loss.js

@@ -0,0 +1,20 @@
+/**
+ * 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 (or zero-weight) set.
+ */
+export function mlEvalLoss(kind, predictor, samples) {
+    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;
+}
+//# sourceMappingURL=eval_loss.js.map

package/dist/ml/eval_loss.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval_loss.js","sourceRoot":"","sources":["../../src/ml/eval_loss.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAgB,EAAE,SAAsB,EAAE,OAA4B;IAC/F,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IACrF,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpH,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QAChB,IAAI,IAAI,CAAC,CAAC;IACZ,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACtC,CAAC"}

package/dist/ml/federate.d.ts

@@ -8,35 +8,16 @@
  * `target: "ml:<task>"`, and the writer folds N of them with the existing FedAvg
  * (`mergeCheckpointDiffsGated` → `mergeCheckpointDiffs`), refusing a merge whose
  * held-out loss regresses. No second wire, no second merge.
+ *
+ * The head's manifest entry and checkpoint format live with the artifact
+ * (`evermind/ml_head.ts`); this module only imports evermind/, never the reverse.
  */
 import { type DeltaLearnPayload } from "../evermind/delta_wire.js";
 import { type GatedMergeResult, type MergeGateOptions } from "../evermind/merge.js";
+import { type EvermindMlHead } from "../evermind/ml_head.js";
 import type { EvermindModelPackage } from "../evermind/package.js";
-/**
- * One trained ML-catalog head carried in a model's manifest (`mlHeads`): small, so
- * it rides in the manifest, and versioned, so it federates — a delta against it is
- * `target: "ml:<task>"`, `baseVersion: version` on the delta wire.
- */
-export interface EvermindMlHead {
-    /** Catalog task id, e.g. `run.local-success`. */
-    task: string;
-    /** Engine key, e.g. `local:classical:logistic`. */
-    engine: string;
-    /** Integer head version — what a federated delta for it is diffed against. */
-    version: number;
-    /** What a loader needs to rebuild the predictor (e.g. `{ dim, classes }`). */
-    shape: Record<string, number>;
-    /** base64 of the CRC-trailed f32 checkpoint of the head's flat parameters. */
-    params: string;
-    /** Held-out loss of this version, when measured. */
-    evalLoss?: number;
-}
-/** A head's flat parameters as a CRC-trailed f32 checkpoint. */
-export declare function headCheckpoint(params: ArrayLike<number>): ArrayBuffer;
-/** The flat parameters of a head checkpoint. Throws on a failed CRC. */
-export declare function headParams(checkpoint: ArrayBuffer): Float32Array;
-/** Why a manifest head entry is unusable, or null (the package's validate() calls this). */
-export declare function mlHeadUnusableReason(h: EvermindMlHead): string | null;
+export { headCheckpoint, headParams, mlHeadUnusableReason } from "../evermind/ml_head.js";
+export type { EvermindMlHead } from "../evermind/ml_head.js";
 /** A manifest entry for a head's current parameters. */
 export declare function mlHeadEntry(task: string, engine: string, version: number, params: ArrayLike<number>, shape?: Record<string, number>, evalLoss?: number): EvermindMlHead;
 /** The entry's flat parameters. */
@@ -65,6 +46,11 @@ export interface MlHeadMergeOutcome {
  * target, stale base or a malformed diff costs only itself), FedAvg the rest, and
  * keep the result only if `score` (held-out loss of a parameter vector, lower is
  * better) does not regress.
+ *
+ * Fails CLOSED: `requireEval` defaults to true here, so a round `score` cannot judge
+ * (null — e.g. `mlEvalLoss` for an anomaly/cluster head or an empty holdout — or a
+ * non-finite loss) is refused. A caller that federates an unscorable head on purpose
+ * passes `{ requireEval: false }` explicitly.
  */
 export declare function mergeMlHeadDeltas(base: EvermindMlHead, payloads: readonly DeltaLearnPayload[], score: (params: Float32Array) => number | null, opts?: MergeGateOptions): MlHeadMergeOutcome;
 //# sourceMappingURL=federate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"federate.d.ts","sourceRoot":"","sources":["../../src/ml/federate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAiF,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAClJ,OAAO,EAA6B,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC/G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAKnE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,WAAW,CAIrE;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAKhE;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAWrE;AAED,wDAAwD;AACxD,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,EACzB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAClC,QAAQ,CAAC,EAAE,MAAM,GAChB,cAAc,CAShB;AAED,mCAAmC;AACnC,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CAEhE;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,GAAG,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEjG;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,oBAAoB,EAAE,KAAK,EAAE,cAAc,GAAG,oBAAoB,CAExG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAGrI;AAED,MAAM,WAAW,kBAAkB;IACjC,4FAA4F;IAC5F,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,gBAAgB,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,KAAK,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,MAAM,GAAG,IAAI,EAC9C,IAAI,GAAE,gBAAqB,GAC1B,kBAAkB,CA8BpB"}
+{"version":3,"file":"federate.d.ts","sourceRoot":"","sources":["../../src/ml/federate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAA6B,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC/G,OAAO,EAA8B,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACzF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAInE,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,wDAAwD;AACxD,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,EACzB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAClC,QAAQ,CAAC,EAAE,MAAM,GAChB,cAAc,CAShB;AAED,mCAAmC;AACnC,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CAEhE;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,GAAG,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEjG;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,oBAAoB,EAAE,KAAK,EAAE,cAAc,GAAG,oBAAoB,CAExG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAGrI;AAED,MAAM,WAAW,kBAAkB;IACjC,4FAA4F;IAC5F,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,gBAAgB,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,KAAK,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,MAAM,GAAG,IAAI,EAC9C,IAAI,GAAE,gBAAqB,GAC1B,kBAAkB,CA+BpB"}

package/dist/ml/federate.js

@@ -8,45 +8,16 @@
  * `target: "ml:<task>"`, and the writer folds N of them with the existing FedAvg
  * (`mergeCheckpointDiffsGated` → `mergeCheckpointDiffs`), refusing a merge whose
  * held-out loss regresses. No second wire, no second merge.
+ *
+ * The head's manifest entry and checkpoint format live with the artifact
+ * (`evermind/ml_head.ts`); this module only imports evermind/, never the reverse.
  */
-import { buildDeltaLearnPayload, decodeDeltaPayload, deltaUnusableReason, mlHeadTarget } from "../evermind/delta_wire.js";
+import { buildDeltaLearnPayload, decodeDeltaPayload, deltaTargetMismatch, deltaUnusableReason, mlHeadTarget, } from "../evermind/delta_wire.js";
 import { mergeCheckpointDiffsGated } from "../evermind/merge.js";
+import { headCheckpoint, headParams } from "../evermind/ml_head.js";
 import { base64ToBytes, bytesToBase64 } from "../utils/base64.js";
-import { appendCrcTrailer, verifyCrcTrailer } from "../utils/crc32.js";
 import { diffCheckpoints } from "../utils/delta.js";
-/** A head's flat parameters as a CRC-trailed f32 checkpoint. */
-export function headCheckpoint(params) {
-    const body = new ArrayBuffer(params.length * 4);
-    new Float32Array(body).set(Array.from(params));
-    return appendCrcTrailer(body);
-}
-/** The flat parameters of a head checkpoint. Throws on a failed CRC. */
-export function headParams(checkpoint) {
-    const crc = verifyCrcTrailer(checkpoint);
-    if (!crc.ok)
-        throw new Error("headParams: checkpoint failed its CRC check");
-    if (crc.body.byteLength % 4 !== 0)
-        throw new Error("headParams: checkpoint is not f32");
-    return new Float32Array(crc.body);
-}
-/** Why a manifest head entry is unusable, or null (the package's validate() calls this). */
-export function mlHeadUnusableReason(h) {
-    if (!h || typeof h.task !== "string" || typeof h.engine !== "string")
-        return "task and engine are required";
-    if (!Number.isInteger(h.version) || h.version < 0)
-        return "version must be a non-negative integer";
-    try {
-        const crc = verifyCrcTrailer(base64ToBytes(h.params));
-        if (!crc.hasTrailer || !crc.ok)
-            return "params checkpoint failed its CRC check";
-        if (crc.body.byteLength % 4 !== 0)
-            return "params checkpoint is not f32";
-    }
-    catch {
-        return "params is not base64";
-    }
-    return null;
-}
+export { headCheckpoint, headParams, mlHeadUnusableReason } from "../evermind/ml_head.js";
 /** A manifest entry for a head's current parameters. */
 export function mlHeadEntry(task, engine, version, params, shape = {}, evalLoss) {
     return {
@@ -83,6 +54,11 @@ export function buildMlHeadDelta(base, trained, weight, label) {
  * target, stale base or a malformed diff costs only itself), FedAvg the rest, and
  * keep the result only if `score` (held-out loss of a parameter vector, lower is
  * better) does not regress.
+ *
+ * Fails CLOSED: `requireEval` defaults to true here, so a round `score` cannot judge
+ * (null — e.g. `mlEvalLoss` for an anomaly/cluster head or an empty holdout — or a
+ * non-finite loss) is refused. A caller that federates an unscorable head on purpose
+ * passes `{ requireEval: false }` explicitly.
  */
 export function mergeMlHeadDeltas(base, payloads, score, opts = {}) {
     const baseCp = base64ToBytes(base.params);
@@ -91,8 +67,9 @@ export function mergeMlHeadDeltas(base, payloads, score, opts = {}) {
     const weights = [];
     const rejected = [];
     payloads.forEach((p, index) => {
-        if (p.target !== target)
-            return void rejected.push({ index, reason: `target ${p.target ?? "(model)"} is not ${target}` });
+        const wrongTarget = deltaTargetMismatch(p.target, target);
+        if (wrongTarget)
+            return void rejected.push({ index, reason: wrongTarget });
         if (p.baseVersion !== base.version)
             return void rejected.push({ index, reason: `stale base version ${p.baseVersion} (head is ${base.version})` });
         let diff;
@@ -108,7 +85,7 @@ export function mergeMlHeadDeltas(base, payloads, score, opts = {}) {
         diffs.push(diff);
         weights.push(p.weight ?? 1);
     });
-    const merge = mergeCheckpointDiffsGated(baseCp, diffs, weights, (cp) => score(headParams(cp)), opts);
+    const merge = mergeCheckpointDiffsGated(baseCp, diffs, weights, (cp) => score(headParams(cp)), { ...opts, requireEval: opts.requireEval ?? true });
     if (!merge.accepted)
         return { head: base, merge, rejected };
     const head = {

package/dist/ml/federate.js.map

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

package/dist/ml/head_trainer.d.ts

@@ -5,8 +5,13 @@
  *
  * 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).
+ * no device it runs the kernel's CPU mirror, `adamwUpdateInPlace` (`optim/adamw.ts`,
+ * NaN/Inf guard included), so training works everywhere (CI, Node without
+ * @webgpu/node, a laptop with no GPU). Neither path bounds the step (maxDelta 0).
+ *
+ * A non-finite gradient element is skipped by both paths — its moments and weight
+ * are left as they were, so the next finite step trains it again — and counted in
+ * {@link HeadTrainer.skippedNonFinite}, so a caller can see a run that diverged.
  *
  * The head owns its forward/backward and its loss (MSE for regression, BCE /
  * softmax cross-entropy for classification); this file owns only the loop:
@@ -50,10 +55,18 @@ export declare class HeadTrainer<S> {
     readonly device: GPUDevice | null;
     private _moments;
     private _step;
+    private _skippedNonFinite;
     private readonly _adamwPipeline;
     constructor(head: TrainableHead<S>, device?: GPUDevice | null, 
     /** Name used in error messages (the registration that owns this trainer). */
     label?: string);
+    /**
+     * Parameter elements whose gradient was non-finite (NaN/±Inf) and whose update was
+     * therefore skipped, summed over every step this trainer has taken. 0 on a healthy run.
+     */
+    get skippedNonFinite(): number;
+    /** Whether any step had to skip a non-finite gradient element. */
+    get diverged(): boolean;
     /** Whether the optimiser step runs on the GPU. */
     get gpuTraining(): boolean;
     private _initMoments;
@@ -65,6 +78,7 @@ export declare class HeadTrainer<S> {
     train(samples: S[], opts?: HeadTrainOptions): Promise<number[]>;
     /** Mean loss over samples (no weight update). 0 for an empty set. */
     evaluate(samples: S[]): number;
+    /** AdamW on the CPU via the kernel's shared mirror (`adamwUpdateInPlace`), which counts its skips. */
     private _adamwStepCpu;
     /** AdamW on the GPU via the shared WEIGHT_UPDATE_WGSL kernel. Awaited per step. */
     private _adamwStepGpu;

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

@@ -1 +1 @@
-{"version":3,"file":"head_trainer.d.ts","sourceRoot":"","sources":["../../src/ml/head_trainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAaH,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,+CAA+C;IAC/C,UAAU,IAAI,SAAS,EAAE,CAAC;IAC1B,+DAA+D;IAC/D,SAAS,IAAI,SAAS,EAAE,CAAC;IACzB,QAAQ,IAAI,IAAI,CAAC;IACjB,oFAAoF;IACpF,UAAU,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;IAC9B,uCAAuC;IACvC,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;mFAC+E;IAC/E,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAChF;AAiCD,qBAAa,WAAW,CAAC,CAAC;IAUtB,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,KAAK;IAVxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4B;gBAGzD,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EACtB,MAAM,GAAE,SAAS,GAAG,IAAW;IAC/B,6EAA6E;IAC5D,KAAK,GAAE,MAAsB;IAShD,kDAAkD;IAClD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,OAAO,CAAC,YAAY;IAQpB;;;;OAIG;IACG,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA8CzE,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,MAAM;IAO9B,OAAO,CAAC,aAAa;IAkBrB,mFAAmF;YACrE,aAAa;CA+B5B;AAcD,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,YAAY,CAQxE;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,CAQxF"}
+{"version":3,"file":"head_trainer.d.ts","sourceRoot":"","sources":["../../src/ml/head_trainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAcH,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,+CAA+C;IAC/C,UAAU,IAAI,SAAS,EAAE,CAAC;IAC1B,+DAA+D;IAC/D,SAAS,IAAI,SAAS,EAAE,CAAC;IACzB,QAAQ,IAAI,IAAI,CAAC;IACjB,oFAAoF;IACpF,UAAU,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;IAC9B,uCAAuC;IACvC,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;mFAC+E;IAC/E,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAChF;AAuBD,qBAAa,WAAW,CAAC,CAAC;IAWtB,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,KAAK;IAXxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4B;gBAGzD,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EACtB,MAAM,GAAE,SAAS,GAAG,IAAW;IAC/B,6EAA6E;IAC5D,KAAK,GAAE,MAAsB;IAShD;;;OAGG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,kEAAkE;IAClE,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,kDAAkD;IAClD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,OAAO,CAAC,YAAY;IAQpB;;;;OAIG;IACG,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA8CzE,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,MAAM;IAO9B,sGAAsG;IACtG,OAAO,CAAC,aAAa;IAQrB,mFAAmF;YACrE,aAAa;CA6B5B;AAiCD,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,YAAY,CAQxE;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,CAQxF"}

package/dist/ml/head_trainer.js

@@ -5,8 +5,13 @@
  *
  * 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).
+ * no device it runs the kernel's CPU mirror, `adamwUpdateInPlace` (`optim/adamw.ts`,
+ * NaN/Inf guard included), so training works everywhere (CI, Node without
+ * @webgpu/node, a laptop with no GPU). Neither path bounds the step (maxDelta 0).
+ *
+ * A non-finite gradient element is skipped by both paths — its moments and weight
+ * are left as they were, so the next finite step trains it again — and counted in
+ * {@link HeadTrainer.skippedNonFinite}, so a caller can see a run that diverged.
  *
  * The head owns its forward/backward and its loss (MSE for regression, BCE /
  * softmax cross-entropy for classification); this file owns only the loop:
@@ -14,10 +19,19 @@
  */
 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);
+import { adamwUpdateInPlace } from "../optim/adamw.js";
+/** Byte size of WEIGHT_UPDATE_WGSL's `AdamParams` uniform: 1 u32 + 8 f32 + 3 f32 pad = 48. */
+const ADAM_PARAMS_BYTES = 48;
+/**
+ * Pack `AdamParams` exactly as WEIGHT_UPDATE_WGSL declares it:
+ * `num_elements: u32, lr, beta1, beta2, eps, weight_decay, beta1_t, beta2_t,
+ * max_delta, _pad0, _pad1, _pad2` (all f32 after the first) — 48 bytes.
+ */
+function packAdamParams(numElements, hp) {
+    const buf = new ArrayBuffer(ADAM_PARAMS_BYTES);
     new Uint32Array(buf, 0, 1).set([numElements]);
-    new Float32Array(buf, 4, 7).set([lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t]);
+    // Pads stay 0 (fresh ArrayBuffer).
+    new Float32Array(buf, 4, 8).set([hp.lr, hp.beta1, hp.beta2, hp.eps, hp.weightDecay, hp.beta1_t, hp.beta2_t, hp.maxDelta]);
     return buf;
 }
 export class HeadTrainer {
@@ -26,6 +40,7 @@ export class HeadTrainer {
     device;
     _moments = null;
     _step = 0;
+    _skippedNonFinite = 0;
     _adamwPipeline;
     constructor(head, device = null, 
     /** Name used in error messages (the registration that owns this trainer). */
@@ -37,6 +52,17 @@ export class HeadTrainer {
             ? createComputePipeline(device, WEIGHT_UPDATE_WGSL, "adamw_update")
             : null;
     }
+    /**
+     * Parameter elements whose gradient was non-finite (NaN/±Inf) and whose update was
+     * therefore skipped, summed over every step this trainer has taken. 0 on a healthy run.
+     */
+    get skippedNonFinite() {
+        return this._skippedNonFinite;
+    }
+    /** Whether any step had to skip a non-finite gradient element. */
+    get diverged() {
+        return this._skippedNonFinite > 0;
+    }
     /** Whether the optimiser step runs on the GPU. */
     get gpuTraining() {
         return this.device != null && this._adamwPipeline != null;
@@ -75,7 +101,7 @@ export class HeadTrainer {
             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 };
+            const hp = { lr: learningRate, weightDecay, beta1, beta2, eps, beta1_t, beta2_t, maxDelta: 0 };
             if (this.gpuTraining) {
                 await this._adamwStepGpu(grads, hp);
             }
@@ -98,21 +124,12 @@ export class HeadTrainer {
             total += this.head.loss(s);
         return total / samples.length;
     }
+    /** AdamW on the CPU via the kernel's shared mirror (`adamwUpdateInPlace`), which counts its skips. */
     _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);
-            }
+            this._skippedNonFinite += adamwUpdateInPlace(params[pi].data, grads[pi].data, mom.m, mom.v, hp);
         }
     }
     /** AdamW on the GPU via the shared WEIGHT_UPDATE_WGSL kernel. Awaited per step. */
@@ -120,15 +137,16 @@ export class HeadTrainer {
         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];
+            // The kernel skips these elements too; it cannot count, so count them here.
+            this._skippedNonFinite += countNonFinite(grads[pi].data);
             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 uni = createUniformBuffer(device, packAdamParams(p.numel, hp));
             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));
@@ -142,20 +160,39 @@ export class HeadTrainer {
         }
     }
 }
-/** Clip grads to `maxNorm` in place; returns the PRE-clip L2 norm (the signal). */
+/** Elements of `a` that are NaN or ±Inf. */
+function countNonFinite(a) {
+    let n = 0;
+    for (let i = 0; i < a.length; i++)
+        if (!Number.isFinite(a[i]))
+            n++;
+    return n;
+}
+/**
+ * Clip grads to `maxNorm` in place; returns the PRE-clip L2 norm (the signal — NaN
+ * or Inf when any element is). The clip itself uses the norm of the FINITE elements:
+ * those are skipped by the optimiser anyway, and one NaN must not exempt the rest
+ * from clipping.
+ */
 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;
+    let finiteSq = 0;
+    for (const g of grads) {
+        for (let i = 0; i < g.data.length; i++) {
+            const sq = g.data[i] * g.data[i];
+            normSq += sq;
+            if (Number.isFinite(sq))
+                finiteSq += sq;
+        }
+    }
+    const finiteNorm = Math.sqrt(finiteSq);
+    if (finiteNorm > maxNorm && finiteNorm > 0) {
+        const scale = maxNorm / finiteNorm;
         for (const g of grads)
             for (let i = 0; i < g.data.length; i++)
                 g.data[i] *= scale;
     }
-    return norm;
+    return Math.sqrt(normSq);
 }
 /** Concatenate a head's parameters into one flat vector (the federation unit). */
 export function flattenParams(params) {

package/dist/ml/head_trainer.js.map

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

package/dist/ml/run.d.ts

@@ -87,8 +87,17 @@ export declare class MlEngineUnavailableError extends Error {
     readonly decision: MlDecision;
     constructor(taskId: string, decision: MlDecision);
 }
-/** 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 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. */
+/**
+ * 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 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

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

package/dist/ml/run.js

@@ -59,32 +59,51 @@ 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"})`);
+        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.taskId = taskId;
         this.decision = decision;
         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, 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;
+    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 = 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) => (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(id, input, ctx) {
     const task = ctx.registry.require(id);
     const engines = candidateEngines(task, ctx.mode, ctx.engine);
     const skipped = [];
     let features = null;
+    let featureError = 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 });
@@ -99,8 +118,28 @@ export async function runMlTask(id, input, ctx) {
                 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;
+            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) });
@@ -117,7 +156,7 @@ export async function runMlTask(id, input, ctx) {
             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.