@seanhogg/builderforce-memory-engine 2026.9.33 → 2026.10.1

package/dist/ml/dense_head.d.ts

@@ -0,0 +1,33 @@
+import { type HeadParam, type TrainableHead } from "./head_trainer.js";
+import type { MlPrediction, MlPredictor, MlSample } from "./types.js";
+export interface DenseHeadConfig {
+    inputDim: number;
+    /** Hidden width; 0 = a linear head. */
+    hiddenDim: number;
+    /** Classes (softmax) or 1 (mse regression). */
+    outputDim: number;
+    /** `softmax` = classification over `outputDim` classes; `mse` = scalar regression. */
+    objective: "softmax" | "mse";
+    seed?: number;
+}
+export declare class DenseHead implements TrainableHead<MlSample>, MlPredictor {
+    readonly config: Required<DenseHeadConfig>;
+    private readonly _params;
+    private readonly _grads;
+    constructor(config: DenseHeadConfig);
+    private _p;
+    private _g;
+    parameters(): HeadParam[];
+    gradients(): HeadParam[];
+    zeroGrad(): void;
+    /** Hidden activation (or the input itself for a linear head) and the output logits/value. */
+    private _forward;
+    /** Loss and dLoss/dz of one sample (unweighted). */
+    private _lossGrad;
+    loss(s: MlSample): number;
+    accumulate(s: MlSample): number;
+    predict(x: Float32Array): MlPrediction;
+    exportParams(): Float32Array;
+    importParams(params: ArrayLike<number>): void;
+}
+//# sourceMappingURL=dense_head.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dense_head.d.ts","sourceRoot":"","sources":["../../src/ml/dense_head.ts"],"names":[],"mappings":"AAUA,OAAO,EAA+B,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACpG,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,SAAS,EAAE,SAAS,GAAG,KAAK,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,SAAU,YAAW,aAAa,CAAC,QAAQ,CAAC,EAAE,WAAW;IACpE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,MAAM,EAAE,eAAe;IAsBnC,OAAO,CAAC,EAAE;IAIV,OAAO,CAAC,EAAE;IAIV,UAAU,IAAI,SAAS,EAAE;IAIzB,SAAS,IAAI,SAAS,EAAE;IAIxB,QAAQ,IAAI,IAAI;IAIhB,6FAA6F;IAC7F,OAAO,CAAC,QAAQ;IA0BhB,oDAAoD;IACpD,OAAO,CAAC,SAAS;IAUjB,IAAI,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM;IAIzB,UAAU,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM;IA6B/B,OAAO,CAAC,CAAC,EAAE,YAAY,GAAG,YAAY;IAOtC,YAAY,IAAI,YAAY;IAI5B,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI;CAG9C"}

package/dist/ml/dense_head.js

@@ -0,0 +1,140 @@
+/**
+ * ml/dense_head.ts — the catalog's trainable head: linear, or one tanh hidden layer,
+ * over a feature vector (usually an experience embedding).
+ *
+ * It is a {@link TrainableHead} (so the ONE {@link HeadTrainer} fits it, on the
+ * GPU when there is one) and an {@link MlPredictor} (so the runner answers with
+ * it). Its parameters flatten to one vector — the unit that federates.
+ */
+import { gaussianArray, SeededRng } from "../utils/rng.js";
+import { softmax } from "../training/cpu_ops.js";
+import { assignParams, flattenParams } from "./head_trainer.js";
+export class DenseHead {
+    config;
+    _params;
+    _grads;
+    constructor(config) {
+        this.config = { seed: 0x4e4d, ...config };
+        const { inputDim, hiddenDim, outputDim, objective } = this.config;
+        if (objective === "mse" && outputDim !== 1)
+            throw new Error("DenseHead: mse objective needs outputDim 1");
+        if (objective === "softmax" && outputDim < 2)
+            throw new Error("DenseHead: softmax objective needs outputDim ≥ 2");
+        const rng = new SeededRng(this.config.seed);
+        const next = () => rng.next();
+        const inner = hiddenDim > 0 ? hiddenDim : inputDim;
+        const shapes = [
+            ...(hiddenDim > 0
+                ? [
+                    ["w1", hiddenDim * inputDim, 1 / Math.sqrt(inputDim)],
+                    ["b1", hiddenDim, 0],
+                ]
+                : []),
+            ["w2", outputDim * inner, 1 / Math.sqrt(inner)],
+            ["b2", outputDim, 0],
+        ];
+        this._params = shapes.map(([name, n, std]) => ({ name, numel: n, data: std > 0 ? gaussianArray(n, std, next) : new Float32Array(n) }));
+        this._grads = shapes.map(([name, n]) => ({ name, numel: n, data: new Float32Array(n) }));
+    }
+    _p(name) {
+        return this._params.find((p) => p.name === name).data;
+    }
+    _g(name) {
+        return this._grads.find((p) => p.name === name).data;
+    }
+    parameters() {
+        return this._params;
+    }
+    gradients() {
+        return this._grads;
+    }
+    zeroGrad() {
+        for (const g of this._grads)
+            g.data.fill(0);
+    }
+    /** Hidden activation (or the input itself for a linear head) and the output logits/value. */
+    _forward(x) {
+        const { inputDim, hiddenDim, outputDim } = this.config;
+        let h;
+        if (hiddenDim > 0) {
+            const w1 = this._p("w1");
+            const b1 = this._p("b1");
+            h = new Float32Array(hiddenDim);
+            for (let j = 0; j < hiddenDim; j++) {
+                let s = b1[j];
+                for (let i = 0; i < inputDim; i++)
+                    s += w1[j * inputDim + i] * (x[i] ?? 0);
+                h[j] = Math.tanh(s);
+            }
+        }
+        else {
+            h = Float32Array.from({ length: inputDim }, (_, i) => x[i] ?? 0);
+        }
+        const w2 = this._p("w2");
+        const b2 = this._p("b2");
+        const z = new Float32Array(outputDim);
+        for (let k = 0; k < outputDim; k++) {
+            let s = b2[k];
+            for (let j = 0; j < h.length; j++)
+                s += w2[k * h.length + j] * h[j];
+            z[k] = s;
+        }
+        return { h, z };
+    }
+    /** Loss and dLoss/dz of one sample (unweighted). */
+    _lossGrad(z, y) {
+        if (this.config.objective === "mse") {
+            const d = z[0] - y;
+            return { loss: 0.5 * d * d, dz: Float32Array.of(d) };
+        }
+        const p = softmax(z);
+        const dz = Float32Array.from(p, (v, k) => v - (k === y ? 1 : 0));
+        return { loss: -Math.log(Math.max(p[y] ?? 0, 1e-12)), dz };
+    }
+    loss(s) {
+        return (s.weight ?? 1) * this._lossGrad(this._forward(s.x).z, s.y).loss;
+    }
+    accumulate(s) {
+        const w = s.weight ?? 1;
+        const { inputDim, hiddenDim, outputDim } = this.config;
+        const { h, z } = this._forward(s.x);
+        const { loss, dz } = this._lossGrad(z, s.y);
+        const w2 = this._p("w2");
+        const gW2 = this._g("w2");
+        const gB2 = this._g("b2");
+        const dh = new Float32Array(h.length);
+        for (let k = 0; k < outputDim; k++) {
+            const g = w * dz[k];
+            gB2[k] = gB2[k] + g;
+            for (let j = 0; j < h.length; j++) {
+                gW2[k * h.length + j] = gW2[k * h.length + j] + g * h[j];
+                dh[j] = dh[j] + g * w2[k * h.length + j];
+            }
+        }
+        if (hiddenDim > 0) {
+            const gW1 = this._g("w1");
+            const gB1 = this._g("b1");
+            for (let j = 0; j < hiddenDim; j++) {
+                const dpre = dh[j] * (1 - h[j] * h[j]);
+                gB1[j] = gB1[j] + dpre;
+                for (let i = 0; i < inputDim; i++)
+                    gW1[j * inputDim + i] = gW1[j * inputDim + i] + dpre * (s.x[i] ?? 0);
+            }
+        }
+        return w * loss;
+    }
+    predict(x) {
+        const { z } = this._forward(x);
+        if (this.config.objective === "mse")
+            return { scores: [z[0]], confidence: 1 };
+        const scores = Array.from(softmax(z));
+        return { scores, confidence: Math.max(...scores) };
+    }
+    exportParams() {
+        return flattenParams(this._params);
+    }
+    importParams(params) {
+        assignParams(this._params, params);
+    }
+}
+//# sourceMappingURL=dense_head.js.map

package/dist/ml/dense_head.js.map

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

package/dist/ml/features.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ml/features.ts — how an input becomes a feature vector.
+ *
+ * Text goes through the existing CPU embedder seam ({@link TextEmbedder}, which
+ * `EvermindTextEmbedder` implements: the person's own Evermind turns text into
+ * an L2-normalised vector with no GPU and no network). Numeric fields are
+ * appended as the task supplies them — on a FIXED scale (see {@link logScale}),
+ * never one fitted to local data, so a federated weight means the same thing on
+ * every machine.
+ */
+import type { TextEmbedder } from "../lm/text_embedder.js";
+import type { FeatureSpec } from "./types.js";
+export type { TextEmbedder } from "../lm/text_embedder.js";
+/** Feature vector of one input: `[embed(text) …, numeric …]`. */
+export declare function extractFeatures<I>(spec: FeatureSpec<I>, input: I, embedder?: TextEmbedder): Promise<Float32Array>;
+/** Feature vectors of many inputs, in order. */
+export declare function extractFeatureMatrix<I>(spec: FeatureSpec<I>, inputs: readonly I[], embedder?: TextEmbedder): Promise<Float32Array[]>;
+/**
+ * A count or size on a fixed log scale: log1p(max(v, 0)) / log1p(ref). `ref` is
+ * the value that maps to 1 (e.g. 100k tokens), so the scale is the same everywhere.
+ */
+export declare function logScale(v: number, ref: number): number;
+/** A ratio clamped to [0, max] — fill fractions, success rates. */
+export declare function clampRatio(numerator: number, denominator: number, max?: number): number;
+//# sourceMappingURL=features.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../../src/ml/features.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,iEAAiE;AACjE,wBAAsB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAmBvH;AAED,gDAAgD;AAChD,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC,CAIzB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,CAGlF"}

package/dist/ml/features.js

@@ -0,0 +1,46 @@
+/** Feature vector of one input: `[embed(text) …, numeric …]`. */
+export async function extractFeatures(spec, input, embedder) {
+    const parts = [];
+    if (spec.text) {
+        if (!embedder)
+            throw new Error("extractFeatures: this task embeds text but no embedder was supplied");
+        parts.push(await embedder.embed(spec.text(input)));
+    }
+    if (spec.numeric) {
+        const nums = spec.numeric(input);
+        for (const v of nums)
+            if (!Number.isFinite(v))
+                throw new Error(`extractFeatures: non-finite numeric feature ${v}`);
+        parts.push(nums);
+    }
+    if (parts.length === 0)
+        throw new Error("extractFeatures: the feature spec has neither text nor numeric fields");
+    const out = new Float32Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+/** Feature vectors of many inputs, in order. */
+export async function extractFeatureMatrix(spec, inputs, embedder) {
+    const out = [];
+    for (const i of inputs)
+        out.push(await extractFeatures(spec, i, embedder));
+    return out;
+}
+/**
+ * A count or size on a fixed log scale: log1p(max(v, 0)) / log1p(ref). `ref` is
+ * the value that maps to 1 (e.g. 100k tokens), so the scale is the same everywhere.
+ */
+export function logScale(v, ref) {
+    return Math.log1p(Math.max(0, v)) / Math.log1p(Math.max(ref, 1));
+}
+/** A ratio clamped to [0, max] — fill fractions, success rates. */
+export function clampRatio(numerator, denominator, max = 4) {
+    if (!(denominator > 0))
+        return 0;
+    return Math.max(0, Math.min(max, numerator / denominator));
+}
+//# sourceMappingURL=features.js.map

package/dist/ml/features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.js","sourceRoot":"","sources":["../../src/ml/features.ts"],"names":[],"mappings":"AAeA,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,eAAe,CAAI,IAAoB,EAAE,KAAQ,EAAE,QAAuB;IAC9F,MAAM,KAAK,GAAwB,EAAE,CAAC;IACtC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACtG,KAAK,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjC,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,EAAE,CAAC,CAAC;QACnH,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IACjH,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACtE,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACd,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,gDAAgD;AAChD,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAoB,EACpB,MAAoB,EACpB,QAAuB;IAEvB,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,GAAG,CAAC,IAAI,CAAC,MAAM,eAAe,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC3E,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,GAAW;IAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,WAAmB,EAAE,GAAG,GAAG,CAAC;IACxE,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC;AAC7D,CAAC"}

package/dist/ml/federate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+import { type DeltaLearnPayload } from "../evermind/delta_wire.js";
+import { type GatedMergeResult, type MergeGateOptions } from "../evermind/merge.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;
+/** 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.
+ */
+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;;;;;;;;;;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"}

package/dist/ml/federate.js

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ */
+import { buildDeltaLearnPayload, decodeDeltaPayload, deltaUnusableReason, mlHeadTarget } from "../evermind/delta_wire.js";
+import { mergeCheckpointDiffsGated } from "../evermind/merge.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;
+}
+/** 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.
+ */
+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) => {
+        if (p.target !== target)
+            return void rejected.push({ index, reason: `target ${p.target ?? "(model)"} is not ${target}` });
+        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);
+    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,76 @@
+/**
+ * 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.
+ */
+/** 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;
+    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;;;;;;;;;;;;;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"}