@seanhogg/builderforce-memory-engine 2026.9.34 → 2026.10.2

package/dist/ml/federate.d.ts

@@ -0,0 +1,56 @@
+/**
+ * ml/federate.ts — trained ML heads federate like the model's own weights.
+ *
+ * A head's trained state is ONE flat f32 vector (`MlPredictor.exportParams`),
+ * stored as a CRC-trailed checkpoint so it is the same shape the delta pipeline
+ * already handles: a learner diffs its trained copy against the version it
+ * started from (`diffCheckpoints`), ships it on the existing delta wire with
+ * `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";
+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. */
+export declare function mlHeadParams(entry: EvermindMlHead): Float32Array;
+/** The head a package carries for `task`, if any. */
+export declare function packageMlHead(pkg: EvermindModelPackage, task: string): EvermindMlHead | undefined;
+/** `pkg` with `entry` as its head for `entry.task` (replacing the old one). */
+export declare function withPackageMlHead(pkg: EvermindModelPackage, entry: EvermindMlHead): EvermindModelPackage;
+/**
+ * The delta-wire payload for a locally trained head: its new parameters diffed
+ * against the version it started from. The caller owns the size guard, as for LM deltas.
+ */
+export declare function buildMlHeadDelta(base: EvermindMlHead, trained: ArrayLike<number>, weight?: number, label?: string): DeltaLearnPayload;
+export interface MlHeadMergeOutcome {
+    /** The head after the round: version + 1 when accepted, the base unchanged when refused. */
+    head: EvermindMlHead;
+    merge: GatedMergeResult;
+    /** Contributions left out of the batch, by index, with why. */
+    rejected: {
+        index: number;
+        reason: string;
+    }[];
+}
+/**
+ * One federated round for a head: validate each contribution ON ITS OWN (wrong
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,99 @@
+/**
+ * ml/federate.ts — trained ML heads federate like the model's own weights.
+ *
+ * A head's trained state is ONE flat f32 vector (`MlPredictor.exportParams`),
+ * stored as a CRC-trailed checkpoint so it is the same shape the delta pipeline
+ * already handles: a learner diffs its trained copy against the version it
+ * started from (`diffCheckpoints`), ships it on the existing delta wire with
+ * `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, 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 { diffCheckpoints } from "../utils/delta.js";
+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 {
+        task,
+        engine,
+        version,
+        shape,
+        params: bytesToBase64(headCheckpoint(params)),
+        ...(evalLoss != null && Number.isFinite(evalLoss) ? { evalLoss } : {}),
+    };
+}
+/** The entry's flat parameters. */
+export function mlHeadParams(entry) {
+    return headParams(base64ToBytes(entry.params));
+}
+/** The head a package carries for `task`, if any. */
+export function packageMlHead(pkg, task) {
+    return pkg.manifest.mlHeads?.find((h) => h.task === task);
+}
+/** `pkg` with `entry` as its head for `entry.task` (replacing the old one). */
+export function withPackageMlHead(pkg, entry) {
+    return pkg.withMlHeads([...(pkg.manifest.mlHeads ?? []).filter((h) => h.task !== entry.task), entry]);
+}
+/**
+ * The delta-wire payload for a locally trained head: its new parameters diffed
+ * against the version it started from. The caller owns the size guard, as for LM deltas.
+ */
+export function buildMlHeadDelta(base, trained, weight, label) {
+    const diff = diffCheckpoints(base64ToBytes(base.params), headCheckpoint(trained));
+    return buildDeltaLearnPayload(diff, base.version, weight, label ?? `ml head ${base.task}`, mlHeadTarget(base.task));
+}
+/**
+ * One federated round for a head: validate each contribution ON ITS OWN (wrong
+ * 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);
+    const target = mlHeadTarget(base.task);
+    const diffs = [];
+    const weights = [];
+    const rejected = [];
+    payloads.forEach((p, index) => {
+        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;
+        try {
+            diff = decodeDeltaPayload(p);
+        }
+        catch (error) {
+            return void rejected.push({ index, reason: `diff is not base64: ${error instanceof Error ? error.message : String(error)}` });
+        }
+        const why = deltaUnusableReason(diff, baseCp);
+        if (why)
+            return void rejected.push({ index, reason: why });
+        diffs.push(diff);
+        weights.push(p.weight ?? 1);
+    });
+    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 = {
+        ...base,
+        version: base.version + 1,
+        params: bytesToBase64(merge.checkpoint),
+        ...(merge.newLoss != null ? { evalLoss: merge.newLoss } : {}),
+    };
+    return { head, merge, rejected };
+}
+//# sourceMappingURL=federate.js.map

package/dist/ml/federate.js.map

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

package/dist/ml/head_trainer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 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).
+ *
+ * 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.
+ */
+/** A named trainable tensor (flat row-major Float32Array). */
+export interface HeadParam {
+    name: string;
+    data: Float32Array;
+    numel: number;
+}
+/** What a head must expose to be trained by {@link HeadTrainer}. */
+export interface TrainableHead<S> {
+    /** Trainable parameters, in a stable order. */
+    parameters(): HeadParam[];
+    /** Gradient buffers, index-aligned with {@link parameters}. */
+    gradients(): HeadParam[];
+    zeroGrad(): void;
+    /** Accumulate gradients for one sample into {@link gradients}; returns its loss. */
+    accumulate(sample: S): number;
+    /** Forward-only loss of one sample. */
+    loss(sample: S): number;
+}
+export interface HeadTrainOptions {
+    learningRate?: number;
+    epochs?: number;
+    weightDecay?: number;
+    beta1?: number;
+    beta2?: number;
+    eps?: number;
+    /** Max global gradient L2 norm before the optimiser step. Default 1.0. */
+    maxGradNorm?: number;
+    /** Per-epoch hook. `gradNorm` is the pre-clip gradient L2 norm this epoch (the
+     *  instability early-warning) — computed CPU-side so it's always available. */
+    onEpochEnd?: ((epoch: number, loss: number, gradNorm?: number) => void) | null;
+}
+export declare class HeadTrainer<S> {
+    /** Name used in error messages (the registration that owns this trainer). */
+    private readonly label;
+    readonly head: TrainableHead<S>;
+    readonly device: GPUDevice | null;
+    private _moments;
+    private _step;
+    private readonly _adamwPipeline;
+    constructor(head: TrainableHead<S>, device?: GPUDevice | null, 
+    /** Name used in error messages (the registration that owns this trainer). */
+    label?: string);
+    /** Whether the optimiser step runs on the GPU. */
+    get gpuTraining(): boolean;
+    private _initMoments;
+    /**
+     * 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.
+     */
+    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`). */
+    private _adamwStepCpu;
+    /** AdamW on the GPU via the shared WEIGHT_UPDATE_WGSL kernel. Awaited per step. */
+    private _adamwStepGpu;
+}
+/** Concatenate a head's parameters into one flat vector (the federation unit). */
+export declare function flattenParams(params: readonly HeadParam[]): Float32Array;
+/** Write a flat vector back into a head's parameters (inverse of {@link flattenParams}). */
+export declare function assignParams(params: readonly HeadParam[], flat: ArrayLike<number>): void;
+//# sourceMappingURL=head_trainer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"head_trainer.d.ts","sourceRoot":"","sources":["../../src/ml/head_trainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;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;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,8EAA8E;IAC9E,OAAO,CAAC,aAAa;IAQrB,mFAAmF;YACrE,aAAa;CA2B5B;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"}

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 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).
+ *
+ * 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";
+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]);
+    // 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 {
+    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 = { lr: learningRate, weightDecay, beta1, beta2, eps, beta1_t, beta2_t, maxDelta: 0 };
+            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;
+    }
+    /** AdamW on the CPU via the kernel's shared mirror (`adamwUpdateInPlace`). */
+    _adamwStepCpu(grads, hp) {
+        const params = this.head.parameters();
+        for (let pi = 0; pi < params.length; pi++) {
+            const mom = this._moments[pi];
+            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. */
+    async _adamwStepGpu(grads, hp) {
+        const device = this.device;
+        const pipeline = this._adamwPipeline;
+        const params = this.head.parameters();
+        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, 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));
+            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"}