@seanhogg/builderforce-memory-engine 2026.6.20 → 2026.6.28

package/dist/moe/moe_package.js

@@ -0,0 +1,157 @@
+/**
+ * moe_package.ts — EvermindModelPackage: the portable, publishable AI artifact.
+ *
+ * This is the unit a creator publishes to the marketplace and a buyer downloads
+ * and runs: a self-describing manifest (name, version, config, model card,
+ * integrity checksum) bundled with the trained checkpoint into one `.evermind`
+ * blob. It is the contract every downstream consumer (marketplace listing,
+ * purchase entitlement, workflow generator) reads — define it once, here.
+ *
+ * Zero-dep and isomorphic: serialises via TextEncoder/TextDecoder, runs in the
+ * browser (where models are trained) and in Node/Workers (where they execute).
+ */
+import { SharedExpertMoE } from "./moe_model.js";
+import { EvermindLM } from "../lm/evermind_lm.js";
+/** First 4 bytes of a serialised package: "EVM1". */
+const PKG_MAGIC = 0x45564d31;
+const PKG_VERSION = 1;
+/** 32-bit FNV-1a hash — dependency-free integrity check over the checkpoint. */
+function fnv1a(bytes) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < bytes.length; i++) {
+        h ^= bytes[i];
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/**
+ * A trained model packaged for publishing: manifest + checkpoint. Build one with
+ * {@link EvermindModelPackage.fromModel}, ship {@link toBlob}, and a buyer
+ * reconstitutes it with {@link fromBlob} → {@link validate} → {@link loadModel}.
+ */
+export class EvermindModelPackage {
+    manifest;
+    checkpoint;
+    constructor(manifest, checkpoint) {
+        this.manifest = manifest;
+        this.checkpoint = checkpoint;
+    }
+    /** Package a trained model with its publishing metadata. */
+    static fromModel(model, meta) {
+        const fp16 = meta.fp16 ?? false;
+        const checkpoint = model.exportWeights({ fp16 });
+        const manifest = {
+            schema: "evermind.model/1",
+            name: meta.name,
+            version: meta.version,
+            modelType: "shared-expert-moe",
+            config: model.config,
+            paramCount: model.parameters().reduce((n, p) => n + p.numel, 0),
+            checkpointFormat: "MoE0",
+            checkpointFp16: fp16,
+            checksum: fnv1a(new Uint8Array(checkpoint)),
+            card: meta.card,
+            ...(meta.createdAt ? { createdAt: meta.createdAt } : {}),
+        };
+        return new EvermindModelPackage(manifest, checkpoint);
+    }
+    /** Package a trained generative {@link EvermindLM} — the runnable marketplace AI. */
+    static fromLM(lm, meta) {
+        const fp16 = meta.fp16 ?? false;
+        const checkpoint = lm.exportWeights({ fp16 });
+        const manifest = {
+            schema: "evermind.model/1",
+            name: meta.name,
+            version: meta.version,
+            modelType: "evermind-lm",
+            config: lm.config,
+            paramCount: lm.parameters().reduce((n, p) => n + p.data.length, 0),
+            checkpointFormat: "EVL0",
+            checkpointFp16: fp16,
+            checksum: fnv1a(new Uint8Array(checkpoint)),
+            card: meta.card,
+            ...(meta.createdAt ? { createdAt: meta.createdAt } : {}),
+        };
+        return new EvermindModelPackage(manifest, checkpoint);
+    }
+    /** Serialise to a single `.evermind` blob: magic, version, manifest, checkpoint. */
+    toBlob() {
+        const manifestBytes = new TextEncoder().encode(JSON.stringify(this.manifest));
+        const headerBytes = 12; // magic, version, manifestLen
+        const out = new ArrayBuffer(headerBytes + manifestBytes.byteLength + this.checkpoint.byteLength);
+        const head = new Uint32Array(out, 0, 3);
+        head[0] = PKG_MAGIC;
+        head[1] = PKG_VERSION;
+        head[2] = manifestBytes.byteLength;
+        new Uint8Array(out, headerBytes, manifestBytes.byteLength).set(manifestBytes);
+        new Uint8Array(out, headerBytes + manifestBytes.byteLength).set(new Uint8Array(this.checkpoint));
+        return out;
+    }
+    /** Parse a `.evermind` blob. Throws on bad magic / truncation. */
+    static fromBlob(buffer) {
+        if (buffer.byteLength < 12)
+            throw new Error("EvermindModelPackage.fromBlob: truncated (no header)");
+        const head = new Uint32Array(buffer, 0, 3);
+        if (head[0] !== PKG_MAGIC)
+            throw new Error("EvermindModelPackage.fromBlob: bad magic (not an .evermind package)");
+        const manifestLen = head[2];
+        const headerBytes = 12;
+        if (headerBytes + manifestLen > buffer.byteLength) {
+            throw new Error("EvermindModelPackage.fromBlob: truncated (manifest length exceeds blob)");
+        }
+        const manifestBytes = new Uint8Array(buffer, headerBytes, manifestLen);
+        const manifest = JSON.parse(new TextDecoder().decode(manifestBytes));
+        const checkpoint = buffer.slice(headerBytes + manifestLen);
+        return new EvermindModelPackage(manifest, checkpoint);
+    }
+    /** Verify integrity + structural sanity before trusting a downloaded package. */
+    validate() {
+        const errors = [];
+        if (this.manifest.schema !== "evermind.model/1")
+            errors.push(`unknown schema: ${this.manifest.schema}`);
+        const c = this.manifest.config;
+        if (this.manifest.modelType === "shared-expert-moe") {
+            if (!c || c.modelDim <= 0 || c.hiddenDim <= 0 || c.numExperts <= 0 || c.topK < 1 || c.topK > c.numExperts) {
+                errors.push("invalid config");
+            }
+        }
+        else if (this.manifest.modelType === "evermind-lm") {
+            if (!c || c.vocabSize <= 0 || c.dModel <= 0 || c.numLayers <= 0 || c.numExperts <= 0 || c.topK < 1 || c.topK > c.numExperts) {
+                errors.push("invalid config");
+            }
+        }
+        else {
+            errors.push(`unsupported modelType: ${String(this.manifest.modelType)}`);
+        }
+        const actual = fnv1a(new Uint8Array(this.checkpoint));
+        if (actual !== this.manifest.checksum) {
+            errors.push(`checksum mismatch (manifest ${this.manifest.checksum}, actual ${actual}) — corrupt or tampered checkpoint`);
+        }
+        return { ok: errors.length === 0, errors };
+    }
+    /** Reconstruct the bare MoE layer. Validates first; throws if invalid / wrong type. */
+    loadModel() {
+        const v = this.validate();
+        if (!v.ok)
+            throw new Error(`EvermindModelPackage.loadModel: ${v.errors.join("; ")}`);
+        if (this.manifest.modelType !== "shared-expert-moe") {
+            throw new Error(`loadModel: package is '${this.manifest.modelType}', use loadLM()`);
+        }
+        const model = new SharedExpertMoE(this.manifest.config);
+        model.loadWeights(this.checkpoint);
+        return model;
+    }
+    /** Reconstruct the runnable generative model — what a marketplace buyer runs. */
+    loadLM() {
+        const v = this.validate();
+        if (!v.ok)
+            throw new Error(`EvermindModelPackage.loadLM: ${v.errors.join("; ")}`);
+        if (this.manifest.modelType !== "evermind-lm") {
+            throw new Error(`loadLM: package is '${this.manifest.modelType}', use loadModel()`);
+        }
+        const lm = new EvermindLM(this.manifest.config);
+        lm.loadWeights(this.checkpoint);
+        return lm;
+    }
+}
+//# sourceMappingURL=moe_package.js.map

package/dist/moe/moe_package.js.map

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

package/dist/moe/moe_trainer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * moe_trainer.ts — AdamW training loop for {@link SharedExpertMoE}.
+ *
+ * Makes "train your own Evermind AI" real: given labelled (input → target)
+ * samples, runs minibatch AdamW over the flat parameters with the load-balancing
+ * auxiliary loss mixed in (so the router spreads load instead of collapsing onto
+ * a few experts). Pure CPU, deterministic given a seeded model — the same loop a
+ * WebGPU optimiser kernel would accelerate.
+ */
+import { SharedExpertMoE } from "./moe_model.js";
+export interface MoESample {
+    input: ArrayLike<number>;
+    target: ArrayLike<number>;
+}
+export interface MoETrainOptions {
+    /** Learning rate. Default 0.01. */
+    lr?: number;
+    /** AdamW β1. Default 0.9. */
+    beta1?: number;
+    /** AdamW β2. Default 0.999. */
+    beta2?: number;
+    /** AdamW ε. Default 1e-8. */
+    eps?: number;
+    /** Decoupled weight decay. Default 0. */
+    weightDecay?: number;
+    /** Weight of the load-balancing auxiliary loss. Default 0.01. */
+    auxWeight?: number;
+    /** Minibatch size. Default = all samples (full batch). */
+    batchSize?: number;
+    /** Passes over the dataset. Default 1. */
+    epochs?: number;
+}
+export interface MoEEpochResult {
+    /** Mean per-sample task (MSE·½) loss over the epoch. */
+    loss: number;
+    /** Load-balancing auxiliary loss at the end of the epoch (≈1 balanced … E collapsed). */
+    auxLoss: number;
+}
+/**
+ * AdamW optimiser over a model's flat parameter list. State (m, v) is keyed by
+ * parameter index and persists across {@link step} calls.
+ */
+export declare class MoETrainer {
+    private readonly model;
+    private readonly adam;
+    private readonly opt;
+    constructor(model: SharedExpertMoE, options?: MoETrainOptions);
+    /** Train for the configured epochs. Returns the per-epoch loss history. */
+    fit(samples: MoESample[]): MoEEpochResult[];
+    private runEpoch;
+    private scaleGradients;
+}
+//# sourceMappingURL=moe_trainer.d.ts.map

package/dist/moe/moe_trainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moe_trainer.d.ts","sourceRoot":"","sources":["../../src/moe/moe_trainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACzB,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,UAAU;IAKnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;gBAG7B,KAAK,EAAE,eAAe,EACvC,OAAO,GAAE,eAAoB;IAe/B,2EAA2E;IAC3E,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,cAAc,EAAE;IAM3C,OAAO,CAAC,QAAQ;IAmDhB,OAAO,CAAC,cAAc;CAMvB"}

package/dist/moe/moe_trainer.js

@@ -0,0 +1,93 @@
+/**
+ * moe_trainer.ts — AdamW training loop for {@link SharedExpertMoE}.
+ *
+ * Makes "train your own Evermind AI" real: given labelled (input → target)
+ * samples, runs minibatch AdamW over the flat parameters with the load-balancing
+ * auxiliary loss mixed in (so the router spreads load instead of collapsing onto
+ * a few experts). Pure CPU, deterministic given a seeded model — the same loop a
+ * WebGPU optimiser kernel would accelerate.
+ */
+import { AdamW } from "../optim/adamw.js";
+/**
+ * AdamW optimiser over a model's flat parameter list. State (m, v) is keyed by
+ * parameter index and persists across {@link step} calls.
+ */
+export class MoETrainer {
+    model;
+    adam;
+    opt;
+    constructor(model, options = {}) {
+        this.model = model;
+        this.opt = {
+            lr: options.lr ?? 0.01,
+            beta1: options.beta1 ?? 0.9,
+            beta2: options.beta2 ?? 0.999,
+            eps: options.eps ?? 1e-8,
+            weightDecay: options.weightDecay ?? 0,
+            auxWeight: options.auxWeight ?? 0.01,
+            batchSize: options.batchSize ?? 0,
+            epochs: options.epochs ?? 1,
+        };
+        this.adam = new AdamW(model, this.opt);
+    }
+    /** Train for the configured epochs. Returns the per-epoch loss history. */
+    fit(samples) {
+        const history = [];
+        for (let e = 0; e < this.opt.epochs; e++)
+            history.push(this.runEpoch(samples));
+        return history;
+    }
+    runEpoch(samples) {
+        const batchSize = this.opt.batchSize > 0 ? this.opt.batchSize : samples.length;
+        const { numExperts, modelDim } = this.model.config;
+        let epochLoss = 0;
+        let lastAux = 0;
+        for (let start = 0; start < samples.length; start += batchSize) {
+            const batch = samples.slice(start, start + batchSize);
+            this.model.zeroGrad();
+            // Forward + task backward, retaining (x, probs) for the batch aux gradient.
+            const xs = [];
+            const probsList = [];
+            const counts = new Float32Array(numExperts);
+            let batchLoss = 0;
+            for (const s of batch) {
+                const f = this.model.forward(s.input);
+                const dOut = new Float32Array(modelDim);
+                for (let d = 0; d < modelDim; d++) {
+                    const diff = f.output[d] - (s.target[d] ?? 0);
+                    dOut[d] = diff;
+                    batchLoss += 0.5 * diff * diff;
+                }
+                this.model.backward(dOut, f.cache);
+                xs.push(f.cache.x);
+                probsList.push(f.route.probs);
+                for (const ex of f.route.experts)
+                    counts[ex] = counts[ex] + 1;
+            }
+            // Load-balancing aux gradient (batch-level): f = dispatch fractions.
+            const dispatched = counts.reduce((a, b) => a + b, 0) || 1;
+            const fVec = Float32Array.from(counts, (c) => c / dispatched);
+            const scale = (this.opt.auxWeight * numExperts) / batch.length;
+            for (let i = 0; i < xs.length; i++) {
+                this.model.auxGradStep(xs[i], probsList[i], fVec, scale);
+            }
+            // Average the task gradient over the batch, then AdamW step.
+            this.scaleGradients(1 / batch.length);
+            this.adam.step();
+            epochLoss += batchLoss;
+            lastAux = numExperts * fVec.reduce((sum, f, e) => sum + f * (probsList.length
+                ? probsList.reduce((s, p) => s + p[e], 0) / probsList.length
+                : 0), 0);
+        }
+        return { loss: epochLoss / Math.max(1, samples.length), auxLoss: lastAux };
+    }
+    scaleGradients(k) {
+        if (k === 1)
+            return;
+        for (const g of this.model.gradients()) {
+            for (let i = 0; i < g.data.length; i++)
+                g.data[i] = g.data[i] * k;
+        }
+    }
+}
+//# sourceMappingURL=moe_trainer.js.map

package/dist/moe/moe_trainer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moe_trainer.js","sourceRoot":"","sources":["../../src/moe/moe_trainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAiC1C;;;GAGG;AACH,MAAM,OAAO,UAAU;IAKF;IAJF,IAAI,CAAQ;IACZ,GAAG,CAA4B;IAEhD,YACmB,KAAsB,EACvC,UAA2B,EAAE;QADZ,UAAK,GAAL,KAAK,CAAiB;QAGvC,IAAI,CAAC,GAAG,GAAG;YACT,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,IAAI;YACtB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG;YAC3B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;YAC7B,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,IAAI;YACxB,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC;YACrC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI;YACpC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,CAAC;YACjC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,CAAC;SAC5B,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACzC,CAAC;IAED,2EAA2E;IAC3E,GAAG,CAAC,OAAoB;QACtB,MAAM,OAAO,GAAqB,EAAE,CAAC;QACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/E,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,QAAQ,CAAC,OAAoB;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QAC/E,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QACnD,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,IAAI,OAAO,GAAG,CAAC,CAAC;QAEhB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;YAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC;YACtD,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YAEtB,4EAA4E;YAC5E,MAAM,EAAE,GAAmB,EAAE,CAAC;YAC9B,MAAM,SAAS,GAAmB,EAAE,CAAC;YACrC,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,UAAU,CAAC,CAAC;YAC5C,IAAI,SAAS,GAAG,CAAC,CAAC;YAElB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACtB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;gBACtC,MAAM,IAAI,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;gBACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;oBAClC,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;oBAC/C,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;oBACf,SAAS,IAAI,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;gBACjC,CAAC;gBACD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;gBACnC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBACnB,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC9B,KAAK,MAAM,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO;oBAAE,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,CAAE,GAAG,CAAC,CAAC;YACjE,CAAC;YAED,qEAAqE;YACrE,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YAC1D,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC;YAC9D,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,UAAU,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;YAC/D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACnC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAE,EAAE,SAAS,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YAC7D,CAAC;YAED,6DAA6D;YAC7D,IAAI,CAAC,cAAc,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAEjB,SAAS,IAAI,SAAS,CAAC;YACvB,OAAO,GAAG,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM;gBAC3E,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM;gBAC7D,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACb,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC7E,CAAC;IAEO,cAAc,CAAC,CAAS;QAC9B,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO;QACpB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,CAAC;YACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE;gBAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;CACF"}

package/dist/optim/adamw.d.ts

@@ -0,0 +1,32 @@
+/**
+ * adamw.ts — AdamW optimiser over a model's flat parameter list.
+ *
+ * Shared by every CPU-reference trainer in the engine (MoE FFN, the full
+ * EvermindLM) so the optimiser maths lives in exactly one place. Operates on any
+ * object exposing index-aligned `parameters()` / `gradients()` Float32Arrays.
+ */
+export interface OptimParam {
+    data: Float32Array;
+}
+export interface OptimTarget {
+    parameters(): OptimParam[];
+    gradients(): OptimParam[];
+}
+export interface AdamWOptions {
+    lr?: number;
+    beta1?: number;
+    beta2?: number;
+    eps?: number;
+    weightDecay?: number;
+}
+export declare class AdamW {
+    private readonly target;
+    private readonly m;
+    private readonly v;
+    private t;
+    private readonly opt;
+    constructor(target: OptimTarget, options?: AdamWOptions);
+    /** One optimiser step from the currently-accumulated gradients. */
+    step(): void;
+}
+//# sourceMappingURL=adamw.d.ts.map

package/dist/optim/adamw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adamw.d.ts","sourceRoot":"","sources":["../../src/optim/adamw.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,IAAI,UAAU,EAAE,CAAC;IAC3B,SAAS,IAAI,UAAU,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,KAAK;IAOd,OAAO,CAAC,QAAQ,CAAC,MAAM;IANzB,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAsB;IACxC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAsB;IACxC,OAAO,CAAC,CAAC,CAAK;IACd,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;gBAG1B,MAAM,EAAE,WAAW,EACpC,OAAO,GAAE,YAAiB;IAe5B,mEAAmE;IACnE,IAAI,IAAI,IAAI;CAsBb"}

package/dist/optim/adamw.js

@@ -0,0 +1,52 @@
+/**
+ * adamw.ts — AdamW optimiser over a model's flat parameter list.
+ *
+ * Shared by every CPU-reference trainer in the engine (MoE FFN, the full
+ * EvermindLM) so the optimiser maths lives in exactly one place. Operates on any
+ * object exposing index-aligned `parameters()` / `gradients()` Float32Arrays.
+ */
+export class AdamW {
+    target;
+    m = [];
+    v = [];
+    t = 0;
+    opt;
+    constructor(target, options = {}) {
+        this.target = target;
+        this.opt = {
+            lr: options.lr ?? 0.01,
+            beta1: options.beta1 ?? 0.9,
+            beta2: options.beta2 ?? 0.999,
+            eps: options.eps ?? 1e-8,
+            weightDecay: options.weightDecay ?? 0,
+        };
+        for (const p of target.parameters()) {
+            this.m.push(new Float32Array(p.data.length));
+            this.v.push(new Float32Array(p.data.length));
+        }
+    }
+    /** One optimiser step from the currently-accumulated gradients. */
+    step() {
+        this.t++;
+        const { lr, beta1, beta2, eps, weightDecay } = this.opt;
+        const params = this.target.parameters();
+        const grads = this.target.gradients();
+        const bc1 = 1 - Math.pow(beta1, this.t);
+        const bc2 = 1 - Math.pow(beta2, this.t);
+        for (let p = 0; p < params.length; p++) {
+            const w = params[p].data;
+            const g = grads[p].data;
+            const m = this.m[p];
+            const v = this.v[p];
+            for (let i = 0; i < w.length; i++) {
+                const gi = g[i];
+                m[i] = beta1 * m[i] + (1 - beta1) * gi;
+                v[i] = beta2 * v[i] + (1 - beta2) * gi * gi;
+                const mh = m[i] / bc1;
+                const vh = v[i] / bc2;
+                w[i] = w[i] - lr * (mh / (Math.sqrt(vh) + eps) + weightDecay * w[i]);
+            }
+        }
+    }
+}
+//# sourceMappingURL=adamw.js.map

package/dist/optim/adamw.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory-engine",
-  "version": "2026.6.20",
+  "version": "2026.6.28",
   "description": "BuilderForce Agent Memory — engine layer. TypeScript/WGSL Mamba SSM kernels, model blocks, autograd, training, and BPE tokenizer (zero runtime deps, WebGPU-native).",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/index.ts

@@ -15,6 +15,34 @@ export { AttentionBlock } from './model/attention_block.js';
 // Deprecated alias — kept until 3.0.0
 export { MambaBlock } from './model/mamba1_block.js';
 
+// ── Mixture-of-Experts (shared-expert hybrid sparsity) ─────────────────────────
+export {
+    SharedExpertMoE,
+    LoadBalanceAccumulator,
+    DEFAULT_MOE_CONFIG,
+    DEFAULT_MOE_SEED,
+    MoETrainer,
+    EvermindModelPackage,
+} from './moe/index.js';
+export type {
+    MoEConfig,
+    MoEParam,
+    RouteResult,
+    MoESample,
+    MoETrainOptions,
+    MoEEpochResult,
+    EvermindModelManifest,
+    EvermindModelCard,
+    PackageMeta,
+    ValidationResult,
+} from './moe/index.js';
+
+// ── EvermindLM (the generative model) + AdamW ──────────────────────────────────
+export { EvermindLM, EvermindLMTrainer, DEFAULT_LM_CONFIG, DEFAULT_LM_SEED } from './lm/index.js';
+export type { EvermindLMConfig, LMGenerateOptions, TextCodec } from './lm/index.js';
+export { AdamW } from './optim/adamw.js';
+export type { AdamWOptions, OptimTarget, OptimParam } from './optim/adamw.js';
+
 // ── Training ──────────────────────────────────────────────────────────────────
 
 export { MambaTrainer } from './training/trainer.js';
@@ -108,6 +136,37 @@ export { COMPLEX_SSD_FORWARD_WGSL, COMPLEX_SSD_BACKWARD_WGSL }
 export { ATTENTION_FORWARD_WGSL, ATTENTION_BACKWARD_WGSL, SOFTMAX_WGSL }
     from './kernels/attention.js';
 
+// ── Limbic system (trainable affective dynamics) ──────────────────────────────
+
+export {
+    REGION,
+    LIMBIC_DIM,
+    LIMBIC_DIM_NAMES,
+    LIMBIC_STATE_DIM,
+    LIMBIC_BOUNDS,
+    NEUTRAL_STATE,
+    clampDim,
+    clampState,
+    neutralState,
+    stateToRecord,
+    recordToState,
+    LimbicModel,
+    DEFAULT_LIMBIC_CONFIG,
+    DEFAULT_LIMBIC_SEED,
+    LimbicTrainer,
+} from './limbic/index.js';
+export type {
+    Region,
+    LimbicDimName,
+    LimbicModelConfig,
+    LimbicForward,
+    LimbicParam,
+    LimbicSample,
+    LimbicTrainOptions,
+} from './limbic/index.js';
+
+export { LIMBIC_AFFECT_WGSL } from './kernels/limbic_affect.js';
+
 // ── Version ───────────────────────────────────────────────────────────────────
 
 export const VERSION     = '2.0.0';

package/src/kernels/limbic_affect.ts

@@ -0,0 +1,74 @@
+// Limbic Affect WGSL Kernel
+//
+// One forward step of the limbic model's recurrent affect core, run on the GPU.
+// Given the previous hidden state, previous affective state, and an experience
+// embedding, it produces the next hidden state and a bounded affect *delta*.
+//
+// This mirrors the CPU reference in limbic/limbic_model.ts exactly (same math):
+//   pre[j]  = Σ_i Win[j,i]·x[i] + Σ_k Ws[j,k]·s[k]
+//   a[j]    = sigmoid(A[j])                       // per-channel recurrence gate
+//   h'[j]   = a[j]·h[j] + (1-a[j])·tanh(pre[j])   // SSM-style leak/input
+//   Δ[k]    = tanh( Σ_j Wout[k,j]·h'[j] + b[k] )  // bounded affect change
+//
+// hidden_dim is assumed ≤ 64 (the limbic head is tiny — the heavy lifting is in
+// the hippocampus SSM that produces the experience embedding). Reward is NOT
+// computed here: it is only needed during training, which runs the CPU backward
+// path; the per-turn inference step only needs Δ and the next hidden state.
+
+export const LIMBIC_AFFECT_WGSL: string = /* wgsl */ `
+
+struct Dims {
+    input_dim  : u32,
+    hidden_dim : u32,
+    state_dim  : u32,
+    _pad       : u32,
+};
+
+@group(0) @binding(0)  var<uniform>             dims        : Dims;
+@group(0) @binding(1)  var<storage, read>       win         : array<f32>;  // hidden*input
+@group(0) @binding(2)  var<storage, read>       ws          : array<f32>;  // hidden*state
+@group(0) @binding(3)  var<storage, read>       a_logit     : array<f32>;  // hidden
+@group(0) @binding(4)  var<storage, read>       wout_state  : array<f32>;  // state*hidden
+@group(0) @binding(5)  var<storage, read>       bout_state  : array<f32>;  // state
+@group(0) @binding(6)  var<storage, read>       x_in        : array<f32>;  // input
+@group(0) @binding(7)  var<storage, read>       h_prev      : array<f32>;  // hidden
+@group(0) @binding(8)  var<storage, read>       s_prev      : array<f32>;  // state
+@group(0) @binding(9)  var<storage, read_write> h_out       : array<f32>;  // hidden
+@group(0) @binding(10) var<storage, read_write> delta_out   : array<f32>;  // state
+
+var<workgroup> hbuf : array<f32, 64>;
+
+// Single-workgroup dispatch: (1, 1, 1) with workgroup_size 64.
+@compute @workgroup_size(64, 1, 1)
+fn affect_step(
+    @builtin(local_invocation_id) lid : vec3<u32>,
+) {
+    let j = lid.x;
+
+    // Pass 1: recurrent hidden update (one thread per hidden channel).
+    if (j < dims.hidden_dim) {
+        var pre : f32 = 0.0;
+        for (var i : u32 = 0u; i < dims.input_dim; i = i + 1u) {
+            pre = pre + win[j * dims.input_dim + i] * x_in[i];
+        }
+        for (var k : u32 = 0u; k < dims.state_dim; k = k + 1u) {
+            pre = pre + ws[j * dims.state_dim + k] * s_prev[k];
+        }
+        let a  = 1.0 / (1.0 + exp(-a_logit[j]));
+        let hn = a * h_prev[j] + (1.0 - a) * tanh(pre);
+        hbuf[j]  = hn;
+        h_out[j] = hn;
+    }
+
+    workgroupBarrier();
+
+    // Pass 2: bounded affect delta (one thread per state dim).
+    if (j < dims.state_dim) {
+        var acc : f32 = bout_state[j];
+        for (var m : u32 = 0u; m < dims.hidden_dim; m = m + 1u) {
+            acc = acc + wout_state[j * dims.hidden_dim + m] * hbuf[m];
+        }
+        delta_out[j] = tanh(acc);
+    }
+}
+`;

package/src/limbic/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Limbic system – trainable affective/motivational dynamics for agents.
+ *
+ * The dynamic counterpart to the (static) psychometric personality: where
+ * personality sets the homeostatic setpoints, the limbic model learns — in
+ * WebGPU — how an agent's affective state moves in response to experience.
+ */
+
+export {
+  REGION,
+  LIMBIC_DIM,
+  LIMBIC_DIM_NAMES,
+  LIMBIC_STATE_DIM,
+  LIMBIC_BOUNDS,
+  NEUTRAL_STATE,
+  clampDim,
+  clampState,
+  neutralState,
+  stateToRecord,
+  recordToState,
+} from "./regions.js";
+export type { Region, LimbicDimName } from "./regions.js";
+
+export { LimbicModel, DEFAULT_LIMBIC_CONFIG, DEFAULT_LIMBIC_SEED } from "./limbic_model.js";
+export type { LimbicModelConfig, LimbicForward, LimbicParam } from "./limbic_model.js";
+
+export { LimbicTrainer } from "./limbic_trainer.js";
+export type { LimbicSample, LimbicTrainOptions } from "./limbic_trainer.js";