@seanhogg/builderforce-memory 2026.6.18

package/dist/session/presets.js

@@ -0,0 +1,91 @@
+/**
+ * presets.ts – Model size presets and config resolver for the MambaSession layer.
+ */
+// ── Model size presets ────────────────────────────────────────────────────────
+/**
+ * Pre-defined model size presets.
+ * nHeads is used by Mamba-2/3 and Attention layers; ignored for Mamba-1.
+ */
+export const MODEL_PRESETS = {
+    nano: { dModel: 128, numLayers: 4, dState: 16, dConv: 4, expand: 2, nHeads: 4 },
+    small: { dModel: 256, numLayers: 6, dState: 16, dConv: 4, expand: 2, nHeads: 8 },
+    medium: { dModel: 512, numLayers: 8, dState: 16, dConv: 4, expand: 2, nHeads: 8 },
+    large: { dModel: 768, numLayers: 12, dState: 16, dConv: 4, expand: 2, nHeads: 12 },
+};
+const DEFAULT_PRESET = 'nano';
+/**
+ * Resolve a layer schedule from a preset name, explicit array, or undefined.
+ *
+ *   'jamba' — Jamba-style: every 4th layer (index 3, 7, 11…) is attention, rest mamba2
+ *   'zamba' — Zamba-style: every 6th layer (index 5, 11…) is attention, rest mamba3
+ */
+export function resolveLayerSchedule(schedule, numLayers, defaultType) {
+    if (!schedule) {
+        return Array.from({ length: numLayers }, () => ({ type: defaultType }));
+    }
+    if (schedule === 'jamba') {
+        return Array.from({ length: numLayers }, (_, i) => ({
+            type: (i % 4 === 3 ? 'attention' : 'mamba2'),
+        }));
+    }
+    if (schedule === 'zamba') {
+        return Array.from({ length: numLayers }, (_, i) => ({
+            type: (i % 6 === 5 ? 'attention' : 'mamba3'),
+        }));
+    }
+    return schedule;
+}
+// ── Config resolution ─────────────────────────────────────────────────────────
+/**
+ * Resolves a fully-populated HybridMambaModelConfig from session options and
+ * the actual tokenizer vocab size.
+ *
+ * Resolution order:
+ *  1. Preset fields (default: 'nano')
+ *  2. modelConfig overrides (only applied when modelSize === 'custom')
+ *  3. vocabSize from the tokenizer
+ *  4. mambaVersion → default layer type for schedule resolution
+ *  5. layerSchedule → per-layer type array (preset string or explicit array)
+ */
+export function resolveModelConfig(options, vocabSize) {
+    const presetName = options.modelSize === 'custom' || options.modelSize == null
+        ? DEFAULT_PRESET
+        : options.modelSize;
+    const preset = MODEL_PRESETS[presetName] ?? MODEL_PRESETS[DEFAULT_PRESET];
+    const overrides = options.modelSize === 'custom' && options.modelConfig
+        ? options.modelConfig
+        : {};
+    const dModel = overrides.dModel ?? preset.dModel ?? 128;
+    const numLayers = overrides.numLayers ?? preset.numLayers ?? 4;
+    const dState = overrides.dState ?? preset.dState ?? 16;
+    const dConv = overrides.dConv ?? preset.dConv ?? 4;
+    const expand = overrides.expand ?? preset.expand ?? 2;
+    const nHeads = overrides.nHeads ?? preset.nHeads ?? 4;
+    const nGroups = overrides.nGroups ?? preset.nGroups ?? 1;
+    const chunkLen = overrides.chunkLen ?? preset.chunkLen ?? 256;
+    const mimoGroup = overrides.mimoGroup ?? preset.mimoGroup ?? 1;
+    const eosId = overrides.eosId ?? preset.eosId ?? -1;
+    // Validate nHeads divides dModel for multi-head blocks
+    if (dModel % nHeads !== 0) {
+        throw new Error(`resolveModelConfig: dModel (${dModel}) must be divisible by nHeads (${nHeads}).`);
+    }
+    // Layer schedule
+    const defaultType = options.mambaVersion ?? 'mamba1';
+    const layers = resolveLayerSchedule(options.layerSchedule, numLayers, defaultType);
+    return {
+        vocabSize,
+        dModel,
+        numLayers,
+        dState,
+        dConv,
+        expand,
+        nHeads,
+        nGroups,
+        chunkLen,
+        mimoGroup,
+        eosId,
+        layers,
+        seed: options.seed,
+    };
+}
+//# sourceMappingURL=presets.js.map

package/dist/session/presets.js.map

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

package/dist/session/session.d.ts

@@ -0,0 +1,186 @@
+/**
+ * session.ts – MambaSession: the single entry point for all session-layer functionality.
+ *
+ * MambaSession is a facade over MambaCode.js that collapses the 8-step
+ * async setup sequence into a single `MambaSession.create()` call.
+ *
+ * Part of the @seanhogg/ssmjs session layer.
+ */
+import { BPETokenizer, HybridMambaModel, MambaTrainer, type HybridMambaModelConfig, type LayerSpec, type LayerType } from '@seanhogg/builderforce-memory-engine';
+import type { Tokenizer } from './tokenizer.js';
+export interface MambaSessionOptions {
+    /** URL to a .bin checkpoint file. Optional — model starts with random weights if omitted. */
+    checkpointUrl?: string;
+    /**
+     * Pre-read checkpoint bytes. Takes precedence over `checkpointUrl` and is
+     * loaded directly via `model.loadWeights()` with no network fetch.
+     * Use this in Node.js, where `fetch()` cannot read local file paths — read
+     * the .bin with `fs` and pass the resulting ArrayBuffer here.
+     */
+    checkpointBuffer?: ArrayBuffer;
+    /** URL to vocab.json. Defaults to the Qwen2.5-Coder vocabulary. */
+    vocabUrl?: string;
+    /** URL to merges.txt. Defaults to the Qwen2.5-Coder merge rules. */
+    mergesUrl?: string;
+    /** In-memory vocabulary object — alternative to vocabUrl. */
+    vocabObject?: Record<string, number>;
+    /** In-memory merges array — alternative to mergesUrl. */
+    mergesArray?: string[];
+    /**
+     * A fully-constructed tokenizer to use instead of BPETokenizer.
+     * When provided, `vocabUrl`, `mergesUrl`, `vocabObject`, and `mergesArray`
+     * are all ignored — MambaSession will use this tokenizer directly.
+     * The tokenizer must satisfy the `Tokenizer` interface.
+     */
+    tokenizer?: Tokenizer;
+    /** Unique name for this session, used as the IndexedDB key. Default: 'default'. */
+    name?: string;
+    /**
+     * Model size preset. Overrides individual model config fields.
+     * - 'nano'   : dModel=128,  numLayers=4
+     * - 'small'  : dModel=256,  numLayers=6
+     * - 'medium' : dModel=512,  numLayers=8  (default)
+     * - 'large'  : dModel=768,  numLayers=12
+     * - 'custom' : use modelConfig directly
+     */
+    modelSize?: 'nano' | 'small' | 'medium' | 'large' | 'custom';
+    /** Fine-grained model configuration. Only used when modelSize is 'custom'. */
+    modelConfig?: Partial<HybridMambaModelConfig>;
+    /**
+     * SSM variant applied to all layers when no layerSchedule is given.
+     * Default: 'mamba1' (existing behaviour).
+     */
+    mambaVersion?: LayerType extends 'attention' ? never : 'mamba1' | 'mamba2' | 'mamba3';
+    /**
+     * Per-layer type schedule. Length must equal the resolved numLayers.
+     * Overrides mambaVersion when provided.
+     *
+     * Preset strings:
+     *   'jamba' — every 4th layer is attention, rest mamba2
+     *   'zamba' — every 6th layer is attention, rest mamba3
+     */
+    layerSchedule?: LayerSpec[] | 'jamba' | 'zamba';
+    /**
+     * Pre-created GPUAdapter to use instead of calling navigator.gpu.requestAdapter().
+     * Use this in Node.js environments with @webgpu/node:
+     *   import { create as createGPU } from '@webgpu/node';
+     *   const gpuAdapter = await createGPU().requestAdapter();
+     * When provided, `powerPreference` and `allowCpuFallback` are ignored.
+     */
+    gpuAdapter?: GPUAdapter;
+    /**
+     * IDBFactory to use instead of the global `indexedDB`.
+     * Use this in Node.js environments with fake-indexeddb:
+     *   import { IDBFactory } from 'fake-indexeddb';
+     *   const idbFactory = new IDBFactory();
+     * When provided, the 'indexedDB' storage target uses this factory.
+     */
+    idbFactory?: IDBFactory;
+    /** WebGPU power preference. Default: 'high-performance'. */
+    powerPreference?: 'high-performance' | 'low-power';
+    /**
+     * When true, MambaSession will attempt to obtain a software (CPU) WebGPU
+     * adapter if the preferred GPU adapter is unavailable — for example in
+     * environments that lack a discrete GPU or where the browser has disabled
+     * WebGPU. Performance will be significantly degraded, but the session will
+     * still initialise and produce correct output.
+     *
+     * Requires a browser/runtime that supports `forceFallbackAdapter: true` on
+     * `navigator.gpu.requestAdapter()`. Node.js environments may not have a
+     * software adapter available; an error is thrown in that case.
+     *
+     * Default: false (a missing GPU is a hard error).
+     */
+    allowCpuFallback?: boolean;
+    /** Number of times to retry a failed checkpoint fetch. Default: 2. */
+    fetchRetries?: number;
+    /**
+     * Deterministic seed for weight initialisation. When set, a model created
+     * without a checkpoint initialises reproducibly — the same seed yields
+     * byte-identical weights on any machine. Omit for non-reproducible
+     * `Math.random` init (the default).
+     */
+    seed?: number;
+}
+export interface CompleteOptions {
+    maxNewTokens?: number;
+    temperature?: number;
+    topK?: number;
+    topP?: number;
+}
+export interface AdaptOptions {
+    epochs?: number;
+    learningRate?: number;
+    seqLen?: number;
+    wsla?: boolean;
+    fullTrain?: boolean;
+    onProgress?: (epoch: number, loss: number) => void;
+}
+export interface AdaptResult {
+    losses: number[];
+    epochCount: number;
+    durationMs: number;
+}
+export type StorageTarget = 'indexedDB' | 'download' | 'fileSystem';
+export interface SaveOptions {
+    storage?: StorageTarget;
+    filename?: string;
+    key?: string;
+}
+export interface LoadOptions {
+    storage?: StorageTarget;
+    url?: string;
+    key?: string;
+}
+export type CreateStage = 'gpu' | 'tokenizer' | 'model' | 'weights';
+export interface CreateProgressEvent {
+    stage: CreateStage;
+    progress: number;
+    message: string;
+}
+export interface SessionInternals {
+    device: GPUDevice;
+    model: HybridMambaModel;
+    trainer: MambaTrainer;
+    tokenizer: BPETokenizer;
+}
+export interface CreateCallbacks {
+    onProgress?: (event: CreateProgressEvent) => void;
+}
+export type GpuMode = 'webgpu' | 'cpu-fallback';
+export declare class MambaSession {
+    private _device;
+    private _tokenizer;
+    private _model;
+    private _trainer;
+    private _name;
+    private _destroyed;
+    private _gpuMode;
+    private _idbFactory;
+    /**
+     * Whether the session is running on a real GPU ('webgpu') or a software
+     * CPU fallback ('cpu-fallback'). Only 'cpu-fallback' when
+     * `allowCpuFallback: true` was passed and no GPU was available.
+     */
+    get gpuMode(): GpuMode;
+    private constructor();
+    static create(options: MambaSessionOptions, callbacks?: CreateCallbacks): Promise<MambaSession>;
+    complete(prompt: string, options?: CompleteOptions): Promise<string>;
+    completeStream(prompt: string, options?: CompleteOptions): AsyncIterable<string>;
+    /**
+     * Returns a fixed-length (`dModel`) L2-normalised embedding for `text`,
+     * derived from the model's final hidden state. Suitable for cosine-similarity
+     * semantic search (see MemoryStore.recallSimilar).
+     *
+     * Returns a zero vector for empty input.
+     */
+    embed(text: string): Promise<Float32Array>;
+    adapt(text: string, options?: AdaptOptions): Promise<AdaptResult>;
+    evaluate(text: string): Promise<number>;
+    save(options?: SaveOptions): Promise<void>;
+    load(options?: LoadOptions): Promise<boolean>;
+    destroy(): void;
+    get internals(): SessionInternals;
+    private _assertNotDestroyed;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session/session.d.ts.map

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

package/dist/session/session.js

@@ -0,0 +1,358 @@
+/**
+ * session.ts – MambaSession: the single entry point for all session-layer functionality.
+ *
+ * MambaSession is a facade over MambaCode.js that collapses the 8-step
+ * async setup sequence into a single `MambaSession.create()` call.
+ *
+ * Part of the @seanhogg/ssmjs session layer.
+ */
+import { initWebGPU, BPETokenizer, HybridMambaModel, MambaTrainer, } from '@seanhogg/builderforce-memory-engine';
+import { SessionError } from './errors.js';
+// ── Opinionated defaults ───────────────────────────────────────────────────────
+/** Default tokenizer: Qwen2.5-Coder BPE vocabulary (Apache 2.0). */
+const DEFAULT_VOCAB_URL = 'https://huggingface.co/Qwen/Qwen2.5-Coder-1.5B-Instruct/resolve/main/vocab.json';
+const DEFAULT_MERGES_URL = 'https://huggingface.co/Qwen/Qwen2.5-Coder-1.5B-Instruct/resolve/main/merges.txt';
+// Checkpoint provenance
+// ----------------------
+// There is intentionally no hard-coded default checkpoint URL. A model with no
+// checkpoint starts from initialised weights and generates poorly until trained
+// or adapted — callers must opt in to a checkpoint explicitly via one of:
+//   • `checkpointUrl`    — fetch a hosted .bin (browser or any fetch-capable env)
+//   • `checkpointBuffer` — load an already-read ArrayBuffer (Node/local files;
+//                          fetch() cannot read local paths in Node)
+// To produce a checkpoint without a hosted model:
+//   • Untrained (deterministic seed): `node tools/generate-bin.js --size nano`
+//   • Trained: open tools/pretrain.html, train on a corpus, download the .bin
+import { resolveModelConfig } from './presets.js';
+import { saveToIndexedDB, loadFromIndexedDB, triggerDownload, saveViaFileSystemAPI, loadViaFileSystemAPI, } from './persistence.js';
+import { tokenStream } from './streaming.js';
+/** Base delay (ms) for the first checkpoint fetch retry. Subsequent retries double this. */
+const RETRY_BASE_DELAY_MS = 500;
+/** Multiplier applied to delay on each successive retry. */
+const RETRY_BACKOFF_FACTOR = 2;
+export class MambaSession {
+    _device;
+    _tokenizer;
+    _model;
+    _trainer;
+    _name;
+    _destroyed = false;
+    _gpuMode = 'webgpu';
+    _idbFactory;
+    /**
+     * Whether the session is running on a real GPU ('webgpu') or a software
+     * CPU fallback ('cpu-fallback'). Only 'cpu-fallback' when
+     * `allowCpuFallback: true` was passed and no GPU was available.
+     */
+    get gpuMode() { return this._gpuMode; }
+    constructor(device, tokenizer, model, trainer, name, gpuMode = 'webgpu', idbFactory) {
+        this._device = device;
+        this._tokenizer = tokenizer;
+        this._model = model;
+        this._trainer = trainer;
+        this._name = name;
+        this._gpuMode = gpuMode;
+        this._idbFactory = idbFactory;
+    }
+    // ── Static factory ─────────────────────────────────────────────────────────
+    static async create(options, callbacks = {}) {
+        const { onProgress } = callbacks;
+        const name = options.name ?? 'default';
+        const fetchRetries = options.fetchRetries ?? 2;
+        const emit = (stage, progress, message) => {
+            onProgress?.({ stage, progress, message });
+        };
+        // Step 1 — GPU
+        emit('gpu', 0.0, 'Initialising WebGPU…');
+        let device;
+        let gpuMode = 'webgpu';
+        if (options.gpuAdapter != null) {
+            // Adapter injected externally (e.g. @webgpu/node in Node.js)
+            try {
+                device = await options.gpuAdapter.requestDevice();
+            }
+            catch (err) {
+                throw new SessionError('GPU_UNAVAILABLE', `Failed to acquire GPUDevice from provided gpuAdapter: ${err.message}`, err);
+            }
+            emit('gpu', 1.0, 'WebGPU ready (injected adapter)');
+        }
+        else {
+            try {
+                const result = await initWebGPU({
+                    powerPreference: options.powerPreference ?? 'high-performance',
+                });
+                device = result.device;
+            }
+            catch (primaryErr) {
+                if (!options.allowCpuFallback) {
+                    throw new SessionError('GPU_UNAVAILABLE', `WebGPU initialisation failed: ${primaryErr.message}. ` +
+                        `Set allowCpuFallback: true to attempt a software (CPU) fallback.`, primaryErr);
+                }
+                // Attempt software (CPU) adapter — available in Chrome with
+                // --enable-unsafe-webgpu or in environments with a WARP/SwiftShader adapter.
+                emit('gpu', 0.4, `WebGPU unavailable (${primaryErr.message}); ` +
+                    `attempting CPU software fallback — performance will be degraded.`);
+                if (typeof navigator === 'undefined' || !navigator.gpu) {
+                    throw new SessionError('GPU_UNAVAILABLE', 'WebGPU is not available in this environment and no software adapter can be requested.', primaryErr);
+                }
+                try {
+                    const fallbackAdapter = await navigator.gpu.requestAdapter({
+                        powerPreference: 'low-power',
+                        forceFallbackAdapter: true,
+                    });
+                    if (!fallbackAdapter)
+                        throw new Error('requestAdapter returned null');
+                    device = await fallbackAdapter.requestDevice();
+                    gpuMode = 'cpu-fallback';
+                }
+                catch (fallbackErr) {
+                    throw new SessionError('GPU_UNAVAILABLE', `WebGPU unavailable and CPU fallback failed: ${fallbackErr.message}`, fallbackErr);
+                }
+            }
+            emit('gpu', 1.0, gpuMode === 'cpu-fallback'
+                ? 'CPU software adapter ready (degraded performance)'
+                : 'WebGPU ready');
+        }
+        // Step 2 — Tokenizer
+        emit('tokenizer', 0.0, 'Loading tokenizer…');
+        let tokenizer;
+        if (options.tokenizer != null) {
+            // Custom tokenizer injected — skip BPETokenizer construction entirely.
+            // Wrap it in a BPETokenizer-shaped proxy so the rest of the code is unchanged.
+            const custom = options.tokenizer;
+            tokenizer = Object.assign(new BPETokenizer(), {
+                encode: (text) => custom.encode(text),
+                decode: (ids) => custom.decode(ids),
+                get vocabSize() { return custom.vocabSize; },
+            });
+        }
+        else {
+            tokenizer = new BPETokenizer();
+            try {
+                if (options.vocabObject != null && options.mergesArray != null) {
+                    tokenizer.loadFromObjects(options.vocabObject, options.mergesArray);
+                }
+                else {
+                    const vocabUrl = options.vocabUrl ?? DEFAULT_VOCAB_URL;
+                    const mergesUrl = options.mergesUrl ?? DEFAULT_MERGES_URL;
+                    await tokenizer.load(vocabUrl, mergesUrl);
+                }
+            }
+            catch (err) {
+                throw new SessionError('TOKENIZER_LOAD_FAILED', `Tokenizer failed to load: ${err.message}`, err);
+            }
+        }
+        emit('tokenizer', 1.0, 'Tokenizer ready');
+        // Step 3 — Model & Trainer
+        emit('model', 0.0, 'Building model…');
+        const vocabSize = tokenizer.vocabSize > 0 ? tokenizer.vocabSize : 1;
+        const config = resolveModelConfig(options, vocabSize);
+        const model = new HybridMambaModel(device, config);
+        const trainer = new MambaTrainer(model, tokenizer);
+        emit('model', 1.0, 'Model ready');
+        // Step 4 — Checkpoint (optional)
+        // A pre-read buffer takes precedence over a URL (Node/local-file path);
+        // fetch() is only used when a URL is supplied.
+        if (options.checkpointBuffer != null) {
+            emit('weights', 0.0, 'Loading checkpoint…');
+            try {
+                await model.loadWeights(options.checkpointBuffer);
+            }
+            catch (err) {
+                throw new SessionError('CHECKPOINT_INVALID', `Checkpoint buffer is invalid or incompatible: ${err.message}`, err);
+            }
+            emit('weights', 1.0, 'Checkpoint loaded');
+        }
+        else if (options.checkpointUrl != null) {
+            emit('weights', 0.0, 'Fetching checkpoint…');
+            let buffer = null;
+            let lastErr;
+            for (let attempt = 0; attempt <= fetchRetries; attempt++) {
+                try {
+                    const res = await fetch(options.checkpointUrl);
+                    if (!res.ok) {
+                        throw new Error(`HTTP ${res.status} ${res.statusText}`);
+                    }
+                    buffer = await res.arrayBuffer();
+                    break;
+                }
+                catch (err) {
+                    lastErr = err;
+                    if (attempt < fetchRetries) {
+                        await sleep(RETRY_BASE_DELAY_MS * Math.pow(RETRY_BACKOFF_FACTOR, attempt));
+                    }
+                }
+            }
+            if (buffer == null) {
+                throw new SessionError('CHECKPOINT_FETCH_FAILED', `Failed to fetch checkpoint from "${options.checkpointUrl}" after ${fetchRetries + 1} attempt(s): ${lastErr.message}`, lastErr);
+            }
+            try {
+                await model.loadWeights(buffer);
+            }
+            catch (err) {
+                throw new SessionError('CHECKPOINT_INVALID', `Checkpoint file is invalid or incompatible: ${err.message}`, err);
+            }
+            emit('weights', 1.0, 'Checkpoint loaded');
+        }
+        return new MambaSession(device, tokenizer, model, trainer, name, gpuMode, options.idbFactory);
+    }
+    // ── Text generation ────────────────────────────────────────────────────────
+    async complete(prompt, options = {}) {
+        this._assertNotDestroyed();
+        const { maxNewTokens = 200, temperature = 0.8, topK = 50, topP = 0.9, } = options;
+        const promptIds = this._tokenizer.encode(prompt);
+        const outputIds = await this._model.generate(promptIds, maxNewTokens, {
+            temperature,
+            topK,
+            topP,
+        });
+        // Return the continuation only (not the original prompt tokens)
+        const continuationIds = outputIds.slice(promptIds.length);
+        return this._tokenizer.decode(continuationIds);
+    }
+    async *completeStream(prompt, options = {}) {
+        this._assertNotDestroyed();
+        const { maxNewTokens = 200, temperature = 0.8, topK = 50, topP = 0.9, } = options;
+        const promptIds = this._tokenizer.encode(prompt);
+        for await (const tokenId of tokenStream(this._model, promptIds, maxNewTokens, {
+            temperature,
+            topK,
+            topP,
+        })) {
+            yield this._tokenizer.decode([tokenId]);
+        }
+    }
+    // ── Embedding ──────────────────────────────────────────────────────────────
+    /**
+     * Returns a fixed-length (`dModel`) L2-normalised embedding for `text`,
+     * derived from the model's final hidden state. Suitable for cosine-similarity
+     * semantic search (see MemoryStore.recallSimilar).
+     *
+     * Returns a zero vector for empty input.
+     */
+    async embed(text) {
+        this._assertNotDestroyed();
+        const ids = this._tokenizer.encode(text);
+        if (ids.length === 0) {
+            return new Float32Array(this._model.config.dModel);
+        }
+        return this._model.embed(ids);
+    }
+    // ── Fine-tuning ────────────────────────────────────────────────────────────
+    async adapt(text, options = {}) {
+        this._assertNotDestroyed();
+        let { epochs = 3, wsla = true, } = options;
+        const { learningRate = 1e-4, seqLen = 512, fullTrain = false, onProgress, } = options;
+        // Convenience alias: fullTrain overrides wsla and epoch defaults
+        if (fullTrain) {
+            wsla = false;
+            epochs = options.epochs ?? 5;
+        }
+        const encoded = this._tokenizer.encode(text);
+        if (encoded.length < 2) {
+            throw new SessionError('INPUT_TOO_SHORT', 'The input text encodes to fewer than 2 tokens and cannot be used for training.');
+        }
+        const startTime = Date.now();
+        const losses = await this._trainer.train(text, {
+            epochs,
+            learningRate,
+            seqLen,
+            wsla,
+            onEpochEnd: onProgress ?? null,
+        });
+        return {
+            losses,
+            epochCount: losses.length,
+            durationMs: Date.now() - startTime,
+        };
+    }
+    // ── Evaluation ─────────────────────────────────────────────────────────────
+    async evaluate(text) {
+        this._assertNotDestroyed();
+        return this._trainer.evaluate(text);
+    }
+    // ── Persistence ────────────────────────────────────────────────────────────
+    async save(options = {}) {
+        this._assertNotDestroyed();
+        const storage = options.storage ?? 'indexedDB';
+        const key = options.key ?? this._name;
+        const filename = options.filename ?? `${this._name}.bin`;
+        const buffer = await this._model.exportWeights();
+        switch (storage) {
+            case 'indexedDB':
+                await saveToIndexedDB(key, buffer, this._idbFactory);
+                break;
+            case 'download':
+                await triggerDownload(filename, buffer);
+                break;
+            case 'fileSystem':
+                await saveViaFileSystemAPI(filename, buffer);
+                break;
+            default:
+                throw new SessionError('STORAGE_UNAVAILABLE', `Unknown storage target: "${storage}"`);
+        }
+    }
+    async load(options = {}) {
+        this._assertNotDestroyed();
+        const storage = options.storage ?? 'indexedDB';
+        const key = options.key ?? this._name;
+        let buffer;
+        switch (storage) {
+            case 'indexedDB': {
+                buffer = await loadFromIndexedDB(key, this._idbFactory);
+                break;
+            }
+            case 'fileSystem': {
+                buffer = await loadViaFileSystemAPI();
+                break;
+            }
+            default: {
+                // Treat any other string as a URL fetch (covers custom `url` option)
+                const url = options.url;
+                if (!url) {
+                    throw new SessionError('STORAGE_UNAVAILABLE', 'load() with storage other than "indexedDB" or "fileSystem" requires a url option.');
+                }
+                const res = await fetch(url);
+                if (!res.ok) {
+                    throw new SessionError('CHECKPOINT_FETCH_FAILED', `Failed to fetch checkpoint from "${url}": HTTP ${res.status}`);
+                }
+                buffer = await res.arrayBuffer();
+            }
+        }
+        if (buffer == null)
+            return false;
+        try {
+            await this._model.loadWeights(buffer);
+        }
+        catch (err) {
+            throw new SessionError('CHECKPOINT_INVALID', `Saved checkpoint is invalid or incompatible: ${err.message}`, err);
+        }
+        return true;
+    }
+    // ── Resource cleanup ───────────────────────────────────────────────────────
+    destroy() {
+        if (this._destroyed)
+            return;
+        this._destroyed = true;
+        this._device.destroy();
+    }
+    // ── Escape hatch ───────────────────────────────────────────────────────────
+    get internals() {
+        return {
+            device: this._device,
+            model: this._model,
+            trainer: this._trainer,
+            tokenizer: this._tokenizer,
+        };
+    }
+    // ── Private helpers ────────────────────────────────────────────────────────
+    _assertNotDestroyed() {
+        if (this._destroyed) {
+            throw new SessionError('SESSION_DESTROYED', 'This MambaSession has been destroyed. Create a new session with MambaSession.create().');
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=session.js.map