@seanhogg/builderforce-memory-engine 2026.7.12 → 2026.9.27

package/src/import/foreign/plan.ts

@@ -0,0 +1,294 @@
+/**
+ * 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";
+
+// ── Transform operations ─────────────────────────────────────────────────────
+
+/**
+ * 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" };
+
+// ── Rules & plans ────────────────────────────────────────────────────────────
+
+/** 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[];
+}
+
+// ── Source-name normalisation ────────────────────────────────────────────────
+
+/**
+ * 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 function normaliseSourceName(name: string): string {
+  return name.startsWith("model.") ? name.slice("model.".length) : name;
+}
+
+// ── Execution ────────────────────────────────────────────────────────────────
+
+/** Product of a shape's dimensions (`[]` ⇒ 1). */
+function numel(shape: readonly number[]): number {
+  return shape.reduce((n, d) => n * d, 1);
+}
+
+/** Shape with size-1 axes removed — `[C, 1, K]` and `[C, K]` compare equal. */
+function squeeze(shape: readonly number[]): number[] {
+  const kept = shape.filter((d) => d !== 1);
+  return kept.length > 0 ? kept : [1];
+}
+
+function sameShape(a: readonly number[], b: readonly number[]): boolean {
+  return a.length === b.length && a.every((d, i) => d === b[i]);
+}
+
+/**
+ * `softplus⁻¹(y) = log(e^y − 1)`, evaluated so it neither overflows nor loses the
+ * small-`y` tail. Above ~30 `log(expm1(y))` and `y` agree to well inside f32
+ * precision, and `expm1` would have overflowed; below it, `expm1` keeps the
+ * precision `exp(y) - 1` would have thrown away.
+ */
+function softplusInverse(y: number): number {
+  if (!(y > 0)) {
+    throw new Error(`import/foreign: softplus⁻¹ needs a positive input, got ${y}`);
+  }
+  if (y > 30) return y;
+  return Math.log(Math.expm1(y));
+}
+
+/** Run one rule, returning the target buffer. Throws on any shape disagreement. */
+function applyRule(rule: PortRule, source: NamedTensor | null): Float32Array {
+  const want = numel(rule.shape);
+
+  if (rule.op.kind === "fill") {
+    return new Float32Array(want).fill(rule.op.value);
+  }
+  if (!source) {
+    // Unreachable via executePortPlan (which checks first) — kept so a direct
+    // caller gets a real message rather than a null dereference.
+    throw new Error(`import/foreign: rule for "${rule.target}" has no source tensor`);
+  }
+
+  const where = `"${source.name}" → "${rule.target}"`;
+
+  switch (rule.op.kind) {
+    case "copy":
+    case "negExpToSoftplusInv": {
+      if (!sameShape(squeeze(source.shape), squeeze(rule.shape))) {
+        throw new Error(
+          `import/foreign: ${where} shape mismatch — checkpoint has [${source.shape.join(", ")}], ` +
+            `this model expects [${rule.shape.join(", ")}]`,
+        );
+      }
+      if (source.data.length !== want) {
+        throw new Error(
+          `import/foreign: ${where} has ${source.data.length} elements, expected ${want}`,
+        );
+      }
+      if (rule.op.kind === "copy") return Float32Array.from(source.data);
+      const out = new Float32Array(want);
+      for (let i = 0; i < want; i++) out[i] = softplusInverse(Math.exp(source.data[i]!));
+      return out;
+    }
+
+    case "convTaps": {
+      const [channels, kernel] = squeeze(rule.shape) as [number, number];
+      const src = squeeze(source.shape);
+      if (!sameShape(src, [channels, kernel])) {
+        throw new Error(
+          `import/foreign: ${where} depthwise conv shape mismatch — checkpoint has ` +
+            `[${source.shape.join(", ")}], this model expects [${rule.shape.join(", ")}] ` +
+            `(a [channels, 1, kernel] PyTorch kernel squeezes to [channels, kernel])`,
+        );
+      }
+      const out = new Float32Array(want);
+      for (let c = 0; c < channels; c++) {
+        for (let k = 0; k < kernel; k++) {
+          // Reverse the tap axis — see PortOp.convTaps.
+          out[c * kernel + k] = source.data[c * kernel + (kernel - 1 - k)]!;
+        }
+      }
+      return out;
+    }
+
+    case "rowSlice": {
+      if (source.shape.length !== 2) {
+        throw new Error(
+          `import/foreign: ${where} rowSlice needs a rank-2 source, got ` +
+            `[${source.shape.join(", ")}]`,
+        );
+      }
+      const [rows, cols] = source.shape as [number, number];
+      const { start, count } = rule.op;
+      if (start < 0 || start + count > rows) {
+        throw new Error(
+          `import/foreign: ${where} rowSlice [${start}, ${start + count}) is outside the ` +
+            `checkpoint tensor's ${rows} rows — the source layout is not what this adapter expects`,
+        );
+      }
+      if (!sameShape(squeeze(rule.shape), squeeze([count, cols]))) {
+        throw new Error(
+          `import/foreign: ${where} rowSlice yields [${count}, ${cols}] but this model expects ` +
+            `[${rule.shape.join(", ")}]`,
+        );
+      }
+      return Float32Array.from(source.data.subarray(start * cols, (start + count) * cols));
+    }
+  }
+}
+
+/**
+ * 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 function executePortPlan(plan: PortPlan, tensors: NamedTensor[]): PortedTensors {
+  const byName = new Map<string, NamedTensor>();
+  for (const t of tensors) {
+    const name = normaliseSourceName(t.name);
+    byName.set(name, { ...t, name });
+  }
+
+  const weights = new Map<string, Float32Array>();
+  const synthesisedTargets: SynthesisedTarget[] = [];
+  const consumed = new Set<string>();
+
+  for (const rule of plan.rules) {
+    if (weights.has(rule.target)) {
+      throw new Error(`import/foreign: plan "${plan.adapter}" defines "${rule.target}" twice`);
+    }
+
+    if (rule.from.length === 0) {
+      if (rule.op.kind !== "fill") {
+        throw new Error(
+          `import/foreign: rule for "${rule.target}" names no source but is not a fill rule`,
+        );
+      }
+      weights.set(rule.target, applyRule(rule, null));
+      synthesisedTargets.push({
+        target: rule.target,
+        value: rule.op.value,
+        reason: rule.note ?? "this architecture has no corresponding tensor",
+      });
+      continue;
+    }
+
+    const source = rule.from.map((n) => byName.get(n)).find((t): t is NamedTensor => t != null);
+    if (!source) {
+      throw new Error(
+        `import/foreign: checkpoint is missing "${rule.from[0]}" (needed for "${rule.target}", ` +
+          `expected shape [${rule.shape.join(", ")}])` +
+          (rule.from.length > 1 ? `; also tried ${rule.from.slice(1).map((n) => `"${n}"`).join(", ")}` : ""),
+      );
+    }
+    consumed.add(source.name);
+    weights.set(rule.target, applyRule(rule, source));
+  }
+
+  const unmappedSources = [...byName.keys()].filter((n) => !consumed.has(n)).sort();
+
+  return {
+    adapter: plan.adapter,
+    weights,
+    unmappedSources,
+    synthesisedTargets,
+    discardedSources: plan.discards,
+  };
+}

package/src/import/foreign/registry.ts

@@ -0,0 +1,126 @@
+/**
+ * import/foreign/registry.ts — config-driven adapter selection and the public
+ * port entry points.
+ *
+ * Given a checkpoint's `config.json`, pick the adapter by `model_type` /
+ * `architectures` and run its plan. An architecture nobody claims fails loudly
+ * with the list of what IS supported — and, for a transformer checkpoint, says
+ * why no map could ever exist for it.
+ */
+
+import type { NamedTensor } from "../../export/tensors.js";
+import type { HybridMambaModelConfig } from "../../model/mamba_model.js";
+import { safetensorsToTensors } from "../safetensors.js";
+import { executePortPlan, type PortDiscard, type PortedTensors, type SynthesisedTarget } from "./plan.js";
+import { falconMambaAdapter } from "./falcon_mamba.js";
+import { codestralMambaAdapter } from "./codestral_mamba.js";
+import type { ForeignConfig, ForeignMambaAdapter } from "./adapter.js";
+
+/** Every foreign SSM architecture this engine can warm-start from. */
+export const FOREIGN_MAMBA_ADAPTERS: readonly ForeignMambaAdapter[] = [
+  falconMambaAdapter,
+  codestralMambaAdapter,
+];
+
+/** A completed port: the model to build, its weights, and what didn't line up. */
+export interface PortedCheckpoint extends PortedTensors {
+  /** Construct a `HybridMambaModel` with this to receive {@link PortedTensors.weights}. */
+  modelConfig: HybridMambaModelConfig;
+}
+
+export type { PortDiscard, SynthesisedTarget };
+
+// ── Detection ────────────────────────────────────────────────────────────────
+
+function architecturesOf(config: ForeignConfig): string[] {
+  const raw = config["architectures"];
+  return Array.isArray(raw) ? raw.filter((a): a is string => typeof a === "string") : [];
+}
+
+function modelTypeOf(config: ForeignConfig): string | undefined {
+  const raw = config["model_type"];
+  return typeof raw === "string" ? raw : undefined;
+}
+
+/**
+ * A checkpoint is a transformer when any declared architecture carries an
+ * attention-stack marker. Recognised only to give a better error: attention
+ * weights (Q/K/V/O, positional embeddings, per-token KV cache) have no
+ * counterpart in a state-space mixer, so no rename or reshape can port them.
+ */
+function looksLikeTransformer(architectures: string[], modelType: string | undefined): boolean {
+  const haystack = [...architectures, modelType ?? ""].join(" ").toLowerCase();
+  if (haystack.includes("mamba") || haystack.includes("ssm")) return false;
+  return /llama|mistral|qwen|gpt|phi|gemma|falcon(?!_?mamba)|starcoder|deepseek|olmo|attention|forcausallm/.test(
+    haystack,
+  );
+}
+
+function supportedList(): string {
+  return FOREIGN_MAMBA_ADAPTERS.map(
+    (a) => `${a.label} — architectures ${a.architectures.join(" / ")}, model_type ${a.modelTypes.join(" / ")}`,
+  ).join("; ");
+}
+
+/**
+ * The adapter that claims this checkpoint. Throws — never guesses — when no
+ * adapter matches, because a wrong map produces a model that loads and then
+ * generates noise.
+ */
+export function foreignMambaAdapterFor(config: ForeignConfig): ForeignMambaAdapter {
+  const architectures = architecturesOf(config);
+  const modelType = modelTypeOf(config);
+
+  const byArch = FOREIGN_MAMBA_ADAPTERS.find((a) =>
+    architectures.some((name) => a.architectures.includes(name)),
+  );
+  if (byArch) return byArch;
+
+  const byType = modelType
+    ? FOREIGN_MAMBA_ADAPTERS.find((a) => a.modelTypes.includes(modelType))
+    : undefined;
+  if (byType) return byType;
+
+  const seen =
+    architectures.length > 0
+      ? `architectures [${architectures.join(", ")}]`
+      : modelType
+        ? `model_type "${modelType}"`
+        : "a config declaring neither `architectures` nor `model_type`";
+
+  if (looksLikeTransformer(architectures, modelType)) {
+    throw new Error(
+      `import/foreign: ${seen} is a TRANSFORMER checkpoint — its attention weights ` +
+        `(q/k/v/o projections, positional embeddings) have no counterpart in a state-space ` +
+        `mixer, so no weight port can exist for it at any tensor naming. Transformer coders ` +
+        `(IQuest, NousCoder, Maincoder and the like) can only be brought across by ` +
+        `DISTILLATION — train this engine's SSM against the transformer's outputs. ` +
+        `Weight porting is supported only for: ${supportedList()}.`,
+    );
+  }
+
+  throw new Error(
+    `import/foreign: unsupported checkpoint — ${seen}. Supported: ${supportedList()}. ` +
+      `A transformer checkpoint cannot be weight-ported at all; distillation is the only route.`,
+  );
+}
+
+// ── Porting ──────────────────────────────────────────────────────────────────
+
+/**
+ * Port a foreign checkpoint's tensors onto this engine's parameters. The result
+ * is device-free — {@link applyPortedWeights} uploads it into a live model.
+ */
+export function portForeignMamba(config: ForeignConfig, tensors: NamedTensor[]): PortedCheckpoint {
+  const adapter = foreignMambaAdapterFor(config);
+  const { modelConfig, plan } = adapter.describe(config);
+  return { ...executePortPlan(plan, tensors), modelConfig };
+}
+
+/** Convenience: port straight from a `.safetensors` buffer. */
+export function portForeignMambaSafetensors(
+  config: ForeignConfig,
+  bytes: Uint8Array,
+): PortedCheckpoint {
+  return portForeignMamba(config, safetensorsToTensors(bytes));
+}

package/src/import/index.ts

@@ -4,8 +4,38 @@
  * The inverse of {@link ../export}: read a `.safetensors` checkpoint back into a
  * live {@link ../lm/evermind_lm.EvermindLM}. Round-trips Evermind's own exports,
  * and warm-starts a foreign SSM checkpoint via a `rename` map.
+ *
+ * `./foreign` is the same seam for checkpoints that were never ours: published
+ * Mamba-1/Mamba-2 models, whose tensor names, layouts and `A_log`/conv
+ * conventions are reconciled onto `HybridMambaModel`'s parameters by a
+ * config-selected adapter.
  */
 
 export { safetensorsToTensors } from "./safetensors.js";
 export { importEvermind, importEvermindTensors, inferArchFromTensors } from "./evermind.js";
 export type { ImportOptions } from "./evermind.js";
+
+// ── Foreign checkpoints (Falcon-Mamba / Codestral-Mamba → HybridMambaModel) ────
+export {
+  FOREIGN_MAMBA_ADAPTERS,
+  foreignMambaAdapterFor,
+  portForeignMamba,
+  portForeignMambaSafetensors,
+  applyPortedWeights,
+  executePortPlan,
+  normaliseSourceName,
+  falconMambaAdapter,
+  codestralMambaAdapter,
+} from "./foreign/index.js";
+export type {
+  ForeignConfig,
+  ForeignMambaAdapter,
+  PortTarget,
+  PortDiscard,
+  PortOp,
+  PortPlan,
+  PortRule,
+  PortedCheckpoint,
+  PortedTensors,
+  SynthesisedTarget,
+} from "./foreign/index.js";

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * MambaCode.js – Entry Point (v2.0.0)
+ * @seanhogg/builderforce-memory-engine – entry point
  */
 
 // ── Model classes ─────────────────────────────────────────────────────────────
@@ -22,7 +22,6 @@ export {
     DEFAULT_MOE_CONFIG,
     DEFAULT_MOE_SEED,
     MoETrainer,
-    EvermindModelPackage,
 } from './moe/index.js';
 export type {
     MoEConfig,
@@ -31,23 +30,82 @@ export type {
     MoESample,
     MoETrainOptions,
     MoEEpochResult,
+} from './moe/index.js';
+
+// ── Evermind (the .evermind artifact + the shared learning pipeline) ───────────
+export {
+    EvermindModelPackage,
+    adaptAndDiff,
+    EVERMIND_ADAPT_MAX_CHARS,
+    EVERMIND_ADAPT_WINDOW_TOKENS,
+    parseDeltaLearnPayload,
+    buildDeltaLearnPayload,
+    decodeDeltaPayload,
+    deltaUnusableReason,
+    MAX_DELTA_B64_CHARS,
+    DELTA_LABEL_MAX_CHARS,
+    mergeCheckpointDiffs,
+    meanEvalLoss,
+    sequenceLoss,
+    EVAL_MAX_TOKENS,
+} from './evermind/index.js';
+export type {
     EvermindModelManifest,
     EvermindModelCard,
     EvermindModelType,
     EvermindModality,
     PackageMeta,
     ValidationResult,
-} from './moe/index.js';
+    AdaptResult,
+    AdaptOptions,
+    AdaptTokenizer,
+    DeltaLearnPayload,
+    DeltaParseResult,
+    MergeResult,
+    EvalExample,
+    EvalTokenizer,
+} from './evermind/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';
+export { EvermindLM, EvermindLMTrainer, DEFAULT_LM_CONFIG, DEFAULT_LM_SEED, logProbOfToken } from './lm/index.js';
+// CPU text→vector embedder — SSM-embedding recall with no GPU.
+export { EvermindTextEmbedder } from './lm/index.js';
+export type { EvermindLMConfig, LMGenerateOptions, TextCodec, EvermindLMTrainOptions, EvermindLMDecodeState } from './lm/index.js';
+export type { TextEmbedder, EmbedderCodec } from './lm/index.js';
+export { AdamW, adamwUpdateInPlace } from './optim/adamw.js';
+export type { AdamWOptions, OptimTarget, OptimParam, ShardSpec, AdamWKernelStep } from './optim/adamw.js';
+
+// PEFT / efficient-training toolkit (LoRA, QLoRA, mixed precision, checkpointing).
+export { LoRAAdapter, EvermindLMLoRA, quantizeBase } from './training/lora.js';
+export type { LoRAConfig, LoRAFitOptions, BaseQuant } from './training/lora.js';
+export { DynamicLossScaler, roundFp16, fp16View } from './training/mixed_precision.js';
+export type { LossScalerOptions } from './training/mixed_precision.js';
 
 // ── Training ──────────────────────────────────────────────────────────────────
 
-export { MambaTrainer } from './training/trainer.js';
+export { MambaTrainer, cpuDimsFor, buildChunks, buildBatches, WSLA_MAX_DELTA } from './training/trainer.js';
+export type { TrainOptions } from './training/trainer.js';
+// The exact CPU forward + backward the trainer differentiates with. Exported so a
+// host can compute gradients (or gradient-check the model) without a GPU.
+export {
+    cpuModelForward, cpuModelLoss, cpuModelBackward,
+    zeroCpuModelGrads, toNamedGrads, namedWeights, cpuWeightsFromNamed,
+    paramMatrixShape, DEFAULT_LORA_TARGETS, CPU_GRADIENT_LAYER_TYPES,
+} from './training/model_cpu.js';
+export type {
+    CpuModelDims, CpuModelWeights, CpuModelGrads, CpuBackwardResult, CpuBackwardOptions, CpuGradientLayerType,
+} from './training/model_cpu.js';
+export {
+    mamba1CpuForward, mamba1CpuBackward, zeroMamba1Grads,
+    MAMBA1_PARAM_NAMES, A_LOG_CLAMP_LO, A_LOG_CLAMP_HI,
+} from './training/mamba1_cpu.js';
+export type {
+    Mamba1CpuWeights, Mamba1CpuDims, Mamba1CpuCache, Mamba1CpuGrads, Mamba1CpuForwardResult,
+} from './training/mamba1_cpu.js';
+export {
+    linearForward, linearBackward, rmsNormForward, rmsNormBackward,
+    silu, siluGrad, softplus, sigmoid, RMSNORM_EPS,
+} from './training/cpu_ops.js';
 export {
     Tensor,
     backward,
@@ -62,6 +120,7 @@ export {
 // ── Tokenizer ─────────────────────────────────────────────────────────────────
 
 export { BPETokenizer } from './tokenizer/bpe.js';
+export type { BPETokenizerSpec } from './tokenizer/bpe.js';
 export type { BPEEncodeOptions, PadSide, HuggingFaceTokenizerSpec, SpecialTokenOverrides } from './tokenizer/bpe.js';
 
 // ── Modality codecs (media ⇄ tokens; lets EvermindLM generate video) ────────────
@@ -123,6 +182,34 @@ export {
 } from './import/index.js';
 export type { ImportOptions } from './import/index.js';
 
+// ── Foreign weight port (Falcon-Mamba / Codestral-Mamba → HybridMambaModel) ────
+// Transformer checkpoints are NOT portable — distillation is the only route, and
+// `foreignMambaAdapterFor` rejects them saying so.
+
+export {
+    FOREIGN_MAMBA_ADAPTERS,
+    foreignMambaAdapterFor,
+    portForeignMamba,
+    portForeignMambaSafetensors,
+    applyPortedWeights,
+    executePortPlan,
+    normaliseSourceName,
+    falconMambaAdapter,
+    codestralMambaAdapter,
+} from './import/index.js';
+export type {
+    ForeignConfig,
+    ForeignMambaAdapter,
+    PortTarget,
+    PortDiscard,
+    PortOp,
+    PortPlan,
+    PortRule,
+    PortedCheckpoint,
+    PortedTensors,
+    SynthesisedTarget,
+} from './import/index.js';
+
 // ── Benchmarking (held-out perplexity / accuracy / throughput + A/B) ──────────
 
 export {
@@ -133,6 +220,10 @@ export {
     compareReports,
     corpusToSequences,
     trainAndBenchmark,
+    benchmarkAdaptationCost,
+    formatAdaptationCostReport,
+    tokenWindows,
+    adaptationsAfterSkip,
     argmax as benchArgmax,
     topKIndices,
     perplexity,
@@ -147,6 +238,9 @@ export type {
     ComparisonReport,
     TrainAndBenchmarkOptions,
     TrainAndBenchmarkResult,
+    AdaptationCostOptions,
+    AdaptationCostPoint,
+    AdaptationCostReport,
 } from './bench/index.js';
 
 // ── Checkpoint integrity (CRC-32 + trailer) ───────────────────────────────────
@@ -162,6 +256,7 @@ export {
     applyCheckpointDiff,
 } from './utils/delta.js';
 export type { RowDelta } from './utils/delta.js';
+export { bytesToBase64, base64ToBytes } from './utils/base64.js';
 
 // ── Seeded RNG (reproducible weight init) ─────────────────────────────────────
 
@@ -222,6 +317,7 @@ export { CONV1D_FORWARD_WGSL, CONV1D_BACKWARD_WGSL }
     from './kernels/conv1d.js';
 export { LINEAR_FORWARD_WGSL, LINEAR_BACKWARD_WGSL }
     from './kernels/linear_projection.js';
+export { COL_SLICE_WGSL, COL_SLICE_ENTRY, dispatchColumnSlice } from './kernels/slice.js';
 export { WEIGHT_UPDATE_WGSL, GRAD_CLIP_WGSL }
     from './kernels/weight_update.js';
 export { ACTIVATIONS_WGSL, ACTIVATIONS_BACKWARD_WGSL, SOFTMAX_FORWARD_WGSL, SOFTMAX_BACKWARD_WGSL }
@@ -271,8 +367,3 @@ export type {
 } from './limbic/index.js';
 
 export { LIMBIC_AFFECT_WGSL } from './kernels/limbic_affect.js';
-
-// ── Version ───────────────────────────────────────────────────────────────────
-
-export const VERSION     = '2.0.0';
-export const DESCRIPTION = 'MambaCode.js: WebGPU-accelerated Mamba-1/2/3 and Hybrid SSM for browser code models';

package/src/kernels/selective_scan.ts

@@ -132,21 +132,27 @@ fn forward_scan(
         // ---- Kogge-Stone inclusive prefix scan within tile ----
         // Associative operator: (a1, b1) ∘ (a2, b2) = (a1*a2, a1*b2 + b1)
         // This computes cumulative state recurrence in log2(TILE) steps.
+        // NOTE the barrier placement. Both barriers MUST sit in uniform control
+        // flow — every invocation in the workgroup has to reach them. The earlier
+        // version put the first workgroupBarrier() INSIDE the if (lid >= stride)
+        // branch, which is a WGSL uniformity violation: shader creation fails on a
+        // conformant implementation. Computing into locals first, then writing
+        // back after a uniform barrier, is the correct read-then-write split.
         var stride: u32 = 1u;
         loop {
             if (stride >= TILE) { break; }
+            var new_a  = wg_a[lid];
+            var new_bu = wg_bu[lid];
             if (lid >= stride) {
-                let prev_a  = wg_a[lid - stride];
-                let prev_bu = wg_bu[lid - stride];
-                // Combine: new_state = prev_a * cur_a (product of A_bars)
-                //                      new_bu  = prev_a * cur_bu + prev_bu
-                let new_a  = prev_a * wg_a[lid];
-                let new_bu = prev_a * wg_bu[lid] + prev_bu;
-                workgroupBarrier();
-                wg_a[lid]  = new_a;
-                wg_bu[lid] = new_bu;
+                // Combine: new_a  = prev_a * cur_a (product of A_bars)
+                //          new_bu = prev_a * cur_bu + prev_bu
+                new_a  = wg_a[lid - stride] * new_a;
+                new_bu = wg_a[lid - stride] * new_bu + wg_bu[lid - stride];
             }
             workgroupBarrier();
+            wg_a[lid]  = new_a;
+            wg_bu[lid] = new_bu;
+            workgroupBarrier();
             stride = stride << 1u;
         }