@seanhogg/builderforce-memory-engine 2026.6.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Hogg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,393 @@
+# MambaCode.js
+
+> WebGPU-accelerated Mamba-1/2/3 and Hybrid SSM library — written in **TypeScript**, compiled for use in any JavaScript application.
+
+[![npm](https://img.shields.io/npm/v/@seanhogg/mambacode.js)](https://www.npmjs.com/package/@seanhogg/mambacode.js)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+MambaCode.js is a **TypeScript-first** library that brings the Mamba family of State Space Models to the browser via WebGPU. Version 2.0.0 adds **Mamba-2** (SSD), **Mamba-3** (complex-valued MIMO + ET discretisation), and **hybrid attention** layers, while remaining fully backward-compatible with Mamba-1 checkpoints.
+
+> 📖 **New to MambaCode.js?** Start with the [Getting Started Guide](./docs/getting-started.md).
+
+---
+
+## What's New in v2.0.0
+
+| Feature | Detail |
+|---|---|
+| **Mamba-2 (SSD)** | Structured State Space Duality — chunked matmul scan, multi-head, scalar A, inner RMSNorm |
+| **Mamba-3** | Complex-valued states (ℂ^N), ET discretisation, MIMO recurrence, 2× smaller state size |
+| **AttentionBlock** | Causal multi-head attention for hybrid (Jamba/Zamba) layer schedules |
+| **HybridMambaModel** | Per-layer type schedule — mix mamba1/2/3/attention freely |
+| **MBJS v2 format** | Layer-type metadata in checkpoint header; v1 files still load unchanged |
+| **`MambaBlock` alias** | Kept as deprecated alias for `Mamba1Block` until 3.0.0 |
+
+---
+
+## Key Features
+
+| Feature | Detail |
+|---|---|
+| **TypeScript-first** | Full type declarations shipped with the package |
+| **Plain JS compatible** | Import the compiled `dist/` in any JavaScript project |
+| **SSM variants** | Mamba-1 (S6), Mamba-2 (SSD), Mamba-3 (complex MIMO+ET) |
+| **Hybrid models** | Jamba/Zamba-style mixed SSM + attention schedules |
+| **Hardware target** | WebGPU (WGSL) — Chrome 113+, Edge 113+, Firefox Nightly |
+| **No heavy frameworks** | Zero TensorFlow.js / Transformers.js dependencies |
+| **On-device training** | Tape-based autograd + AdamW GPU optimizer |
+| **Quantization** | FP16 weights, Int8 activations |
+| **Tokenizer** | Browser-side BPE (Qwen2.5-Coder compatible) |
+| **WSLA mode** | Fast-adapt: trains only the selective projection rows |
+
+---
+
+## Installation
+
+```bash
+npm install mambacode.js
+```
+
+Build from source:
+
+```bash
+npm run build   # compiles TypeScript → dist/
+```
+
+---
+
+## Quick Start
+
+### Mamba-1 (backward-compatible, unchanged)
+
+```ts
+import { MambaModel, MambaTrainer, BPETokenizer, initWebGPU } from 'mambacode.js';
+
+const { device } = await initWebGPU();
+const tokenizer  = new BPETokenizer();
+await tokenizer.load('/vocab.json', '/merges.txt');
+
+const model = new MambaModel(device, {
+  vocabSize : tokenizer.vocabSize,
+  dModel    : 512,
+  numLayers : 8,
+});
+
+await model.loadWeights(await (await fetch('/checkpoint.bin')).arrayBuffer());
+const ids = await model.generate(tokenizer.encode('function add('), 200);
+console.log(tokenizer.decode(ids));
+```
+
+### Mamba-2 (SSD)
+
+```ts
+import { HybridMambaModel } from 'mambacode.js';
+
+const model = new HybridMambaModel(device, {
+  vocabSize : tokenizer.vocabSize,
+  dModel    : 512,
+  numLayers : 8,
+  nHeads    : 8,
+  layers    : Array(8).fill({ type: 'mamba2' }),
+});
+```
+
+### Mamba-3 (complex states)
+
+```ts
+const model = new HybridMambaModel(device, {
+  vocabSize : tokenizer.vocabSize,
+  dModel    : 512,
+  numLayers : 8,
+  nHeads    : 8,
+  layers    : Array(8).fill({ type: 'mamba3' }),
+});
+```
+
+### Hybrid (Jamba-style: every 4th layer is attention)
+
+```ts
+const model = new HybridMambaModel(device, {
+  vocabSize : tokenizer.vocabSize,
+  dModel    : 512,
+  numLayers : 12,
+  nHeads    : 8,
+  layers    : Array.from({ length: 12 }, (_, i) => ({
+    type: i % 4 === 3 ? 'attention' : 'mamba2',
+  })),
+});
+```
+
+---
+
+## Architecture Reference
+
+### Mamba-1 Block (S6)
+
+```
+Input (B, L, D)
+  └─ RMSNorm
+  └─ in_proj → x, z (gate)
+                x → conv1d → SiLU → x_proj → Δ, B, C
+                                              Δ → dt_proj → softplus
+                                              Selective Scan S6
+                                              h_t = Ā·h_{t-1} + B̄·x_t
+                                              y_t = C·h_t + D·x_t
+  └─ y * SiLU(z)
+  └─ out_proj + residual
+```
+
+### Mamba-2 Block (SSD)
+
+```
+Input (B, L, D)
+  └─ RMSNorm
+  └─ in_proj → [x (D_inner), B (G·N), C (G·N), dt (H)]
+               conv1d over x, B, C (fused)
+               SSD scan: A_bar = exp(-softplus(A) · softplus(dt))
+                          h_t = A_bar · h_{t-1} + B · x_t
+                          y_t = C · h_t
+  └─ inner RMSNorm
+  └─ out_proj + residual
+```
+
+### Mamba-3 Block (complex MIMO, ET)
+
+```
+Input (B, L, D)
+  └─ Same structure as Mamba-2 but:
+     • A ∈ ℂ (log|A|, arg(A)) per head
+     • A_bar = exp(Δ·A)  [complex]
+     • B_bar = (A_bar − 1)·A⁻¹·B  [ET, exact]
+     • h_t ∈ ℂ^(N/2), y_t = Re(C·h_t)
+```
+
+### AttentionBlock (causal MHA)
+
+```
+Input (B, L, D)
+  └─ RMSNorm
+  └─ wQKV → Q, K, V (B, L, H, d_head)
+  └─ scores = Q·Kᵀ / √d_head  (causal mask)
+  └─ softmax → weighted V sum
+  └─ concat heads → wO + residual
+  [optional FFN sublayer]
+```
+
+---
+
+## File Structure
+
+```
+src/
+├── index.ts                         ← public API entry point (v2.0.0)
+├── kernels/
+│   ├── selective_scan.ts            ← WGSL: S6 forward/backward (Mamba-1)
+│   ├── ssd.ts                       ← WGSL: chunked SSD forward/backward (Mamba-2)
+│   ├── complex_ssd.ts               ← WGSL: complex SSD + ET + MIMO (Mamba-3)
+│   ├── attention.ts                 ← WGSL: tiled causal MHA forward/backward
+│   ├── conv1d.ts                    ← WGSL: 1D causal convolution (+ groups param)
+│   ├── linear_projection.ts         ← WGSL: tiled GEMM
+│   ├── weight_update.ts             ← WGSL: AdamW + gradient clipping
+│   └── activations.ts               ← WGSL: SiLU, RMSNorm, Softmax
+├── model/
+│   ├── sequence_layer.ts            ← SequenceLayer interface (LayerType, LayerParam)
+│   ├── mamba1_block.ts              ← Mamba1Block (renamed from MambaBlock)
+│   ├── mamba2_block.ts              ← Mamba2Block (SSD)
+│   ├── mamba3_block.ts              ← Mamba3Block (complex + MIMO + ET)
+│   ├── attention_block.ts           ← AttentionBlock (causal MHA)
+│   └── mamba_model.ts               ← HybridMambaModel + MambaModel alias
+├── training/
+│   ├── autograd.ts                  ← Tape-based AD + loss helpers
+│   └── trainer.ts                   ← MambaTrainer (AdamW, WSLA)
+├── tokenizer/
+│   └── bpe.ts                       ← Browser-side BPE tokenizer
+└── utils/
+    ├── gpu_utils.ts                 ← WebGPU device/buffer management
+    └── quantization.ts              ← FP16 / Int8 quantization
+
+tools/                               ← Model building & checkpoint tooling
+├── generate-bin.js                  ← CLI: generate an MBJS v2 checkpoint from scratch
+├── pretrain.html                    ← Browser: pretrain a model on a text corpus
+└── convert.html                     ← Browser: convert HuggingFace Mamba → MBJS format
+
+tests/
+├── kernels.test.ts
+├── autograd.test.ts
+├── bpe.test.ts
+└── quantization.test.ts
+
+docs/
+├── getting-started.md
+├── integration-architecture.md
+├── weight-lifecycle.md
+├── api-reference.md
+└── prd-mambacode-v2-v3-hybrid.md    ← PRD: Mamba-2/3/hybrid implementation spec
+```
+
+---
+
+## Tools
+
+The `tools/` directory contains model-building and checkpoint utilities that operate at the mambacode.js level. These are **not part of the MambaKit API** — they are for authors who want to build, pretrain, or convert model weights.
+
+### `tools/generate-bin.js` — Generate a blank MBJS checkpoint
+
+Creates a properly-shaped MBJS v2 `.bin` file with randomly initialised weights. Useful as a starting point before pretraining.
+
+```bash
+node tools/generate-bin.js                        # nano → model.bin
+node tools/generate-bin.js --size small           # small preset
+node tools/generate-bin.js --size nano --out my.bin
+```
+
+The weights are **not pretrained** — use `pretrain.html` to run language-model training.
+
+### `tools/pretrain.html` — Browser pretraining UI
+
+In-browser training loop over a text corpus. Requires a WebGPU-capable browser.
+
+```bash
+npm run build
+npm run serve
+# Open http://localhost:3000/tools/pretrain.html
+# Load a corpus (e.g. TinyStories), configure size/epochs, click Start Training
+# Download the resulting .bin checkpoint
+```
+
+### `tools/convert.html` — HuggingFace → MBJS converter
+
+Converts `state-spaces/mamba` safetensors checkpoints to MBJS format.
+
+```bash
+# Open http://localhost:3000/tools/convert.html
+# Drop model.safetensors from huggingface.co/state-spaces/mamba-130m
+# Download converted .bin
+```
+
+---
+
+## WGSL Kernels
+
+| Kernel file | Entry points | Used by |
+|---|---|---|
+| `selective_scan.ts` | `forward_scan`, `forward_reduce`, `selective_scan_backward` | Mamba-1 |
+| `ssd.ts` | `ssd_chunk_forward`, `ssd_chunk_backward` | Mamba-2 |
+| `complex_ssd.ts` | `complex_ssd_forward`, `complex_ssd_backward` | Mamba-3 |
+| `attention.ts` | `attention_forward`, `attention_value`, `attention_backward` | Attention |
+| `conv1d.ts` | `conv1d_forward`, `conv1d_backward_dx`, `conv1d_backward_dw` | All SSM |
+| `linear_projection.ts` | `linear_forward`, `linear_backward_dX`, `linear_backward_dW` | All layers |
+| `activations.ts` | `silu_forward`, `rmsnorm_forward`, `softmax_forward_simple` | All layers |
+| `weight_update.ts` | `adamw_update`, `grad_norm_reduce`, `grad_clip_scale` | Training |
+
+---
+
+## MBJS Binary Format
+
+### Version 1 (legacy, still readable)
+
+```
+[0..3]   magic   = 0x4D424A53 ('MBJS')
+[4..7]   version = 1
+[8..11]  nParams : uint32
+[12 ..]  numel[i] : uint32  (×nParams)
+[data]   float32 values
+```
+
+### Version 2 (written by default from v2.0.0)
+
+```
+[0..3]   magic   = 0x4D424A53
+[4..7]   version = 2
+[8..11]  nLayers : uint32
+[12 ..]  layerType[i] : uint8  (0=mamba1, 1=mamba2, 2=mamba3, 3=attention)
+[pad]    aligned to 4 bytes
+[next4]  nParams : uint32
+[next..]  numel[i] : uint32  (×nParams)
+[data]   float32 values
+```
+
+Version 1 files are loaded transparently — all layers assumed `mamba1`.
+
+---
+
+## Migration from v1.x
+
+```ts
+// v1.x — no change needed (mamba1 default is preserved)
+const model = new MambaModel(device, config);
+
+// v2.x — opt into Mamba-2
+const model = new HybridMambaModel(device, { ...config, layers: Array(8).fill({ type: 'mamba2' }) });
+
+// v2.x — MambaBlock is a deprecated alias for Mamba1Block; both still work
+import { MambaBlock, Mamba1Block } from 'mambacode.js';
+```
+
+---
+
+## Testing
+
+```bash
+npm test        # unit tests (no GPU required)
+npm run build   # compile TypeScript → dist/
+npm run lint    # ESLint
+```
+
+---
+
+## Browser Compatibility
+
+| Browser | Version | Status |
+|---|---|---|
+| Chrome | 113+ | ✅ Supported |
+| Edge | 113+ | ✅ Supported |
+| Firefox | Nightly | ✅ (flag: `dom.webgpu.enabled`) |
+| Safari | 18+ | ⚠️ Partial |
+| Node.js | — | ❌ Not supported |
+
+---
+
+## Acknowledgements
+
+- **Mamba-3** — Lahoti et al., *Mamba: The Hard Way* (arXiv 2603.15569, ICLR 2026)
+- **Mamba-2** — Dao & Gu, *Transformers are SSMs* (arXiv 2405.21060, 2024)
+- **Mamba-1** — Gu & Dao, *Mamba: Linear-Time Sequence Modeling with Selective State Spaces* (arXiv 2312.00752, 2023)
+
+---
+
+## Professional Platform
+
+**Want managed infrastructure for your MambaCode.js models?**
+
+[**Builderforce.ai**](https://builderforce.ai) is the professional enterprise platform built on MambaCode.js. It provides:
+
+- **In-browser LoRA training** — fine-tune up to 2B-parameter models on instruction datasets using the MambaCode.js WebGPU kernels, entirely client-side
+- **Hybrid Local Brain** — the Mamba State Engine runs a selective scan alongside Transformers.js inference for persistent agent memory, powered by MambaCode.js WGSL kernels
+- **Dataset generation** — LLM-assisted JSONL instruction dataset creation with streaming progress
+- **Workforce Registry** — publish trained models as specialist AI agents; discoverable and hirable by the community
+- **Agent portability** — `AgentPackage` bundles the LoRA adapter, `MambaStateSnapshot`, and agent profile into a single portable JSON artifact
+- **BuilderForce Agents mesh** — trained agents deploy as self-hosted coding agents via [BuilderForce Agents](https://builderforce.ai), orchestrated from Builderforce
+
+Use MambaCode.js to build and experiment locally. Use Builderforce.ai to deploy, manage, and share at scale.
+
+```
+MambaCode.js (WebGPU kernels)
+      ↓
+  SSM.js (session API + runtime + memory)
+      ↓
+ Builderforce.ai (enterprise IDE + training + registry)
+      ↓
+   BuilderForce Agents (self-hosted agent mesh)
+```
+
+---
+
+## Consolidated Gap Register
+
+- **Release publish blocked by NPM_TOKEN permissions** (`.github/workflows/release.yml`): the `2026.5.31` tag failed `npm publish` with a 404 PUT. The package exists on npm (maintainer `seanhogg`) and `npm whoami` passes, so the `NPM_TOKEN` secret authenticates but lacks read-write on `@seanhogg/mambacode.js` (read-only token, wrong account, or a granular token whose allowlist omits the package). The workflow now fails fast with this diagnosis, but the actual fix is registry-side and manual: rotate `NPM_TOKEN` to an Automation/granular token with publish rights, then re-push the tag. Unblocks every downstream consumer pinned to a published `@seanhogg/mambacode.js` version.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * MambaCode.js – Entry Point (v2.0.0)
+ */
+export { HybridMambaModel, MambaModel } from './model/mamba_model.js';
+export { Mamba1Block } from './model/mamba1_block.js';
+export { Mamba2Block } from './model/mamba2_block.js';
+export { Mamba3Block } from './model/mamba3_block.js';
+export { AttentionBlock } from './model/attention_block.js';
+export { MambaBlock } from './model/mamba1_block.js';
+export { MambaTrainer } from './training/trainer.js';
+export { Tensor, backward, enableGrad, noGrad, clearTape, recordOperation, crossEntropyLoss, crossEntropyGrad, } from './training/autograd.js';
+export { BPETokenizer } from './tokenizer/bpe.js';
+export { SeededRng, setInitSeed, randn, gaussianArray } from './utils/rng.js';
+export type { HybridMambaModelConfig, MambaModelConfig, ModelForwardResult, SamplingOptions, LayerSpec, } from './model/mamba_model.js';
+export type { SequenceLayer, LayerParam, LayerType, LayerForwardResult } from './model/sequence_layer.js';
+export type { Mamba1BlockConfig, BlockParam, BlockCache, BlockForwardResult, MambaBlockConfig } from './model/mamba1_block.js';
+export type { Mamba2BlockConfig, Mamba2Cache } from './model/mamba2_block.js';
+export type { Mamba3BlockConfig, Mamba3Cache } from './model/mamba3_block.js';
+export type { AttentionBlockConfig, AttentionCache } from './model/attention_block.js';
+export { initWebGPU, createStorageBuffer, createEmptyStorageBuffer, createUniformBuffer, createComputePipeline, createBindGroup, dispatchKernel, readBuffer, uploadBuffer, cdiv, } from './utils/gpu_utils.js';
+export { quantizeFp16, dequantizeFp16, floatToFp16, fp16ToFloat, quantizeInt8, dequantizeInt8, quantizeInt8PerChannel, dequantizeInt8PerChannel, estimateMemory, } from './utils/quantization.js';
+export { SELECTIVE_SCAN_FORWARD_WGSL, SELECTIVE_SCAN_BACKWARD_WGSL } from './kernels/selective_scan.js';
+export { CONV1D_FORWARD_WGSL, CONV1D_BACKWARD_WGSL } from './kernels/conv1d.js';
+export { LINEAR_FORWARD_WGSL, LINEAR_BACKWARD_WGSL } from './kernels/linear_projection.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 } from './kernels/activations.js';
+export { SSD_FORWARD_WGSL, SSD_BACKWARD_WGSL } from './kernels/ssd.js';
+export { COMPLEX_SSD_FORWARD_WGSL, COMPLEX_SSD_BACKWARD_WGSL } from './kernels/complex_ssd.js';
+export { ATTENTION_FORWARD_WGSL, ATTENTION_BACKWARD_WGSL, SOFTMAX_WGSL } from './kernels/attention.js';
+export declare const VERSION = "2.0.0";
+export declare const DESCRIPTION = "MambaCode.js: WebGPU-accelerated Mamba-1/2/3 and Hybrid SSM for browser code models";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,EAAE,WAAW,EAAE,MAAQ,yBAAyB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAQ,yBAAyB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAQ,yBAAyB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG5D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAIrD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EACH,MAAM,EACN,QAAQ,EACR,UAAU,EACV,MAAM,EACN,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIlD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI9E,YAAY,EACR,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,SAAS,GACZ,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC1G,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,UAAU,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC/H,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9E,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAO,yBAAyB,CAAC;AAC/E,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAIvF,OAAO,EACH,UAAU,EACV,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,UAAU,EACV,YAAY,EACZ,IAAI,GACP,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EACH,YAAY,EACZ,cAAc,EACd,WAAW,EACX,WAAW,EACX,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,GACjB,MAAM,yBAAyB,CAAC;AAKjC,OAAO,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAC3D,6BAA6B,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAC3C,qBAAqB,CAAC;AAC/B,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAC3C,gCAAgC,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MACpC,4BAA4B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAC1F,0BAA0B,CAAC;AAGpC,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MACrC,kBAAkB,CAAC;AAG5B,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MACrD,0BAA0B,CAAC;AAGpC,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAC/D,wBAAwB,CAAC;AAIlC,eAAO,MAAM,OAAO,UAAc,CAAC;AACnC,eAAO,MAAM,WAAW,wFAAwF,CAAC"}

package/dist/index.js

@@ -0,0 +1,40 @@
+/**
+ * MambaCode.js – Entry Point (v2.0.0)
+ */
+// ── Model classes ─────────────────────────────────────────────────────────────
+export { HybridMambaModel, MambaModel } from './model/mamba_model.js';
+// New block classes
+export { Mamba1Block } from './model/mamba1_block.js';
+export { Mamba2Block } from './model/mamba2_block.js';
+export { Mamba3Block } from './model/mamba3_block.js';
+export { AttentionBlock } from './model/attention_block.js';
+// Deprecated alias — kept until 3.0.0
+export { MambaBlock } from './model/mamba1_block.js';
+// ── Training ──────────────────────────────────────────────────────────────────
+export { MambaTrainer } from './training/trainer.js';
+export { Tensor, backward, enableGrad, noGrad, clearTape, recordOperation, crossEntropyLoss, crossEntropyGrad, } from './training/autograd.js';
+// ── Tokenizer ─────────────────────────────────────────────────────────────────
+export { BPETokenizer } from './tokenizer/bpe.js';
+// ── Seeded RNG (reproducible weight init) ─────────────────────────────────────
+export { SeededRng, setInitSeed, randn, gaussianArray } from './utils/rng.js';
+// ── GPU utilities ─────────────────────────────────────────────────────────────
+export { initWebGPU, createStorageBuffer, createEmptyStorageBuffer, createUniformBuffer, createComputePipeline, createBindGroup, dispatchKernel, readBuffer, uploadBuffer, cdiv, } from './utils/gpu_utils.js';
+// ── Quantization ──────────────────────────────────────────────────────────────
+export { quantizeFp16, dequantizeFp16, floatToFp16, fp16ToFloat, quantizeInt8, dequantizeInt8, quantizeInt8PerChannel, dequantizeInt8PerChannel, estimateMemory, } from './utils/quantization.js';
+// ── WGSL kernel sources ───────────────────────────────────────────────────────
+// Mamba-1 kernels (unchanged)
+export { SELECTIVE_SCAN_FORWARD_WGSL, SELECTIVE_SCAN_BACKWARD_WGSL } from './kernels/selective_scan.js';
+export { CONV1D_FORWARD_WGSL, CONV1D_BACKWARD_WGSL } from './kernels/conv1d.js';
+export { LINEAR_FORWARD_WGSL, LINEAR_BACKWARD_WGSL } from './kernels/linear_projection.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 } from './kernels/activations.js';
+// Mamba-2 SSD kernels
+export { SSD_FORWARD_WGSL, SSD_BACKWARD_WGSL } from './kernels/ssd.js';
+// Mamba-3 complex SSD kernels
+export { COMPLEX_SSD_FORWARD_WGSL, COMPLEX_SSD_BACKWARD_WGSL } from './kernels/complex_ssd.js';
+// Attention kernels
+export { ATTENTION_FORWARD_WGSL, ATTENTION_BACKWARD_WGSL, SOFTMAX_WGSL } from './kernels/attention.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';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,iFAAiF;AAEjF,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEtE,oBAAoB;AACpB,OAAO,EAAE,WAAW,EAAE,MAAQ,yBAAyB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAQ,yBAAyB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAQ,yBAAyB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,sCAAsC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,iFAAiF;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EACH,MAAM,EACN,QAAQ,EACR,UAAU,EACV,MAAM,EACN,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,wBAAwB,CAAC;AAEhC,iFAAiF;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,iFAAiF;AAEjF,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAkB9E,iFAAiF;AAEjF,OAAO,EACH,UAAU,EACV,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,UAAU,EACV,YAAY,EACZ,IAAI,GACP,MAAM,sBAAsB,CAAC;AAE9B,iFAAiF;AAEjF,OAAO,EACH,YAAY,EACZ,cAAc,EACd,WAAW,EACX,WAAW,EACX,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,GACjB,MAAM,yBAAyB,CAAC;AAEjC,iFAAiF;AAEjF,8BAA8B;AAC9B,OAAO,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAC3D,6BAA6B,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAC3C,qBAAqB,CAAC;AAC/B,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAC3C,gCAAgC,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MACpC,4BAA4B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAC1F,0BAA0B,CAAC;AAEpC,sBAAsB;AACtB,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MACrC,kBAAkB,CAAC;AAE5B,8BAA8B;AAC9B,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MACrD,0BAA0B,CAAC;AAEpC,oBAAoB;AACpB,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAC/D,wBAAwB,CAAC;AAElC,iFAAiF;AAEjF,MAAM,CAAC,MAAM,OAAO,GAAO,OAAO,CAAC;AACnC,MAAM,CAAC,MAAM,WAAW,GAAG,qFAAqF,CAAC"}

package/dist/kernels/activations.d.ts

@@ -0,0 +1,5 @@
+export declare const ACTIVATIONS_WGSL: string;
+export declare const SOFTMAX_FORWARD_WGSL: string;
+export declare const SOFTMAX_BACKWARD_WGSL: string;
+export declare const ACTIVATIONS_BACKWARD_WGSL: string;
+//# sourceMappingURL=activations.d.ts.map

package/dist/kernels/activations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activations.d.ts","sourceRoot":"","sources":["../../src/kernels/activations.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,gBAAgB,EAAE,MAyD9B,CAAC;AAOF,eAAO,MAAM,oBAAoB,EAAE,MA2ClC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,MAkCnC,CAAC;AAGF,eAAO,MAAM,yBAAyB,EAAE,MAwBvC,CAAC"}

package/dist/kernels/activations.js

@@ -0,0 +1,171 @@
+// Activation function WGSL kernels: SiLU (Swish) and its backward pass.
+// Used in the gating mechanism of the Mamba Mixer Block.
+export const ACTIVATIONS_WGSL = /* wgsl */ `
+
+struct ActParams {
+    num_elements : u32,
+};
+
+@group(0) @binding(0) var<uniform>             p    : ActParams;
+@group(0) @binding(1) var<storage, read>       x    : array<f32>;
+@group(0) @binding(2) var<storage, read_write> y    : array<f32>;
+
+// SiLU(x) = x * sigmoid(x)
+@compute @workgroup_size(256, 1, 1)
+fn silu_forward(
+    @builtin(global_invocation_id) gid : vec3<u32>,
+) {
+    let i = gid.x;
+    if (i >= p.num_elements) { return; }
+    let v = x[i];
+    y[i] = v / (1.0 + exp(-v));
+}
+
+// RMSNorm forward:  y = x / rms(x) * weight
+// Requires separate uniform for rms norm params.
+struct RMSNormParams {
+    num_rows  : u32,   // number of vectors (batch * seq_len)
+    dim       : u32,   // feature dimension
+    eps       : f32,
+};
+
+@group(0) @binding(0) var<uniform>             rms_p    : RMSNormParams;
+@group(0) @binding(1) var<storage, read>       rms_x    : array<f32>;
+@group(0) @binding(2) var<storage, read>       rms_w    : array<f32>;   // scale (dim,)
+@group(0) @binding(3) var<storage, read_write> rms_y    : array<f32>;
+@group(0) @binding(4) var<storage, read_write> rms_inv  : array<f32>;   // cache 1/rms per row
+
+@compute @workgroup_size(64, 1, 1)
+fn rmsnorm_forward(
+    @builtin(global_invocation_id) gid : vec3<u32>,
+) {
+    let row = gid.x;
+    if (row >= rms_p.num_rows) { return; }
+
+    let D = rms_p.dim;
+    let base = row * D;
+
+    var sq_sum: f32 = 0.0;
+    for (var i: u32 = 0u; i < D; i = i + 1u) {
+        let v = rms_x[base + i];
+        sq_sum = sq_sum + v * v;
+    }
+    let inv_rms = 1.0 / sqrt(sq_sum / f32(D) + rms_p.eps);
+    rms_inv[row] = inv_rms;
+
+    for (var i: u32 = 0u; i < D; i = i + 1u) {
+        rms_y[base + i] = rms_x[base + i] * inv_rms * rms_w[i];
+    }
+}
+`;
+// ---- Softmax (row-wise with optional causal mask) ----
+// Standalone softmax used by AttentionBlock for the score matrix.
+// Dispatch: (L, H, B) — one workgroup per (row, head, batch).
+// This version is a simple sequential-within-workgroup implementation;
+// for large L prefer the cooperative version in attention.ts.
+export const SOFTMAX_FORWARD_WGSL = /* wgsl */ `
+struct SoftmaxParams {
+    rows    : u32,   // L
+    cols    : u32,   // L
+    causal  : u32,   // 1 = apply causal mask, 0 = full softmax
+};
+
+@group(0) @binding(0) var<uniform>             sp   : SoftmaxParams;
+@group(0) @binding(1) var<storage, read_write> data : array<f32>;
+
+@compute @workgroup_size(1, 1, 1)
+fn softmax_forward_simple(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let row  = gid.x;
+    let head = gid.y;
+    let bat  = gid.z;
+
+    if (row >= sp.rows) { return; }
+
+    let L    = sp.cols;
+    let base = bat * sp.rows * L + head * L * L + row * L;
+    let lim  = select(L, row + 1u, sp.causal == 1u);
+
+    var max_val = -1e38;
+    for (var c = 0u; c < lim; c = c + 1u) {
+        if (data[base + c] > max_val) { max_val = data[base + c]; }
+    }
+
+    var sum_exp = 0.0;
+    for (var c = 0u; c < lim; c = c + 1u) {
+        let e = exp(data[base + c] - max_val);
+        data[base + c] = e;
+        sum_exp = sum_exp + e;
+    }
+
+    let inv = 1.0 / (sum_exp + 1e-12);
+    for (var c = 0u; c < lim; c = c + 1u) {
+        data[base + c] = data[base + c] * inv;
+    }
+    // Zero out masked positions
+    for (var c = lim; c < L; c = c + 1u) {
+        data[base + c] = 0.0;
+    }
+}
+`;
+export const SOFTMAX_BACKWARD_WGSL = /* wgsl */ `
+struct SoftmaxParams {
+    rows    : u32,
+    cols    : u32,
+    causal  : u32,
+};
+
+@group(0) @binding(0) var<uniform>            sp  : SoftmaxParams;
+@group(0) @binding(1) var<storage, read>      p   : array<f32>;   // post-softmax probs
+@group(0) @binding(2) var<storage, read>      dp  : array<f32>;   // upstream gradient
+@group(0) @binding(3) var<storage, read_write> dx : array<f32>;   // output gradient
+
+@compute @workgroup_size(1, 1, 1)
+fn softmax_backward(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let row  = gid.x;
+    let head = gid.y;
+    let bat  = gid.z;
+
+    if (row >= sp.rows) { return; }
+
+    let L    = sp.cols;
+    let base = bat * sp.rows * L + head * L * L + row * L;
+    let lim  = select(L, row + 1u, sp.causal == 1u);
+
+    // dot = sum_i p[i] * dp[i]
+    var dot = 0.0;
+    for (var i = 0u; i < lim; i = i + 1u) {
+        dot = dot + p[base + i] * dp[base + i];
+    }
+
+    for (var i = 0u; i < lim; i = i + 1u) {
+        dx[base + i] = p[base + i] * (dp[base + i] - dot);
+    }
+}
+`;
+// ---- Backward for SiLU ----
+export const ACTIVATIONS_BACKWARD_WGSL = /* wgsl */ `
+
+struct ActParams {
+    num_elements : u32,
+};
+
+@group(0) @binding(0) var<uniform>            p   : ActParams;
+@group(0) @binding(1) var<storage, read>      x   : array<f32>;
+@group(0) @binding(2) var<storage, read>      dy  : array<f32>;
+@group(0) @binding(3) var<storage, read_write> dx : array<f32>;
+
+// d/dx [x * sigmoid(x)] = sigmoid(x) + x * sigmoid(x) * (1 - sigmoid(x))
+//                        = silu(x)/x  + sigmoid(x) * (1 - sigmoid(x)) * x
+//                        simplified:  sigmoid(x) * (1 + x*(1 - sigmoid(x)))
+@compute @workgroup_size(256, 1, 1)
+fn silu_backward(
+    @builtin(global_invocation_id) gid : vec3<u32>,
+) {
+    let i = gid.x;
+    if (i >= p.num_elements) { return; }
+    let v   = x[i];
+    let sig = 1.0 / (1.0 + exp(-v));
+    dx[i] = dy[i] * sig * (1.0 + v * (1.0 - sig));
+}
+`;
+//# sourceMappingURL=activations.js.map