@seanhogg/builderforce-memory-engine 2026.7.14 → 2026.9.27

package/dist/import/foreign/codestral_mamba.js

@@ -0,0 +1,174 @@
+/**
+ * import/foreign/codestral_mamba.ts — weight port for Codestral-Mamba
+ * (`mistralai/Mamba-Codestral-7B-v0.1`, `Mamba2ForCausalLM`,
+ * `model_type: "mamba2"`, Mamba-2 / SSD).
+ *
+ * Source layout confirmed against the repo's published HF `config.json`, its
+ * `model.safetensors.index.json` (579 tensors = 9 per layer × 64 + 3 globals),
+ * the header of `consolidated.safetensors`, and
+ * `transformers/models/mamba2/modeling_mamba2.py`:
+ *
+ *   backbone.embeddings.weight                    [vocab, d_model]
+ *   backbone.layers.{N}.norm.weight               [d_model]
+ *   backbone.layers.{N}.mixer.in_proj.weight      [2*d_inner + 2*n_groups*d_state + n_heads, d_model]
+ *   backbone.layers.{N}.mixer.conv1d.weight       [conv_dim, 1, d_conv]
+ *   backbone.layers.{N}.mixer.conv1d.bias         [conv_dim]
+ *   backbone.layers.{N}.mixer.dt_bias             [n_heads]
+ *   backbone.layers.{N}.mixer.A_log               [n_heads]
+ *   backbone.layers.{N}.mixer.D                   [n_heads]
+ *   backbone.layers.{N}.mixer.norm.weight         [d_inner]
+ *   backbone.layers.{N}.mixer.out_proj.weight     [d_model, d_inner]
+ *   backbone.norm_f.weight                        [d_model]
+ *   lm_head.weight                                [vocab, d_model]
+ *
+ * where `conv_dim = d_inner + 2 * n_groups * d_state`. Mamba-2 has no `x_proj`
+ * and no `dt_proj`: B, C and dt all come out of the fused `in_proj`.
+ *
+ * Three reconciliations against `Mamba2Block`:
+ *
+ *  1. **`in_proj` row order.** Upstream splits
+ *     `[gate (d_inner), x|B|C (conv_dim), dt (n_heads)]`; this engine's fused
+ *     projection is `[x (d_inner), B (n_groups*d_state), C (n_groups*d_state),
+ *     dt (n_heads)]` — the SAME tail, minus the leading gate rows. So the port
+ *     is one contiguous row slice starting at `d_inner`, and the gate rows are
+ *     declared as a discard (see 3).
+ *  2. **`A_log` convention.** Upstream uses `A = -exp(A_log)`; `ssd.ts` uses
+ *     `A = -softplus(A_log)`. The port re-expresses the same `A` as
+ *     `softplus⁻¹(exp(A_log))` so decay rates are preserved exactly, rather than
+ *     copying the raw value and silently changing every head's decay.
+ *  3. **The gate branch.** `Mamba2Block` has no `z` gate: it RMS-norms the scan
+ *     output and projects out, where upstream computes
+ *     `norm(y * silu(z))`. The `d_inner × d_model` gate rows therefore have no
+ *     target. That is a REAL loss of capability, not a formatting detail, and it
+ *     is reported as a `PortDiscard` on every layer so a caller sees it.
+ *
+ * Also mapped without transform: `mixer.norm.weight` → the block's inner
+ * `normWeight` (applied ungated here, per 3), `backbone.layers.N.norm.weight` →
+ * `preNormWeight`, `conv1d.{weight,bias}` (depthwise, taps reversed) → the fused
+ * `[x, B, C]` conv, and `D` / `dt_bias` per head. Linear weights are
+ * `[out, in]` row-major on both sides, so no transposes.
+ *
+ * `tie_word_embeddings: false`, so `lm_head.weight` is a real stored tensor with
+ * no target here (`HybridMambaModel` ties its head to the embedding) — it is
+ * reported as unmapped.
+ */
+import { expandFactor, firstInt, readInnerSize, requireInt, } from "./adapter.js";
+const ID = "codestral_mamba";
+/** `backbone.embeddings` (HF) vs `backbone.embedding` (Mistral-native). */
+const EMBEDDING_NAMES = ["backbone.embeddings.weight", "backbone.embedding.weight"];
+function rules(a) {
+    const { vocabSize: V, dModel: E, numLayers: L, dInner: D, dState: N, dConv: K, nHeads: H, nGroups: G } = a;
+    const convDim = D + 2 * G * N;
+    /** Rows this engine keeps out of the fused projection: [x, B, C, dt]. */
+    const keptRows = convDim + H;
+    const out = [
+        { target: "embedding", shape: [V, E], from: EMBEDDING_NAMES, op: { kind: "copy" } },
+    ];
+    for (let i = 0; i < L; i++) {
+        const m = `backbone.layers.${i}.mixer`;
+        const t = `layer${i}`;
+        out.push({
+            target: `${t}.wInProj`,
+            shape: [keptRows, E],
+            from: [`${m}.in_proj.weight`],
+            // Drop the leading gate rows; keep [x, B, C, dt] verbatim.
+            op: { kind: "rowSlice", start: D, count: keptRows },
+            note: "upstream rows are [gate, x, B, C, dt]; this block has no gate branch",
+        }, {
+            target: `${t}.wConv`,
+            shape: [convDim, K],
+            from: [`${m}.conv1d.weight`],
+            op: { kind: "convTaps" },
+            note: "depthwise [conv_dim, 1, d_conv] → [conv_dim, d_conv] with the tap axis reversed",
+        }, { target: `${t}.bConv`, shape: [convDim], from: [`${m}.conv1d.bias`], op: { kind: "copy" } }, {
+            target: `${t}.A_log`,
+            shape: [H],
+            from: [`${m}.A_log`],
+            op: { kind: "negExpToSoftplusInv" },
+            note: "upstream A = -exp(A_log); this engine's SSD kernel uses A = -softplus(A_log)",
+        }, { target: `${t}.dt_bias`, shape: [H], from: [`${m}.dt_bias`], op: { kind: "copy" } }, { target: `${t}.D_vec`, shape: [H], from: [`${m}.D`], op: { kind: "copy" } }, { target: `${t}.wOutProj`, shape: [E, D], from: [`${m}.out_proj.weight`], op: { kind: "copy" } }, {
+            target: `${t}.normWeight`,
+            shape: [D],
+            from: [`${m}.norm.weight`],
+            op: { kind: "copy" },
+            note: "upstream this gain belongs to a GATED RMSNorm; applied ungated here",
+        }, {
+            target: `${t}.preNormWeight`,
+            shape: [E],
+            from: [`backbone.layers.${i}.norm.weight`],
+            op: { kind: "copy" },
+        });
+    }
+    out.push({ target: "final_norm", shape: [E], from: ["backbone.norm_f.weight"], op: { kind: "copy" } });
+    return out;
+}
+function discards(a) {
+    const out = [];
+    for (let i = 0; i < a.numLayers; i++) {
+        out.push({
+            source: `backbone.layers.${i}.mixer.in_proj.weight`,
+            elements: a.dInner * a.dModel,
+            reason: "the leading d_inner gate (z) rows — Mamba2Block computes norm(y) rather than " +
+                "norm(y * silu(z)), so it has no gate branch to receive them",
+        });
+    }
+    return out;
+}
+export const codestralMambaAdapter = {
+    id: ID,
+    label: "Codestral-Mamba (Mamba-2 / SSD)",
+    modelTypes: ["mamba2"],
+    // `MambaCodestralForCausalLM` is not a transformers class — the published
+    // config says `Mamba2ForCausalLM` — but it is a common mis-citation, so it is
+    // accepted here rather than sending a correct checkpoint down the error path.
+    architectures: ["Mamba2ForCausalLM", "MambaCodestralForCausalLM"],
+    describe(config) {
+        const dModel = requireInt(config, "hidden_size");
+        const numLayers = requireInt(config, "num_hidden_layers");
+        const vocabSize = requireInt(config, "vocab_size");
+        const dState = requireInt(config, "state_size");
+        const dConv = requireInt(config, "conv_kernel");
+        const nHeads = requireInt(config, "num_heads");
+        const nGroups = firstInt(config, ["n_groups"]) ?? 1;
+        const chunkLen = firstInt(config, ["chunk_size"]) ?? 256;
+        const dInner = readInnerSize(config, dModel);
+        const expand = expandFactor(dInner, dModel, "Codestral-Mamba");
+        // Upstream's own invariant (`hidden_size * expand == num_heads * head_dim`);
+        // Mamba2Block enforces the same divisibility, so check it here where the
+        // message can name the config fields that disagree.
+        const headDim = firstInt(config, ["head_dim"]);
+        if (dInner % nHeads !== 0) {
+            throw new Error(`import/foreign: Codestral-Mamba d_inner ${dInner} is not divisible by num_heads ${nHeads}`);
+        }
+        if (headDim !== undefined && headDim * nHeads !== dInner) {
+            throw new Error(`import/foreign: Codestral-Mamba config is inconsistent — head_dim ${headDim} × ` +
+                `num_heads ${nHeads} = ${headDim * nHeads}, but d_inner is ${dInner}`);
+        }
+        const layers = Array.from({ length: numLayers }, () => ({ type: "mamba2" }));
+        const modelConfig = {
+            vocabSize,
+            dModel,
+            numLayers,
+            layers,
+            dState,
+            dConv,
+            expand,
+            nHeads,
+            nGroups,
+            chunkLen,
+        };
+        const geometry = {
+            vocabSize,
+            dModel,
+            numLayers,
+            dInner,
+            dState,
+            dConv,
+            nHeads,
+            nGroups,
+            chunkLen,
+        };
+        return { modelConfig, plan: { adapter: ID, rules: rules(geometry), discards: discards(geometry) } };
+    },
+};
+//# sourceMappingURL=codestral_mamba.js.map

package/dist/import/foreign/codestral_mamba.js.map

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

package/dist/import/foreign/falcon_mamba.d.ts

@@ -0,0 +1,51 @@
+/**
+ * import/foreign/falcon_mamba.ts — weight port for Falcon-Mamba
+ * (`FalconMambaForCausalLM`, `model_type: "falcon_mamba"`, Mamba-1 / S6).
+ *
+ * Source layout confirmed against `tiiuae/falcon-mamba-7b`'s published
+ * `config.json`, `model.safetensors.index.json` (643 tensors = 10 per layer × 64
+ * + 3 globals) and the safetensors header of shard 1, plus
+ * `transformers/models/falcon_mamba/modeling_falcon_mamba.py`:
+ *
+ *   backbone.embeddings.weight                       [vocab, d_model]
+ *   backbone.layers.{N}.norm.weight                  [d_model]
+ *   backbone.layers.{N}.mixer.in_proj.weight         [2*d_inner, d_model]
+ *   backbone.layers.{N}.mixer.conv1d.weight          [d_inner, 1, d_conv]
+ *   backbone.layers.{N}.mixer.conv1d.bias            [d_inner]
+ *   backbone.layers.{N}.mixer.x_proj.weight          [dt_rank + 2*d_state, d_inner]
+ *   backbone.layers.{N}.mixer.dt_proj.weight         [d_inner, dt_rank]
+ *   backbone.layers.{N}.mixer.dt_proj.bias           [d_inner]
+ *   backbone.layers.{N}.mixer.A_log                  [d_inner, d_state]
+ *   backbone.layers.{N}.mixer.D                      [d_inner]
+ *   backbone.layers.{N}.mixer.out_proj.weight        [d_model, d_inner]
+ *   backbone.norm_f.weight                           [d_model]
+ *   lm_head.weight                                   [vocab, d_model]
+ *
+ * Conventions that line up with `Mamba1Block` as-is, so most rules are copies:
+ *   • `in_proj` rows are `[x, gate]` (`hidden_states, gate = …chunk(2, dim=1)`),
+ *     and `Mamba1Block.forward` also takes the first half as `x` and the second
+ *     as the gate `z`.
+ *   • `x_proj` rows are `[dt, B, C]`, matching the block's split order.
+ *   • `A = -exp(A_log)` in both — `selective_scan.ts` computes
+ *     `a_cont = -exp(clamp(a_log, -10, 5))`.
+ *   • `dt_proj.bias` is added inside `softplus(dt + bias)` upstream; here it is
+ *     the `dt_proj` linear's bias and the scan applies `softplus` afterwards —
+ *     algebraically the same value.
+ *   • Linear weights are `[out, in]` row-major on both sides (no transpose).
+ *
+ * Fidelity caveats recorded on the plan rather than hidden:
+ *   • `use_bias: false` upstream, so `in_proj` / `x_proj` / `out_proj` ship no
+ *     bias; this engine's blocks always own one, and they are filled with zeros
+ *     (an exact no-op, not an approximation).
+ *   • Falcon-Mamba RMS-normalises `dt`, `B` and `C` inside the mixer. Those
+ *     norms are `FalconMambaWeightlessRMSNorm` with `persistent=False` buffers,
+ *     so they contribute NO tensors to the checkpoint — nothing is dropped from
+ *     the file — but this engine's S6 scan has no such normalisation step, so a
+ *     ported model is not numerically identical to the original.
+ *   • `tie_word_embeddings: false`, so `lm_head.weight` is a real stored tensor.
+ *     `HybridMambaModel` always ties its LM head to the embedding table, so that
+ *     tensor has no target and is reported as unmapped.
+ */
+import { type ForeignMambaAdapter } from "./adapter.js";
+export declare const falconMambaAdapter: ForeignMambaAdapter;
+//# sourceMappingURL=falcon_mamba.d.ts.map

package/dist/import/foreign/falcon_mamba.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"falcon_mamba.d.ts","sourceRoot":"","sources":["../../../src/import/foreign/falcon_mamba.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAIH,OAAO,EAML,KAAK,mBAAmB,EAEzB,MAAM,cAAc,CAAC;AA0EtB,eAAO,MAAM,kBAAkB,EAAE,mBAuChC,CAAC"}

package/dist/import/foreign/falcon_mamba.js

@@ -0,0 +1,131 @@
+/**
+ * import/foreign/falcon_mamba.ts — weight port for Falcon-Mamba
+ * (`FalconMambaForCausalLM`, `model_type: "falcon_mamba"`, Mamba-1 / S6).
+ *
+ * Source layout confirmed against `tiiuae/falcon-mamba-7b`'s published
+ * `config.json`, `model.safetensors.index.json` (643 tensors = 10 per layer × 64
+ * + 3 globals) and the safetensors header of shard 1, plus
+ * `transformers/models/falcon_mamba/modeling_falcon_mamba.py`:
+ *
+ *   backbone.embeddings.weight                       [vocab, d_model]
+ *   backbone.layers.{N}.norm.weight                  [d_model]
+ *   backbone.layers.{N}.mixer.in_proj.weight         [2*d_inner, d_model]
+ *   backbone.layers.{N}.mixer.conv1d.weight          [d_inner, 1, d_conv]
+ *   backbone.layers.{N}.mixer.conv1d.bias            [d_inner]
+ *   backbone.layers.{N}.mixer.x_proj.weight          [dt_rank + 2*d_state, d_inner]
+ *   backbone.layers.{N}.mixer.dt_proj.weight         [d_inner, dt_rank]
+ *   backbone.layers.{N}.mixer.dt_proj.bias           [d_inner]
+ *   backbone.layers.{N}.mixer.A_log                  [d_inner, d_state]
+ *   backbone.layers.{N}.mixer.D                      [d_inner]
+ *   backbone.layers.{N}.mixer.out_proj.weight        [d_model, d_inner]
+ *   backbone.norm_f.weight                           [d_model]
+ *   lm_head.weight                                   [vocab, d_model]
+ *
+ * Conventions that line up with `Mamba1Block` as-is, so most rules are copies:
+ *   • `in_proj` rows are `[x, gate]` (`hidden_states, gate = …chunk(2, dim=1)`),
+ *     and `Mamba1Block.forward` also takes the first half as `x` and the second
+ *     as the gate `z`.
+ *   • `x_proj` rows are `[dt, B, C]`, matching the block's split order.
+ *   • `A = -exp(A_log)` in both — `selective_scan.ts` computes
+ *     `a_cont = -exp(clamp(a_log, -10, 5))`.
+ *   • `dt_proj.bias` is added inside `softplus(dt + bias)` upstream; here it is
+ *     the `dt_proj` linear's bias and the scan applies `softplus` afterwards —
+ *     algebraically the same value.
+ *   • Linear weights are `[out, in]` row-major on both sides (no transpose).
+ *
+ * Fidelity caveats recorded on the plan rather than hidden:
+ *   • `use_bias: false` upstream, so `in_proj` / `x_proj` / `out_proj` ship no
+ *     bias; this engine's blocks always own one, and they are filled with zeros
+ *     (an exact no-op, not an approximation).
+ *   • Falcon-Mamba RMS-normalises `dt`, `B` and `C` inside the mixer. Those
+ *     norms are `FalconMambaWeightlessRMSNorm` with `persistent=False` buffers,
+ *     so they contribute NO tensors to the checkpoint — nothing is dropped from
+ *     the file — but this engine's S6 scan has no such normalisation step, so a
+ *     ported model is not numerically identical to the original.
+ *   • `tie_word_embeddings: false`, so `lm_head.weight` is a real stored tensor.
+ *     `HybridMambaModel` always ties its LM head to the embedding table, so that
+ *     tensor has no target and is reported as unmapped.
+ */
+import { expandFactor, readInnerSize, readTimeStepRank, requireInt, } from "./adapter.js";
+const ID = "falcon_mamba";
+/** `backbone.embeddings` (HF) vs `backbone.embedding` (Mamba-SSM native). */
+const EMBEDDING_NAMES = ["backbone.embeddings.weight", "backbone.embedding.weight"];
+function rules(a) {
+    const { vocabSize: V, dModel: E, numLayers: L, dInner: D, dState: N, dConv: K, dtRank: R } = a;
+    const out = [
+        { target: "embedding", shape: [V, E], from: EMBEDDING_NAMES, op: { kind: "copy" } },
+    ];
+    for (let i = 0; i < L; i++) {
+        const m = `backbone.layers.${i}.mixer`;
+        const t = `layer${i}`;
+        out.push({ target: `${t}.wInProj`, shape: [2 * D, E], from: [`${m}.in_proj.weight`], op: { kind: "copy" } }, {
+            target: `${t}.bInProj`,
+            shape: [2 * D],
+            from: [],
+            op: { kind: "fill", value: 0 },
+            note: "Falcon-Mamba sets use_bias=false — in_proj ships no bias; zeros are exact",
+        }, {
+            target: `${t}.wConv`,
+            shape: [D, K],
+            from: [`${m}.conv1d.weight`],
+            op: { kind: "convTaps" },
+            note: "depthwise [d_inner, 1, d_conv] → [d_inner, d_conv] with the tap axis reversed",
+        }, { target: `${t}.bConv`, shape: [D], from: [`${m}.conv1d.bias`], op: { kind: "copy" } }, { target: `${t}.wXProj`, shape: [R + 2 * N, D], from: [`${m}.x_proj.weight`], op: { kind: "copy" } }, {
+            target: `${t}.bXProj`,
+            shape: [R + 2 * N],
+            from: [],
+            op: { kind: "fill", value: 0 },
+            note: "x_proj is bias-free upstream; zeros are exact",
+        }, { target: `${t}.wDtProj`, shape: [D, R], from: [`${m}.dt_proj.weight`], op: { kind: "copy" } }, { target: `${t}.bDtProj`, shape: [D], from: [`${m}.dt_proj.bias`], op: { kind: "copy" } }, { target: `${t}.A_log`, shape: [D, N], from: [`${m}.A_log`], op: { kind: "copy" } }, { target: `${t}.D_vec`, shape: [D], from: [`${m}.D`], op: { kind: "copy" } }, { target: `${t}.wOutProj`, shape: [E, D], from: [`${m}.out_proj.weight`], op: { kind: "copy" } }, {
+            target: `${t}.bOutProj`,
+            shape: [E],
+            from: [],
+            op: { kind: "fill", value: 0 },
+            note: "out_proj is bias-free upstream; zeros are exact",
+        }, {
+            target: `${t}.normWeight`,
+            shape: [E],
+            from: [`backbone.layers.${i}.norm.weight`],
+            op: { kind: "copy" },
+        });
+    }
+    out.push({ target: "final_norm", shape: [E], from: ["backbone.norm_f.weight"], op: { kind: "copy" } });
+    return out;
+}
+export const falconMambaAdapter = {
+    id: ID,
+    label: "Falcon-Mamba (Mamba-1 / S6)",
+    modelTypes: ["falcon_mamba"],
+    architectures: ["FalconMambaForCausalLM"],
+    describe(config) {
+        const dModel = requireInt(config, "hidden_size");
+        const numLayers = requireInt(config, "num_hidden_layers");
+        const vocabSize = requireInt(config, "vocab_size");
+        const dState = requireInt(config, "state_size");
+        const dConv = requireInt(config, "conv_kernel");
+        const dInner = readInnerSize(config, dModel);
+        const expand = expandFactor(dInner, dModel, "Falcon-Mamba");
+        const dtRank = readTimeStepRank(config, dModel);
+        const modelConfig = {
+            vocabSize,
+            dModel,
+            numLayers,
+            dState,
+            dConv,
+            expand,
+            // Every layer is a Mamba-1 mixer (the model's default schedule), but the
+            // dt rank and conv bias are per-block settings the shorthand can't carry.
+            defaultMamba1: { dtRank, biasConv: true },
+        };
+        const plan = {
+            adapter: ID,
+            rules: rules({ vocabSize, dModel, numLayers, dInner, dState, dConv, dtRank }),
+            // Nothing is partially consumed: every Falcon-Mamba tensor this plan
+            // touches is taken whole. `lm_head.weight` is untouched entirely and
+            // surfaces through `unmappedSources`.
+            discards: [],
+        };
+        return { modelConfig, plan };
+    },
+};
+//# sourceMappingURL=falcon_mamba.js.map

package/dist/import/foreign/falcon_mamba.js.map

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

package/dist/import/foreign/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * import/foreign/index.ts — the foreign-checkpoint weight-port surface.
+ *
+ * Warm-start this engine's `HybridMambaModel` from a published Mamba checkpoint:
+ * pass the checkpoint's `config.json` and its tensors, get back the model config
+ * to build plus a name-keyed set of weights, together with an explicit account of
+ * anything that did not map cleanly.
+ *
+ * Supported: Falcon-Mamba (Mamba-1) and Codestral-Mamba (Mamba-2). Transformer
+ * checkpoints are NOT portable at any tensor naming — distillation is the only
+ * route, and {@link foreignMambaAdapterFor} says so when it rejects one.
+ */
+export { FOREIGN_MAMBA_ADAPTERS, foreignMambaAdapterFor, portForeignMamba, portForeignMambaSafetensors, } from "./registry.js";
+export type { PortedCheckpoint } from "./registry.js";
+export { applyPortedWeights } from "./apply.js";
+export { executePortPlan, normaliseSourceName } from "./plan.js";
+export type { PortDiscard, PortOp, PortPlan, PortRule, PortedTensors, SynthesisedTarget, } from "./plan.js";
+export type { ForeignConfig, ForeignMambaAdapter, PortTarget } from "./adapter.js";
+export { falconMambaAdapter } from "./falcon_mamba.js";
+export { codestralMambaAdapter } from "./codestral_mamba.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/import/foreign/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/import/foreign/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,gBAAgB,EAChB,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACjE,YAAY,EACV,WAAW,EACX,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/import/foreign/index.js

@@ -0,0 +1,18 @@
+/**
+ * import/foreign/index.ts — the foreign-checkpoint weight-port surface.
+ *
+ * Warm-start this engine's `HybridMambaModel` from a published Mamba checkpoint:
+ * pass the checkpoint's `config.json` and its tensors, get back the model config
+ * to build plus a name-keyed set of weights, together with an explicit account of
+ * anything that did not map cleanly.
+ *
+ * Supported: Falcon-Mamba (Mamba-1) and Codestral-Mamba (Mamba-2). Transformer
+ * checkpoints are NOT portable at any tensor naming — distillation is the only
+ * route, and {@link foreignMambaAdapterFor} says so when it rejects one.
+ */
+export { FOREIGN_MAMBA_ADAPTERS, foreignMambaAdapterFor, portForeignMamba, portForeignMambaSafetensors, } from "./registry.js";
+export { applyPortedWeights } from "./apply.js";
+export { executePortPlan, normaliseSourceName } from "./plan.js";
+export { falconMambaAdapter } from "./falcon_mamba.js";
+export { codestralMambaAdapter } from "./codestral_mamba.js";
+//# sourceMappingURL=index.js.map

package/dist/import/foreign/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/import/foreign/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,gBAAgB,EAChB,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAYjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/import/foreign/plan.d.ts

@@ -0,0 +1,122 @@
+/**
+ * import/foreign/plan.ts — the ONE executor for a foreign-checkpoint weight port.
+ *
+ * A port is expressed declaratively: every target parameter of this engine's
+ * {@link HybridMambaModel} gets exactly one {@link PortRule} saying which source
+ * tensor feeds it and how the bytes are reshaped. Architecture adapters
+ * (`falcon_mamba.ts`, `codestral_mamba.ts`) only *describe* their rules — the
+ * matching, validation and transform logic lives here once, so a new
+ * architecture never re-implements it.
+ *
+ * The contract that makes a port trustworthy: NOTHING is silently dropped.
+ *   • a target with no source in the checkpoint is a `fill` rule and is reported
+ *     in {@link PortedCheckpoint.synthesisedTargets};
+ *   • a source tensor no rule consumed is reported in
+ *     {@link PortedCheckpoint.unmappedSources};
+ *   • a source tensor only PARTLY consumed (e.g. Mamba-2's gate rows, which this
+ *     engine's block has no branch for) is declared as a {@link PortDiscard};
+ *   • a shape that doesn't line up throws, naming the tensor and both shapes.
+ */
+import type { NamedTensor } from "../../export/tensors.js";
+/**
+ * How one source tensor becomes one target buffer.
+ *
+ *  • `copy`                 — element-for-element; source and target shapes must
+ *                             agree once size-1 axes are squeezed out. Linear
+ *                             weights need no transpose: HF stores
+ *                             `[out_features, in_features]` row-major and this
+ *                             engine's LINEAR_FORWARD_WGSL reads `W` as `(N, K)`
+ *                             = `[out, in]` row-major — the same layout.
+ *  • `convTaps`             — a depthwise conv kernel `[C, 1, K]` (PyTorch
+ *                             `nn.Conv1d(groups=C)`) → `[C, K]` with the taps
+ *                             REVERSED. PyTorch pads left by `K-1` and cross-
+ *                             correlates: `y[t] = Σ_j w[j]·x[t + j - (K-1)]`,
+ *                             while conv1d.ts computes
+ *                             `y[t] = Σ_k w[k]·x[t - k]`. Substituting
+ *                             `k = K-1-j` shows the two agree only when the tap
+ *                             axis is reversed.
+ *  • `rowSlice`             — keep rows `[start, start+count)` of a rank-2
+ *                             source. Used for Mamba-2's fused `in_proj`.
+ *  • `fill`                 — no source: fill the target with a constant.
+ *  • `negExpToSoftplusInv`  — `A_log` convention change. HF Mamba-2 uses
+ *                             `A = -exp(A_log)`; this engine's SSD kernel uses
+ *                             `A = -softplus(A_log)`. Re-express the same `A`:
+ *                             `target = softplus⁻¹(exp(source))`.
+ */
+export type PortOp = {
+    kind: "copy";
+} | {
+    kind: "convTaps";
+} | {
+    kind: "rowSlice";
+    start: number;
+    count: number;
+} | {
+    kind: "fill";
+    value: number;
+} | {
+    kind: "negExpToSoftplusInv";
+};
+/** How ONE target parameter of this engine is produced. */
+export interface PortRule {
+    /** Target parameter name, exactly as `HybridMambaModel.parameters()` names it. */
+    target: string;
+    /** Expected target shape (row-major), for validation and reporting. */
+    shape: number[];
+    /**
+     * Candidate source tensor names, in preference order — the first one present
+     * in the checkpoint is used. Empty means the target is synthesised (`fill`),
+     * because this architecture has no such tensor.
+     */
+    from: string[];
+    op: PortOp;
+    /** Why this isn't a plain copy / why there is no source. Required for `fill`. */
+    note?: string;
+}
+/** A source tensor deliberately consumed only in part. */
+export interface PortDiscard {
+    source: string;
+    /** How many source elements are left behind. */
+    elements: number;
+    reason: string;
+}
+/** The complete, architecture-specific description of a port. */
+export interface PortPlan {
+    /** Adapter id, e.g. `falcon_mamba`. */
+    adapter: string;
+    rules: PortRule[];
+    discards: PortDiscard[];
+}
+/** A target that no source tensor feeds, and the constant used instead. */
+export interface SynthesisedTarget {
+    target: string;
+    value: number;
+    reason: string;
+}
+/** The result of running a {@link PortPlan} over a checkpoint's tensors. */
+export interface PortedTensors {
+    adapter: string;
+    /** Target parameter name → buffer, sized exactly as the model expects. */
+    weights: Map<string, Float32Array>;
+    /** Checkpoint tensors that no rule consumed (e.g. an untied `lm_head.weight`). */
+    unmappedSources: string[];
+    /** Targets this architecture has no tensor for. */
+    synthesisedTargets: SynthesisedTarget[];
+    /** Source tensors consumed only in part. */
+    discardedSources: PortDiscard[];
+}
+/**
+ * Mistral publishes the same Mamba-2 weights twice: the HF conversion
+ * (`backbone.…`) and its native `consolidated.safetensors`, whose names carry a
+ * `model.` prefix. Strip it so one rule table serves both. The
+ * `embedding`/`embeddings` spelling difference is handled by the rules' `from`
+ * alternatives, not here.
+ */
+export declare function normaliseSourceName(name: string): string;
+/**
+ * Execute a plan against a checkpoint's tensors. Every rule must resolve; the
+ * first failure throws naming the offending tensor. Sources no rule touched are
+ * returned rather than ignored.
+ */
+export declare function executePortPlan(plan: PortPlan, tensors: NamedTensor[]): PortedTensors;
+//# sourceMappingURL=plan.d.ts.map

package/dist/import/foreign/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/import/foreign/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAI3D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,MAAM,GACd;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAIpC,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnC,kFAAkF;IAClF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,mDAAmD;IACnD,kBAAkB,EAAE,iBAAiB,EAAE,CAAC;IACxC,4CAA4C;IAC5C,gBAAgB,EAAE,WAAW,EAAE,CAAC;CACjC;AAID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAkHD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,aAAa,CAoDrF"}