@seanhogg/builderforce-memory-engine 2026.6.20 → 2026.6.28

package/dist/limbic/limbic_trainer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * limbic_trainer.ts – LimbicTrainer: gradient-based training for the LimbicModel.
+ *
+ * Trains the affect head to predict affect deltas and reward from
+ * (experience embedding, current state) pairs, using 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 (real WebGPU training); with
+ * no device it uses a numerically-equivalent CPU AdamW so training works
+ * everywhere (CI, Node without @webgpu/node, etc.).
+ *
+ * The objective is MSE (regression), not the cross-entropy used by the
+ * language-model {@link MambaTrainer} — a limbic experience has continuous
+ * targets, not a next-token distribution.
+ */
+import type { LimbicModel } from "./limbic_model.js";
+/** One training example: an experience and the affect change it should produce. */
+export interface LimbicSample {
+    /** Experience embedding (length = model.inputDim). */
+    input: ArrayLike<number>;
+    /** Affective state at the time of the experience (length = model.stateDim). */
+    state: ArrayLike<number>;
+    /** Observed affect delta target in (-1, 1) per state dim (length = model.stateDim). */
+    deltaTarget: ArrayLike<number>;
+    /** Observed scalar reward for the experience. */
+    reward: number;
+}
+export interface LimbicTrainOptions {
+    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;
+    onEpochEnd?: ((epoch: number, loss: number) => void) | null;
+}
+export declare class LimbicTrainer {
+    readonly model: LimbicModel;
+    readonly device: GPUDevice | null;
+    private _moments;
+    private _step;
+    private readonly _adamwPipeline;
+    constructor(model: LimbicModel, device?: GPUDevice | null);
+    /** Whether the optimiser step runs on the GPU. */
+    get gpuTraining(): boolean;
+    private _initMoments;
+    /**
+     * Train on a batch of samples for `epochs` passes. Returns the per-epoch mean
+     * loss (monotonically decreasing on a learnable mapping). Full-batch: grads
+     * accumulate across the whole sequence (recurrent hidden carried, reset per
+     * epoch), are averaged, clipped, then applied once per epoch.
+     */
+    train(samples: LimbicSample[], opts?: LimbicTrainOptions): Promise<number[]>;
+    /** Mean MSE loss over samples (no weight update). Hidden resets per sample. */
+    evaluate(samples: LimbicSample[]): number;
+    private _clipGradients;
+    private _adamwStepCpu;
+    /** AdamW on the GPU via the shared WEIGHT_UPDATE_WGSL kernel. Awaited per step. */
+    private _adamwStepGpu;
+}
+//# sourceMappingURL=limbic_trainer.d.ts.map

package/dist/limbic/limbic_trainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limbic_trainer.d.ts","sourceRoot":"","sources":["../../src/limbic/limbic_trainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,mBAAmB,CAAC;AAElE,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACzB,+EAA+E;IAC/E,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACzB,uFAAuF;IACvF,WAAW,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,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,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7D;AAuBD,qBAAa,aAAa;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,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;gBAE/C,KAAK,EAAE,WAAW,EAAE,MAAM,GAAE,SAAS,GAAG,IAAW;IAQ/D,kDAAkD;IAClD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,OAAO,CAAC,YAAY;IAQpB;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA6DtF,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM;IAkBzC,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,aAAa;IAqBrB,mFAAmF;YACrE,aAAa;CAkC5B"}

package/dist/limbic/limbic_trainer.js

@@ -0,0 +1,172 @@
+/**
+ * limbic_trainer.ts – LimbicTrainer: gradient-based training for the LimbicModel.
+ *
+ * Trains the affect head to predict affect deltas and reward from
+ * (experience embedding, current state) pairs, using 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 (real WebGPU training); with
+ * no device it uses a numerically-equivalent CPU AdamW so training works
+ * everywhere (CI, Node without @webgpu/node, etc.).
+ *
+ * The objective is MSE (regression), not the cross-entropy used by the
+ * language-model {@link MambaTrainer} — a limbic experience has continuous
+ * targets, not a next-token distribution.
+ */
+import { createUniformBuffer, createStorageBuffer, createComputePipeline, createBindGroup, dispatchKernel, readBuffer, cdiv, } from "../utils/gpu_utils.js";
+import { WEIGHT_UPDATE_WGSL } from "../kernels/weight_update.js";
+function packAdamParams(numElements, lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t) {
+    const buf = new ArrayBuffer(32);
+    new Uint32Array(buf, 0, 1).set([numElements]);
+    new Float32Array(buf, 4, 7).set([lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t]);
+    return buf;
+}
+export class LimbicTrainer {
+    model;
+    device;
+    _moments = null;
+    _step = 0;
+    _adamwPipeline;
+    constructor(model, device = null) {
+        this.model = model;
+        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.model.parameters().map((p) => ({
+            m: new Float32Array(p.numel),
+            v: new Float32Array(p.numel),
+        }));
+    }
+    /**
+     * Train on a batch of samples for `epochs` passes. Returns the per-epoch mean
+     * loss (monotonically decreasing on a learnable mapping). Full-batch: grads
+     * accumulate across the whole sequence (recurrent hidden carried, reset per
+     * epoch), are averaged, clipped, then applied once per epoch.
+     */
+    async train(samples, opts = {}) {
+        if (samples.length === 0)
+            throw new Error("LimbicTrainer.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.model.zeroGrad();
+            let epochLoss = 0;
+            // Each sample is one experience appraisal: cross-experience memory flows
+            // through the affective state `s` (fed back by the runtime), not through
+            // the hidden scratch `h`, so the hidden state resets per sample. This also
+            // makes BPTT(1) exact — there is no truncated carry.
+            for (const s of samples) {
+                const { loss } = this.model.backwardStep(s.input, this.model.initHidden(), s.state, s.deltaTarget, s.reward);
+                epochLoss += loss;
+            }
+            // Average gradients over the batch.
+            const grads = this.model.gradients();
+            const invN = 1 / samples.length;
+            for (const g of grads) {
+                for (let i = 0; i < g.data.length; i++)
+                    g.data[i] *= invN;
+            }
+            this._clipGradients(grads, maxGradNorm);
+            this._step++;
+            const beta1_t = Math.pow(beta1, this._step);
+            const beta2_t = Math.pow(beta2, this._step);
+            const hp = { learningRate, weightDecay, beta1, beta2, eps, beta1_t, beta2_t };
+            if (this.gpuTraining) {
+                await this._adamwStepGpu(grads, hp);
+            }
+            else {
+                this._adamwStepCpu(grads, hp);
+            }
+            const avg = epochLoss / samples.length;
+            losses.push(avg);
+            if (onEpochEnd)
+                onEpochEnd(epoch + 1, avg);
+        }
+        return losses;
+    }
+    /** Mean MSE loss over samples (no weight update). Hidden resets per sample. */
+    evaluate(samples) {
+        if (samples.length === 0)
+            return 0;
+        let total = 0;
+        const { rewardWeight } = this.model.config;
+        for (const s of samples) {
+            const f = this.model.forward(s.input, this.model.initHidden(), s.state);
+            let loss = 0;
+            for (let k = 0; k < f.delta.length; k++) {
+                const d = f.delta[k] - (s.deltaTarget[k] ?? 0);
+                loss += 0.5 * d * d;
+            }
+            const rd = f.reward - s.reward;
+            loss += 0.5 * rewardWeight * rd * rd;
+            total += loss;
+        }
+        return total / samples.length;
+    }
+    _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;
+        }
+    }
+    _adamwStepCpu(grads, hp) {
+        const params = this.model.parameters();
+        const { learningRate: lr, weightDecay: wd, beta1, beta2, eps, beta1_t, beta2_t } = hp;
+        for (let pi = 0; pi < params.length; pi++) {
+            const p = params[pi].data;
+            const g = grads[pi].data;
+            const mom = this._moments[pi];
+            for (let i = 0; i < p.length; i++) {
+                const gi = g[i];
+                mom.m[i] = beta1 * mom.m[i] + (1 - beta1) * gi;
+                mom.v[i] = beta2 * mom.v[i] + (1 - beta2) * gi * gi;
+                const mHat = mom.m[i] / (1 - beta1_t);
+                const vHat = mom.v[i] / (1 - beta2_t);
+                p[i] = p[i] * (1 - lr * wd) - (lr * mHat) / (Math.sqrt(vHat) + eps);
+            }
+        }
+    }
+    /** AdamW on the GPU via the shared WEIGHT_UPDATE_WGSL kernel. Awaited per step. */
+    async _adamwStepGpu(grads, hp) {
+        const device = this.device;
+        const pipeline = this._adamwPipeline;
+        const params = this.model.parameters();
+        const { learningRate: lr, weightDecay: wd, beta1, beta2, eps, beta1_t, beta2_t } = hp;
+        for (let pi = 0; pi < params.length; pi++) {
+            const p = params[pi];
+            const mom = this._moments[pi];
+            const paramBuf = createStorageBuffer(device, p.data, true);
+            const gradBuf = createStorageBuffer(device, grads[pi].data, false);
+            const mBuf = createStorageBuffer(device, mom.m, true);
+            const vBuf = createStorageBuffer(device, mom.v, true);
+            const uni = createUniformBuffer(device, packAdamParams(p.numel, lr, beta1, beta2, eps, wd, beta1_t, beta2_t));
+            const bg = createBindGroup(device, pipeline, [uni, paramBuf, gradBuf, mBuf, vBuf]);
+            dispatchKernel(device, pipeline, bg, [cdiv(p.numel, 256), 1, 1]);
+            p.data.set((await readBuffer(device, paramBuf, p.numel * 4)).subarray(0, p.numel));
+            mom.m.set((await readBuffer(device, mBuf, p.numel * 4)).subarray(0, p.numel));
+            mom.v.set((await readBuffer(device, vBuf, p.numel * 4)).subarray(0, p.numel));
+            paramBuf.destroy();
+            gradBuf.destroy();
+            mBuf.destroy();
+            vBuf.destroy();
+            uni.destroy();
+        }
+    }
+}
+//# sourceMappingURL=limbic_trainer.js.map

package/dist/limbic/limbic_trainer.js.map

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

package/dist/limbic/regions.d.ts

@@ -0,0 +1,79 @@
+/**
+ * regions.ts – Limbic-system region map and affective state schema.
+ *
+ * The limbic model is the *dynamic* affective/motivational layer that rides on
+ * top of the (static) psychometric personality. Where the hippocampus
+ * (HybridMambaModel + MemoryStore) holds *what the agent knows*, the limbic
+ * model holds *how the agent currently feels and what it is driven toward* —
+ * and learns the dynamics of that, in WebGPU, from experience.
+ *
+ * This file is the single source of truth for the affective state vector that
+ * every other limbic module (model, trainer, runtime service) indexes into.
+ * Keep the dimension ids in sync with the runtime compiler in
+ * `agent-runtime/src/builderforce/limbic.ts` — the two are coupled solely by
+ * these string ids and the {@link LIMBIC_DIM} indices.
+ *
+ * Region → state mapping (mirrors the labelled diagram):
+ *   • Amygdala      → salience / threat appraisal → drives valence + arousal
+ *   • Hypothalamus  → homeostatic drives (curiosity, caution, effort, social)
+ *   • Thalamus      → attention gate (how much incoming signal is admitted)
+ *   • Basal ganglia → action selection bias (explore vs. exploit)
+ *   • Hippocampus   → reused (existing SSM memory); feeds the experience input
+ */
+/** The five modelled limbic regions. Hippocampus is reused, not re-modelled. */
+export declare const REGION: {
+    readonly amygdala: "amygdala";
+    readonly hypothalamus: "hypothalamus";
+    readonly thalamus: "thalamus";
+    readonly basalGanglia: "basal_ganglia";
+    readonly hippocampus: "hippocampus";
+};
+export type Region = (typeof REGION)[keyof typeof REGION];
+/**
+ * Canonical indices into the affective state vector. The vector is a dense
+ * Float32Array of length {@link LIMBIC_STATE_DIM}. Core affect (valence,
+ * arousal) is the 2D summary; the remaining dims are the per-region drives the
+ * agent's behaviour is modulated by.
+ */
+export declare const LIMBIC_DIM: {
+    /** Core affect — pleasantness. Range [-1, +1] (negative .. positive). */
+    readonly valence: 0;
+    /** Core affect — activation. Range [0, 1] (calm .. activated). */
+    readonly arousal: 1;
+    /** Hypothalamus drive — appetite for novelty/exploration. Range [0, 1]. */
+    readonly driveCuriosity: 2;
+    /** Hypothalamus drive — appetite for safety/guardrails. Range [0, 1]. */
+    readonly driveCaution: 3;
+    /** Hypothalamus drive — available energy. Range [0, 1] (fatigued .. fresh). */
+    readonly driveEffort: 4;
+    /** Hypothalamus drive — appetite for communication/collaboration. Range [0, 1]. */
+    readonly driveSocial: 5;
+    /** Thalamus — attention gain on incoming signal. Range [0, 1]. */
+    readonly attention: 6;
+    /** Basal ganglia — explore(1) vs. exploit(0) action-selection bias. Range [0, 1]. */
+    readonly exploration: 7;
+};
+export type LimbicDimName = keyof typeof LIMBIC_DIM;
+/** Length of the affective state vector. */
+export declare const LIMBIC_STATE_DIM = 8;
+/** Ordered dim names, index-aligned with {@link LIMBIC_DIM}. */
+export declare const LIMBIC_DIM_NAMES: LimbicDimName[];
+/** Inclusive [min, max] bounds per state dim, index-aligned. Valence is signed. */
+export declare const LIMBIC_BOUNDS: ReadonlyArray<readonly [number, number]>;
+/**
+ * Neutral resting state — the default homeostatic setpoint before personality
+ * pulls it anywhere. Calm, mildly positive, balanced drives, full attention,
+ * slightly exploit-biased.
+ */
+export declare const NEUTRAL_STATE: ReadonlyArray<number>;
+/** Clamp a single state dim to its bounds. */
+export declare function clampDim(index: number, value: number): number;
+/** Clamp a whole state vector in place and return it. */
+export declare function clampState(state: Float32Array): Float32Array;
+/** A fresh neutral state vector. */
+export declare function neutralState(): Float32Array;
+/** Build a labelled record from a dense state vector (for logging / transport). */
+export declare function stateToRecord(state: ArrayLike<number>): Record<LimbicDimName, number>;
+/** Build a dense state vector from a (possibly partial) labelled record. */
+export declare function recordToState(rec: Partial<Record<LimbicDimName, number>>): Float32Array;
+//# sourceMappingURL=regions.d.ts.map

package/dist/limbic/regions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regions.d.ts","sourceRoot":"","sources":["../../src/limbic/regions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,gFAAgF;AAChF,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC;AACX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,UAAU;IACrB,yEAAyE;;IAEzE,kEAAkE;;IAElE,2EAA2E;;IAE3E,yEAAyE;;IAEzE,+EAA+E;;IAE/E,mFAAmF;;IAEnF,kEAAkE;;IAElE,qFAAqF;;CAE7E,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,UAAU,CAAC;AAEpD,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,EAAE,aAAa,EAS3C,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CASlE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,MAAM,CAS/C,CAAC;AAEF,8CAA8C;AAC9C,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAK5D;AAED,oCAAoC;AACpC,wBAAgB,YAAY,IAAI,YAAY,CAE3C;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAMrF;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,GAAG,YAAY,CAOvF"}

package/dist/limbic/regions.js

@@ -0,0 +1,132 @@
+/**
+ * regions.ts – Limbic-system region map and affective state schema.
+ *
+ * The limbic model is the *dynamic* affective/motivational layer that rides on
+ * top of the (static) psychometric personality. Where the hippocampus
+ * (HybridMambaModel + MemoryStore) holds *what the agent knows*, the limbic
+ * model holds *how the agent currently feels and what it is driven toward* —
+ * and learns the dynamics of that, in WebGPU, from experience.
+ *
+ * This file is the single source of truth for the affective state vector that
+ * every other limbic module (model, trainer, runtime service) indexes into.
+ * Keep the dimension ids in sync with the runtime compiler in
+ * `agent-runtime/src/builderforce/limbic.ts` — the two are coupled solely by
+ * these string ids and the {@link LIMBIC_DIM} indices.
+ *
+ * Region → state mapping (mirrors the labelled diagram):
+ *   • Amygdala      → salience / threat appraisal → drives valence + arousal
+ *   • Hypothalamus  → homeostatic drives (curiosity, caution, effort, social)
+ *   • Thalamus      → attention gate (how much incoming signal is admitted)
+ *   • Basal ganglia → action selection bias (explore vs. exploit)
+ *   • Hippocampus   → reused (existing SSM memory); feeds the experience input
+ */
+/** The five modelled limbic regions. Hippocampus is reused, not re-modelled. */
+export const REGION = {
+    amygdala: "amygdala",
+    hypothalamus: "hypothalamus",
+    thalamus: "thalamus",
+    basalGanglia: "basal_ganglia",
+    hippocampus: "hippocampus",
+};
+/**
+ * Canonical indices into the affective state vector. The vector is a dense
+ * Float32Array of length {@link LIMBIC_STATE_DIM}. Core affect (valence,
+ * arousal) is the 2D summary; the remaining dims are the per-region drives the
+ * agent's behaviour is modulated by.
+ */
+export const LIMBIC_DIM = {
+    /** Core affect — pleasantness. Range [-1, +1] (negative .. positive). */
+    valence: 0,
+    /** Core affect — activation. Range [0, 1] (calm .. activated). */
+    arousal: 1,
+    /** Hypothalamus drive — appetite for novelty/exploration. Range [0, 1]. */
+    driveCuriosity: 2,
+    /** Hypothalamus drive — appetite for safety/guardrails. Range [0, 1]. */
+    driveCaution: 3,
+    /** Hypothalamus drive — available energy. Range [0, 1] (fatigued .. fresh). */
+    driveEffort: 4,
+    /** Hypothalamus drive — appetite for communication/collaboration. Range [0, 1]. */
+    driveSocial: 5,
+    /** Thalamus — attention gain on incoming signal. Range [0, 1]. */
+    attention: 6,
+    /** Basal ganglia — explore(1) vs. exploit(0) action-selection bias. Range [0, 1]. */
+    exploration: 7,
+};
+/** Length of the affective state vector. */
+export const LIMBIC_STATE_DIM = 8;
+/** Ordered dim names, index-aligned with {@link LIMBIC_DIM}. */
+export const LIMBIC_DIM_NAMES = [
+    "valence",
+    "arousal",
+    "driveCuriosity",
+    "driveCaution",
+    "driveEffort",
+    "driveSocial",
+    "attention",
+    "exploration",
+];
+/** Inclusive [min, max] bounds per state dim, index-aligned. Valence is signed. */
+export const LIMBIC_BOUNDS = [
+    [-1, 1], // valence
+    [0, 1], // arousal
+    [0, 1], // driveCuriosity
+    [0, 1], // driveCaution
+    [0, 1], // driveEffort
+    [0, 1], // driveSocial
+    [0, 1], // attention
+    [0, 1], // exploration
+];
+/**
+ * Neutral resting state — the default homeostatic setpoint before personality
+ * pulls it anywhere. Calm, mildly positive, balanced drives, full attention,
+ * slightly exploit-biased.
+ */
+export const NEUTRAL_STATE = [
+    0.0, // valence
+    0.2, // arousal
+    0.5, // driveCuriosity
+    0.5, // driveCaution
+    0.8, // driveEffort
+    0.5, // driveSocial
+    0.7, // attention
+    0.5, // exploration (centred → resting state is behaviourally inert)
+];
+/** Clamp a single state dim to its bounds. */
+export function clampDim(index, value) {
+    const b = LIMBIC_BOUNDS[index];
+    if (!b)
+        return value;
+    if (Number.isNaN(value))
+        return b[0];
+    return Math.max(b[0], Math.min(b[1], value));
+}
+/** Clamp a whole state vector in place and return it. */
+export function clampState(state) {
+    for (let i = 0; i < state.length && i < LIMBIC_STATE_DIM; i++) {
+        state[i] = clampDim(i, state[i]);
+    }
+    return state;
+}
+/** A fresh neutral state vector. */
+export function neutralState() {
+    return Float32Array.from(NEUTRAL_STATE);
+}
+/** Build a labelled record from a dense state vector (for logging / transport). */
+export function stateToRecord(state) {
+    const out = {};
+    for (let i = 0; i < LIMBIC_DIM_NAMES.length; i++) {
+        out[LIMBIC_DIM_NAMES[i]] = state[i] ?? 0;
+    }
+    return out;
+}
+/** Build a dense state vector from a (possibly partial) labelled record. */
+export function recordToState(rec) {
+    const s = neutralState();
+    for (let i = 0; i < LIMBIC_DIM_NAMES.length; i++) {
+        const v = rec[LIMBIC_DIM_NAMES[i]];
+        if (typeof v === "number" && !Number.isNaN(v))
+            s[i] = clampDim(i, v);
+    }
+    return s;
+}
+//# sourceMappingURL=regions.js.map

package/dist/limbic/regions.js.map

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

package/dist/lm/evermind_lm.d.ts

@@ -0,0 +1,148 @@
+/**
+ * evermind_lm.ts — EvermindLM: a small but complete generative language model.
+ *
+ * This is what turns a trained checkpoint into an *AI that generates text* (the
+ * thing a marketplace buyer actually runs). Architecture (Mamba-flavoured, the
+ * minimal exact-gradient CPU reference):
+ *
+ *   x_t = Embed[token_t]
+ *   per layer:
+ *     x_t += DepthwiseCausalConv(x)_t            // temporal mixing (short conv)
+ *     x_t += SharedExpertMoE(x_t)                // per-position channel mixing (sparse)
+ *   logits_t = x_t · Embedᵀ                       // tied output head
+ *
+ * The token mixer is a depthwise causal convolution (each channel sees a short
+ * window of its own past — Mamba's pre-conv) and the channel mixer is the
+ * shared-expert MoE, so the model is genuinely sparse. Embeddings are tied
+ * (input lookup == output head), which the gradient code accounts for.
+ *
+ * Pure CPU, exact forward + backward (finite-difference checked), reusing the
+ * engine's MoE, cross-entropy, and AdamW. The WGSL/WebGPU path is a future
+ * acceleration with the same shapes.
+ */
+import { type AdamWOptions } from "../optim/adamw.js";
+export interface EvermindLMConfig {
+    /** Vocabulary size. */
+    vocabSize: number;
+    /** Model (channel) dimension. Default 64. */
+    dModel: number;
+    /** Number of (conv + MoE) blocks. Default 2. */
+    numLayers: number;
+    /** Causal conv kernel width. Default 3. */
+    convKernel: number;
+    /** Hidden width of each MoE expert FFN. Default 2·dModel. */
+    hiddenDim: number;
+    /** Routed experts per MoE layer. Default 4. */
+    numExperts: number;
+    /** Experts activated per token. Default 2. */
+    topK: number;
+    /** Deterministic init seed. */
+    seed?: number;
+}
+export declare const DEFAULT_LM_CONFIG: Required<Omit<EvermindLMConfig, "seed" | "vocabSize">>;
+export declare const DEFAULT_LM_SEED = 1163283533;
+interface MoECacheLike {
+    x: Float32Array;
+    route: {
+        experts: number[];
+        gates: number[];
+        probs: Float32Array;
+    };
+    sharedPre: Float32Array;
+    sharedH: Float32Array;
+    expertOut: Float32Array[];
+    expertPre: Float32Array[];
+    expertH: Float32Array[];
+}
+interface LayerCache {
+    layerIn: Float32Array[];
+    normedConv: Float32Array[];
+    rmsConv: number[];
+    afterConv: Float32Array[];
+    rmsMoe: number[];
+    moeCache: MoECacheLike[];
+}
+interface ForwardCache {
+    tokens: number[];
+    layers: LayerCache[];
+    finalX: Float32Array[];
+}
+/** A tokenizer the LM can read/write text through (the engine's `BPETokenizer` fits). */
+export interface TextCodec {
+    encode(text: string): number[];
+    decode(ids: number[]): string;
+}
+export interface LMGenerateOptions {
+    maxNewTokens: number;
+    /** Sampling temperature; ≤0 ⇒ greedy argmax. Default 0 (greedy). */
+    temperature?: number;
+    /** Deterministic sampler seed (only used when temperature > 0). */
+    seed?: number;
+    /** Stop generating when this token id is produced. */
+    stopToken?: number;
+}
+export declare class EvermindLM {
+    readonly config: Required<Omit<EvermindLMConfig, "seed">>;
+    /** Tied token embedding / output head: vocabSize × dModel (row-major). */
+    emb: Float32Array;
+    private gEmb;
+    /** Per-layer depthwise causal conv kernels: dModel × convKernel. */
+    private readonly conv;
+    private readonly gConv;
+    /** Per-layer pre-conv / pre-MoE RMSNorm gains (dModel each). */
+    private readonly nConv;
+    private readonly gNConv;
+    private readonly nMoe;
+    private readonly gNMoe;
+    /** Per-layer channel mixer. */
+    private readonly moe;
+    constructor(config: EvermindLMConfig);
+    /** Run the model over a token sequence; returns per-position logits + a cache. */
+    forward(tokens: number[]): {
+        logits: Float32Array[];
+        cache: ForwardCache;
+    };
+    /**
+     * Next-token cross-entropy over the sequence (predict tokens[t+1] from
+     * position t), accumulating exact gradients. Returns the mean loss. Call
+     * {@link zeroGrad} before and an optimiser step after.
+     */
+    lossAndBackward(tokens: number[]): number;
+    /**
+     * Text-level generation: encode the prompt, generate, decode. `codec` is any
+     * tokenizer exposing encode/decode (the engine's `BPETokenizer` satisfies it),
+     * so the LM consumes and emits real text rather than raw token ids. The model's
+     * `vocabSize` must match the codec's vocabulary.
+     */
+    generateText(prompt: string, codec: TextCodec, opts: LMGenerateOptions): string;
+    /** Greedy / temperature-sampled autoregressive generation. Returns NEW token ids. */
+    generate(prompt: number[], opts: LMGenerateOptions): number[];
+    /** All trainable parameters as {data} (AdamW-compatible), canonical order. */
+    parameters(): {
+        data: Float32Array;
+    }[];
+    /** Gradient buffers, index-aligned with {@link parameters}. */
+    gradients(): {
+        data: Float32Array;
+    }[];
+    zeroGrad(): void;
+    /** Serialise to an "EVL0" binary (fp16 or f32), params in {@link parameters} order. */
+    exportWeights(opts?: {
+        fp16?: boolean;
+    }): ArrayBuffer;
+    /** Load weights from an "EVL0" binary. Validates magic + dims. */
+    loadWeights(buffer: ArrayBuffer): void;
+}
+/** Minimal sequence trainer: AdamW over next-token cross-entropy. */
+export declare class EvermindLMTrainer {
+    private readonly model;
+    private readonly opts;
+    private readonly adam;
+    constructor(model: EvermindLM, opts?: AdamWOptions & {
+        epochs?: number;
+    });
+    /** Train on a set of token sequences; returns per-epoch mean loss. */
+    fit(sequences: number[][]): number[];
+}
+export {};
+//# sourceMappingURL=evermind_lm.d.ts.map

package/dist/lm/evermind_lm.d.ts.map

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