mlx-bun 0.0.12 → 0.2.0

package/README.md

@@ -83,7 +83,7 @@ runtime, so the only thing the first run fetches is the model.
 
 ### bunx (no install)
 
-Already have [Bun](https://bun.sh) ≥ 1.3.14? Run it straight from npm,
+Already have [Bun](https://bun.sh) ≥ 1.4.0? Run it straight from npm,
 nothing to install:
 
 ```sh
@@ -97,7 +97,7 @@ mlx-bun` under Node exits with a
 
 ### From source
 
-Needs [Bun](https://bun.sh) ≥ 1.3.14 — no Python, no native library to
+Needs [Bun](https://bun.sh) ≥ 1.4.0 — no Python, no native library to
 install by hand:
 
 ```sh
@@ -212,12 +212,12 @@ runtime that serves them:
   [quickstart](./docs/reference/orpo-quickstart.md)).
 - **The curve designer** — HLG tone-curve sampling with an interactive
   designer in the server UI at `/curves`
-  ([design](./docs/design/hlg-sampling.md)).
+  ([design](./docs/archive/hlg-sampling.md)).
 - **Speculative decoding research (DSpark)** — a KV-injection drafter
   ([design](./docs/design/dspark-speculative-decoding.md)).
 - The full research trail — including dead ends — is tracked in
   [docs/design/](./docs/design/) and
-  [docs/investigations/](./docs/investigations/).
+  [docs/archive/investigations/](./docs/archive/investigations/).
 
 On the site: [The lab](https://mlx-bun.dev/about/lab/).
 
@@ -225,7 +225,7 @@ On the site: [The lab](https://mlx-bun.dev/about/lab/).
 
 Scope is deliberate: a few model families held to explicit oracle contracts,
 rather than dozens held to none. Currently MiniCPM5, the Gemma-4 OptiQ quants,
-Qwen3.5-4B, and the direct-container GLM-5.2 path:
+the Qwen 3.x family, and the direct-container GLM-5.2 path:
 
 | Model | Download | Fits on | Vision | Notes |
 |---|---|---|---|---|
@@ -234,14 +234,13 @@ Qwen3.5-4B, and the direct-container GLM-5.2 path:
 | [`mlx-community/gemma-4-e4b-it-OptiQ-4bit`](https://huggingface.co/mlx-community/gemma-4-e4b-it-OptiQ-4bit) | 7.0 GB | 16 GB | ✓ | **Recommended starter** (16 GB+); ~56 tok/s |
 | [`mlx-community/gemma-4-12B-it-OptiQ-4bit`](https://huggingface.co/mlx-community/gemma-4-12B-it-OptiQ-4bit) | 8.4 GB | 16 GB | ✓ | Vision + tool calling, both verified end-to-end |
 | [`mlx-community/gemma-4-26B-A4B-it-OptiQ-4bit`](https://huggingface.co/mlx-community/gemma-4-26B-A4B-it-OptiQ-4bit) | 18 GB | 24 GB | — | MoE (top-8 of 128 experts); ~54 tok/s |
+| [`mlx-community/Qwen3.8-27B-OptiQ-4bit`](https://huggingface.co/mlx-community/Qwen3.8-27B-OptiQ-4bit) | 20.4 GB | 32 GB (24 GB with `--memory-budget`) | image + video | Current-gen Qwen; bf16-KV bit-exact parity (vs mlx-lm); thinking with `reasoning_effort` (xhigh/medium/low) + `preserve_thinking` + tool calling; native MTP head mounts as a `--draft-model` (lossless-by-verify, recurrent-cache rollback built in); **image AND video input serve** (`image_url` / `video_url` content parts — dedicated vision tower + mRoPE; video decodes via macOS-native AVFoundation, 2 fps ≤768 frames) |
 | [`mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp`](https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp) | ~384 GB / 357 GiB | 32 GB + fast disk | — | Direct streamed Colibri container; true top-8, native MTP, bounded 25 GiB process plan; warm single-stream performance is disk-bound and below the aspirational 2 tok/s target |
 
 Not sure what fits your machine? `bun src/cli.ts fit <model> --ctx 8192`
-gives a deterministic answer (see below). The larger
-`Qwen3.6-27B-OptiQ-4bit` is still in bring-up — parity and serving polish
-remain (see [PLAN.md](./PLAN.md)). Downloading, cache layout, and reclaiming
-disk: [docs/reference/models.md](./docs/reference/models.md); on the site:
-[Choosing a model](https://mlx-bun.dev/getting-started/models/).
+gives a deterministic answer (see below). Downloading, cache layout, and
+reclaiming disk: [docs/reference/models.md](./docs/reference/models.md);
+on the site: [Choosing a model](https://mlx-bun.dev/getting-started/models/).
 
 ### GLM-5.2: 32 GB quickstart
 
@@ -342,8 +341,10 @@ agent CLIs like pi/OpenClaw via their provider config.
   `temperature`, `top_p`, `top_k`, `max_tokens`, `seed`,
   `repetition_penalty`, `stop` (string or array, matched on decoded
   text with streaming hold-back), `reasoning_effort` (thinking on/off for
-  Qwen3.5 / MiniCPM5 — `none` disables, any level enables), and an `hlg`
-  tone-curve sampling override;
+  Qwen3.5/3.8 / MiniCPM5 — `none` disables, any level enables; on Qwen3.8
+  the level also sets reasoning depth: `low`/`medium`/`xhigh`), a Qwen3.8
+  `chat_template_kwargs.preserve_thinking` toggle (keep think blocks from
+  history; default on), and an `hlg` tone-curve sampling override;
   omitted sampling fields default to the model's own
   `generation_config.json` recipe; usage includes `cached_tokens`.
   Full schemas in
@@ -380,7 +381,9 @@ agent CLIs like pi/OpenClaw via their provider config.
 - **Prompt caching** — a byte-capped LRU KV cache reuses the longest
   common token prefix across requests (multi-turn conversations
   re-prefill only the new turn) — automatic, no client changes.
-  Entries are adapter-specific when LoRA adapters are in play.
+  Entries are adapter-specific when LoRA adapters are in play. With
+  `--ssd-cache`, pending snapshots are flushed durably on `SIGINT`/`SIGTERM`;
+  `POST /admin/cache/flush` exposes the same boundary for automation.
 - **LoRA hot-swap** — mount adapters at runtime (`POST /v1/adapters`)
   and discover on-disk ones (`GET /v1/adapters/available`), select per
   request with the `adapter` body field (`"id"`, stacked `"a+b"`, or
@@ -415,8 +418,10 @@ agent CLIs like pi/OpenClaw via their provider config.
   targets, not small fast models. Serial lane only — with `--batch N` a
   mounted draft routes every request serial, like mlx_lm.server.
 - **Memory admission control** — `--memory-budget <GB>` refuses to load
-  a model that can't serve within the budget and rejects requests whose
-  `prompt + max_tokens` exceed the budget's max safe context with a 400
+  a model that can't serve within the budget. For requests, `max_tokens`
+  is a ceiling, not a promise: a broad client value is capped to the room
+  remaining under the safe context, and only a prompt that leaves no
+  generation slot at all is rejected with a 400
   (`type: "memory_admission"`) *before* generating. The GPU
   out-of-memory crash it prevents is uncatchable by design — rejection
   up front is the only defense. Ceiling visible at `GET /stats`.
@@ -474,6 +479,13 @@ for await (const t of gen) process.stdout.write(tok.decode([t.token], true));
 console.log(gen.stats); // prompt/decode tok/s, cached tokens, ...
 ```
 
+`openModel()` first resolves a declared model profile: exact immutable artifact
+profiles outrank dedicated family paths, which outrank the generic fallback.
+Profiles select the loader/model graph/generation loop and carry their fidelity
+contract; they never rewrite explicit or default-resolved KV, MTP, adapter,
+grammar, or sampling choices. `loadContext()` exposes the resolved declaration
+as `ctx.profile`, and direct library users can call `resolveModelProfile()`.
+
 KV caches can be persisted to disk (page-aligned files that reload as
 zero-copy GPU-safe mmaps — see `src/kv-store.ts`) so a standard agent
 preamble prefills once, ever.
@@ -562,7 +574,7 @@ On the site: [Correctness](https://mlx-bun.dev/about/correctness/) and
 - **Slow decode on a model near your RAM ceiling** — close memory-heavy
   apps; a model that doesn't fit the wired-memory budget pages weights
   every token (check with `fit`).
-- **Bun version** — requires ≥ 1.3.14 (`bun upgrade`); pinned for
+- **Bun version** — requires ≥ 1.4.0 (`bun upgrade`); pinned for
   `Bun.Image` and verified FFI behavior.
 
 ## Status
@@ -571,7 +583,7 @@ Pre-alpha, moving fast. See [PLAN.md](./PLAN.md) for phases, exit
 criteria, measured numbers, and the findings log.
 
 **Complete** — load path; bit-exact model port (MiniCPM5, Qwen3.5-4B,
-e4b per-layer-input, 12B dense, 26B MoE); sampling + serving (tools, vision,
+Qwen3.8-27B, e4b per-layer-input, 12B dense, 26B MoE); sampling + serving (tools, vision,
 prompt cache); registry / fit / KV persistence; quantized +
 mixed-precision KV serving (rotating-cache KV-quant, Phase 9) with fused
 quantized prefill (Phase 10); LoRA hot-swap with per-request selection;
@@ -586,17 +598,21 @@ head-to-head benchmark harness; the decode-gap root-cause fix
 (commit 4625fe5); the embeddable single-binary build (signed +
 notarized — Homebrew, direct-download, and npm/bunx).
 
-**In progress** — `Qwen3.6-27B` bring-up (Phase 14f): same architecture
-as the verified 4B (untied + larger geometry); parity and serving polish
-remain. MTP speculation and Qwen3-VL vision deferred.
+**In progress** — `Qwen3.8-27B` full support (Phase 14 retarget): text
+parity is bit-exact, thinking controls (`reasoning_effort` depths,
+`preserve_thinking`) + tool calling are wired, and native MTP speculation
+(the Qwen-trained head as a `--draft-model`) mounts through the serve
+loop's recurrent-cache rollback contract; vision and video input are in
+bring-up.
 
 **Experimental** — opt-in, default-off, still being hardened: transparent
 expert offload for MoE models (`serve --expert-offload`, Phase 20:
 page-aligned mmap-backed experts, bit-exact — 26B-A4B 17.1→4.2 GB
-resident, decode unregressed); batched serving (`--batch N`, default 8
-since 2026-07-05 — a lone request runs the exact serial engine, so the cap
-engages only under real concurrency, e.g. coding sub-agents; `--batch 1`
-pins strict serial; Phase 18: continuous-batching bf16 decode at mlx-lm B=N parity,
+resident, decode unregressed); continuous serving (`--batch N`, default 8
+since 2026-07-05 — the scheduler's B=1 fast path uses serial-class caches and
+the parity-gated single-row graph, while the cap permits B=N under real
+concurrency such as coding sub-agents; `--batch 1` pins the preserved strict
+serial executor; Phase 18: bf16 decode at mlx-lm B=N parity,
 B=2 bit-parity verified for MiniCPM5/12B/e4b/26B; sampler extras,
 repetition penalty, and grammar-constrained requests batch; Qwen3.5's
 SSM caches batch, as do plain full-attention Tier-0 archs (e.g. Llama) —

package/bin/mlx-bun.mjs

@@ -4,7 +4,7 @@
 // (a guard inside cli.ts would never run under Node — its static imports
 // hoist and fail on the bun: scheme first).
 
-const MIN_BUN = "1.3.14"; // Bun.Image + verified FFI behavior (see README)
+const MIN_BUN = "1.4.0"; // fixed macOS arm64 FFI stack layout (see README)
 
 if (typeof Bun === "undefined") {
   console.error(

package/docs/{design → archive}/hlg-sampling.md

@@ -1,6 +1,6 @@
 # HLG sampling — a piecewise tone curve on the logits
 
-Status: **implemented, found neutral, superseded by Curve Designer** — `applyHlg` shipped in `src/sampler.ts`; investigation found HLG a wash vs plain temperature; the Curve Designer (`src/curve-sampler.ts`) is its v2 replacement. See [docs/investigations/hlg-sampling-investigation.md](../investigations/hlg-sampling-investigation.md) for findings. This doc remains as the design rationale.
+Status: **implemented, found neutral, superseded by Curve Designer** — `applyHlg` shipped in `src/sampler.ts`; investigation found HLG a wash vs plain temperature; the Curve Designer (`src/curve-sampler.ts`) is its v2 replacement. See [docs/archive/investigations/hlg-sampling-investigation.md](investigations/hlg-sampling-investigation.md) for findings. This doc remains as the design rationale.
 Owner: sampling layer (`src/sampler.ts`)
 Default: **off** (`--hlg-sampling off` = today's temperature sampler, untouched)
 
@@ -12,7 +12,7 @@ Default: **off** (`--hlg-sampling off` = today's temperature sampler, untouched)
 
 ## Outcome / Retrospective
 
-HLG was implemented through **Piece 2** (pure curve + neutrality tests + serial wiring, `applyHlg` live in `src/sampler.ts`). Evaluation found it **neutral vs plain temperature** — no measurable gain in diversity or quality at matched output entropy. As a result, HLG is **superseded by the Curve Designer** (`src/curve-sampler.ts`), which generalizes the same region-shaping idea with an editable control-point interface and cleaner UX. Full empirical findings are in [docs/investigations/hlg-sampling-investigation.md](../investigations/hlg-sampling-investigation.md).
+HLG was implemented through **Piece 2** (pure curve + neutrality tests + serial wiring, `applyHlg` live in `src/sampler.ts`). Evaluation found it **neutral vs plain temperature** — no measurable gain in diversity or quality at matched output entropy. As a result, HLG is **superseded by the Curve Designer** (`src/curve-sampler.ts`), which generalizes the same region-shaping idea with an editable control-point interface and cleaner UX. Full empirical findings are in [docs/archive/investigations/hlg-sampling-investigation.md](investigations/hlg-sampling-investigation.md).
 
 The sections below (Goal through Correctness) remain as design rationale. Pieces 3–6 of Phasing and the Open Questions were never executed; see the [Phasing](#phasing-the-piece-n-increments) and [Open Questions](#open-questions--risks) sections for historical context.
 
@@ -347,4 +347,4 @@ for it. That a transfer function is standard practice in another domain says
 nothing about whether it helps token sampling — that is decided only by
 measurement (the KL characterization, the capability guardrail, and the
 diversity lens in [Correctness](#correctness--evaluation)). The full empirical
-write-up is in [docs/investigations/hlg-sampling-investigation.md](../investigations/hlg-sampling-investigation.md).
+write-up is in [docs/archive/investigations/hlg-sampling-investigation.md](investigations/hlg-sampling-investigation.md).

package/docs/{investigations → archive/investigations}/hlg-sampling-investigation.md

@@ -3,7 +3,7 @@
 *2026-06-14. Question: can the structure of a piecewise nonlinear transfer
 function (HLG, the HDR transfer function) be transplanted onto a logit
 distribution as a sampling method, and if so, where do you place its pivot
-(middle grey)? Design contract: [docs/design/hlg-sampling.md](../design/hlg-sampling.md).
+(middle grey)? Design contract: [docs/archive/hlg-sampling.md](../design/hlg-sampling.md).
 Code: `src/sampler.ts` (`applyHlg`, `makeSampler`). Harness:
 `scripts/hlg-compare.ts`. Model under test: `gemma-4-e4b-it-OptiQ-4bit` on the
 M4 Pro.*

package/docs/archive/investigations/pareto-specialized-runtime-findings.md

@@ -0,0 +1,92 @@
+# Pareto-specialized runtime findings
+
+## Question
+
+Which parts of mlx-bun should converge on shared infrastructure, and which parts should remain deliberately specialized so cleanup does not turn the runtime into a lowest-common-denominator model host?
+
+This note compares three mature specialization clusters: the Colibri/GLM-5.2 runtime, the Qwen3.8 27B TurboQuant and MTP work, and ORPO training. The evidence says the same thing in all three places: share lifecycle and composition policy, but keep artifact layout and numerical work close to the model or method that owns them.
+
+## Shared control-plane infrastructure
+
+The shared layer decides what runs, owns resources, and records what happened. It does not rewrite the selected computation.
+
+- **Model construction.** `openModel()` recognizes the direct Colibri artifact before ordinary safetensors loading. `createModel()` prefers dedicated and fingerprint-generated model classes before the universal fallback, and explicitly says the generic path must not shadow a dedicated port. This is shared dispatch with specialized implementations, not one universal graph. [Factory dispatch](../../../src/model/factory.ts#L30-L150)
+- **Concurrency and request composition.** The target is one concurrency-driven engine. One active request uses the B=1 pipelined or compiled fast path; concurrent requests use the general step up to `--batch N`. B=1 is an internal specialization, not a permanent public lane. Features are stackable layers, and scheduling must not replace the selected KV scheme, adapter, draft method, grammar, or sampler. [Unified engine decision](../../design/unified-engine-frontier-plan.md#L333-L403) [Composition matrix](../../design/unified-engine-frontier-plan.md#L405-L424)
+- **Cache lifecycle and capability.** `Cache` owns update, masks, state, rollback, accounting, and disposal. `BatchableCache` adds row merge, extraction, filtering, and byte projection. The scheduler can depend on those capabilities without knowing whether a row contains ordinary KV, recurrent state, TurboQuant tensors, or compressed GLM state. [Cache interface](../../../src/model/gemma4-base.ts#L264-L303) [Batchable cache interface](../../../src/model/gemma4-base.ts#L347-L357)
+- **Resolved KV policy.** `KvScheme` preserves bf16, uniform affine, per-layer affine, and TurboQuant as distinct immutable schemes. It centralizes names, accounting, and current batch capability checks without pretending the schemes have identical storage or kernels. [KV scheme](../../../src/kv-scheme.ts#L84-L169)
+- **Draft lifecycle.** `DraftProvider` owns server-lifetime machinery and opens a request-scoped `DraftSource`. The source interface carries prompt mode, target taps, draft, commit, rollback-related cache state, and disposal. Assistant, DSpark, Qwen MTP, and native GLM MTP can share speculative orchestration while retaining different state transitions. [Draft source](../../../src/spec/source.ts#L31-L101) [Draft provider](../../../src/spec/source.ts#L103-L118)
+- **Expert residency policy.** The budget equation, stable expert union, lease state, backend contract, telemetry, and pressure correction are reusable. GLM supplies artifact geometry and byte segments to that policy. [Residency planning and union](../../../src/expert-residency.ts#L17-L155) [Residency backend](../../../src/expert-residency.ts#L157-L170)
+- **Offline transform orchestration.** `WeightTransform` separates name/config planning from lazy tensor application. Llama, the Qwen3.5 trunk, and Qwen MTP are real adapters over the same conversion seam. [Weight transform interface](../../../src/quantize/weight-transform.ts#L40-L51) [Qwen transform adapters](../../../src/quantize/weight-transform.ts#L244-L268)
+- **Training orchestration.** `TrainConfig` names independent techniques such as segmented backward, fused or flash CCE, prefix sharing, regularization, and ORPO semantics. `orpoLoop()` composes the selected techniques and chooses the model-specific backward implementation. [Training configuration](../../../src/train/trainer.ts#L42-L150) [ORPO composition](../../../src/train/trainer.ts#L821-L948)
+
+## Deliberately specialized data-plane code
+
+### Colibri and GLM-5.2
+
+GLM-5.2 is not a descriptor-table variation of a dense transformer. Its graph has MLA, DSA, shared plus routed MoE, native MTP, and compressed cache state. Its public artifact also has a dedicated container and streamed expert layout. The design therefore calls for a dedicated `Glm52Model`, direct artifact support, and a one-read routed-expert kernel rather than repacking into generic projection-major tensors. [Dedicated graph and artifact contract](../../design/colibri-glm52-port.md#L323-L357)
+
+The memory contract is also model and artifact specific. A header-only preflight reads the container, derives expert slot layouts, counts DSA and MTP state, and refuses startup when the exact resident weights, expert slabs, compressed KV, verification transients, allocator reserve, Bun reserve, and safety margin exceed the process limit. [GLM geometry and preflight](../../../src/model/glm52-memory.ts#L340-L500) The runtime then maps Colibri segments into generic residency leases, but retains GLM-specific slot layouts, MTP slabs, signed-int8 requirements, and routed-SwiGLU executors. [GLM residency binding](../../../src/model/glm52-residency.ts#L138-L230) [GLM executor construction](../../../src/model/glm52-residency.ts#L300-L459)
+
+That split is intentional. Bun owns residency policy and observability; the native helper owns aligned slabs, `pread`, wiring, and completion fences; the GLM model owns tensor semantics and kernels. [Ownership map](../../design/colibri-glm52-port.md#L580-L600)
+
+### Qwen3.8 27B, TurboQuant, and MTP
+
+Qwen3.5/3.8 keeps a dedicated graph because gated DeltaNet recurrence, full attention, MRoPE, output gates, and recurrent speculative rollback are numerical behavior, not configuration decoration. [Qwen graph](../../../src/model/qwen3_5.ts#L128-L322) [Qwen model interface](../../../src/model/qwen3_5.ts#L512-L673)
+
+Qwen MTP preserves its own artifact and state machine behind `DraftProvider` and `DraftSource`. The provider rejects a non-Qwen target or a hidden-size mismatch. The request source uses tapped pre-final-norm target state, maintains its own KV, samples through the target sampler, and rebuilds accepted rows from verified target hiddens. Those rules must not move into generic speculative orchestration. [Qwen MTP provider](../../../src/spec/qwen-mtp-source.ts#L193-L235) [Qwen MTP state machine](../../../src/spec/qwen-mtp-source.ts#L237-L430)
+
+TurboQuant KV demonstrates the right form of specialization. `TurboQuantKVCache` implements the shared `Cache` lifecycle, while keeping packed indices, scales, zero points, FWHT-domain values, supported head dimensions, and conversion rules inside the class. [TurboQuant cache](../../../src/model/gemma4-base.ts#L1539-L1800) The weight pipeline follows the same rule. `WeightTransform` is shared, but the Qwen corridor map preserves the output gate, recurrent internals, vision-to-residual seam, untied 27B head, and companion MTP basis. [Qwen transform seam](../../design/turboquant-weights.md#L80-L87) [Qwen corridor map](../../design/turboquant-weights.md#L125-L174)
+
+### ORPO training
+
+ORPO benefits from composition, not one generic backward. The trainer combines prefix sharing, segmented recomputation, fused or flash CCE, LoRA regularization, and objective semantics. The data plane remains specialized where the model topology demands it. Gemma4 segmented ORPO threads per-layer inputs and cross-segment donor KV cotangents; MiniCPM5 uses a simpler segment graph. [Composed ORPO paths](../../design/orpo-training.md#L178-L218) [Gemma4 segmented backward](../../../src/train/segmented.ts#L1137-L1471)
+
+Flash CCE is a shared quantized-head interface with specialized Metal kernels and explicit shape guards. Its implementation selects Steel, simdgroup, or scalar kernels from actual hidden, vocabulary, group, and tile geometry, and exposes exact-gradient escape hatches. Flattening this into a generic matrix-loss helper would lose the memory and watchdog constraints that justify it. [Flash CCE head](../../../src/train/flash-cce.ts#L42-L64) [Forward dispatch](../../../src/train/flash-cce.ts#L1033-L1132) [Backward dispatch](../../../src/train/flash-cce.ts#L1134-L1234)
+
+Dynamic lambda is not implemented. Its design belongs in the ORPO control plane: validation metrics update a live lambda source in `orpoLoop()`, while every monolithic and segmented loss reads the same value. It should not create another family of backward classes. [Dynamic-lambda status and signals](../../design/orpo-dynamic-lambda.md#L1-L27) [Proposed wiring](../../design/orpo-dynamic-lambda.md#L163-L180)
+
+## Interfaces that already preserve specialization
+
+| Interface | Shared invariant | Specialization retained behind it |
+|---|---|---|
+| `RuntimeModel` plus factory dispatch | Construction and serving can hold one model type | Dedicated GLM, Qwen, Gemma, diffusion, MoE, and generated graphs |
+| `Cache` / `BatchableCache` | Lifecycle, rollback, row operations, byte projection | Plain, rotating, quantized, TurboQuant, SSM, MLA, and DSA storage |
+| `KvScheme` | One resolved KV choice and stable identity | Per-scheme accounting, conversion, persistence, and kernels |
+| `DraftProvider` / `DraftSource` | Request lifecycle, target taps, draft and commit | Assistant, DSpark, Qwen MTP, and GLM MTP state machines |
+| `ExpertResidencyBackend` | Lease and I/O lifecycle | Colibri container offsets, slot packing, expert kernels, and prediction policy inputs |
+| `WeightTransform` | Plan first, apply lazily, record identity | Family-specific exact fold corridors and companion artifacts |
+| ORPO trainer configuration | One run composes selected techniques | Model-specific masks, donor topology, VJPs, and Metal kernels |
+
+## Declared profile seam (S2, 2026-08-21)
+
+Model construction now resolves one `ResolvedModelProfile` before opening
+weights. An exact artifact declaration binds an immutable external fingerprint,
+config fingerprint, fidelity contract, required engine capabilities, and a
+loader/graph/loop composition. Exact Qwen3.8 OptiQ and GLM-5.2 Colibri revisions
+are pinned; other supported artifacts retain dedicated family resolution and
+then the universal dense fallback.
+
+The factory consumes the resolved composition, and the serving context retains
+it for library callers. A matched exact declaration with a config or capability
+mismatch refuses rather than taking another route. The profile seam does not
+own request methods: MTP, KV schemes, adapters, grammar, and sampling remain
+independently resolved inputs to completion execution. This keeps the control
+plane declarative without turning a model profile into a feature preset.
+
+These interfaces preserve specialization because they describe lifecycle or capability, not tensor algebra. They also have multiple real implementations. That is the useful test for whether an abstraction belongs.
+
+## Rules for steady-state cleanup
+
+1. **Unify control, not math.** Centralize admission, concurrency, cancellation, ownership, accounting, persistence, telemetry, and technique composition. Keep tensor layout, recurrence, cache encoding, model topology, and kernel selection with their owning model, artifact, or method.
+2. **Keep one concurrency-driven engine.** B=1 and B>1 are internal step specializations in one engine. `--batch N` is a concurrency cap. Observed placement may be reported, but serial versus batch must not become a permanent public mode or feature-selection interface. Current feature-specific serial routing is capability debt.
+3. **Never weaken a resolved composition to fit a path.** If batching lacks TurboQuant, MTP, adapters, grammar, or another selected method, close that capability gap or reject the unsupported composition. Do not silently substitute bf16 KV, disable drafting, or change sampling.
+4. **Prefer capability interfaces over family checks.** Scheduling should ask caches whether they can merge or project bytes and draft sources what target state they require. Factory dispatch is the proper place for model identity checks.
+5. **Let dedicated ports outrank generic fallbacks.** The universal model path is valuable for ordinary architectures. It must not absorb GLM MLA/DSA, Qwen recurrence, artifact-specific MTP, or another optimized graph merely to reduce class count.
+6. **Treat artifacts as executable contracts.** Validate manifests, tensor families, layouts, quantization metadata, companion seeds, and memory equations before allocation. Keep artifact-specific loaders and transforms when repacking would add copies, lose reproducibility, or change arithmetic.
+7. **Generalize only after the invariant is visible in two implementations.** Extract lifecycle and capability seams such as `DraftSource` or `WeightTransform`. Do not extract a common tensor algorithm from code that only looks similar but has different masks, state, accumulation order, or oracle.
+8. **Compose optimizations at the orchestrator, then test the cross-product.** ORPO proves that prefix sharing, flash CCE, segmented backward, and regularization can stack while model-specific backward code remains intact. Serving needs the same discipline for model graph, KV scheme, MTP, adapters, grammar, sampling, and concurrency.
+9. **Bind every specialized path to its own oracle and measured purpose.** A specialized module earns its place through parity, memory, quality, or throughput gates on the artifact and hardware it targets. If the benefit disappears, delete the specialization instead of preserving it as architecture folklore.
+
+## Strongest conclusion
+
+The steady state is not a generic engine with scattered exceptions. It is a shared control plane that carries authoritative compositions through one concurrency-driven engine, plus specialized data planes selected by model, artifact, and numerical method. That structure preserves the project's Pareto advantage: common serving and training behavior where sameness is real, and unapologetically specific code where the result depends on it.

package/docs/{planning → archive/planning}/chat-ui-vision.md

@@ -1,6 +1,6 @@
 # The mlx-bun chat surface: a vision
 
-*Draft vision, product/design lead pass — 2026-07-06. Bold stance: reimagine the chat surface from scratch. Companion to the market research and current-state audit that produced it; see `docs/planning/web-ui-pass-plan.md` for the tactical bug list and `docs/design/adapters-end-to-end.md` / `docs/design/memory-system.md` for the backend contracts this vision assumes.*
+*Draft vision, product/design lead pass — 2026-07-06. Bold stance: reimagine the chat surface from scratch. Companion to the market research and current-state audit that produced it; see `docs/archive/planning/web-ui-pass-plan.md` for the tactical bug list and `docs/design/adapters-end-to-end.md` / `docs/design/memory-system.md` for the backend contracts this vision assumes.*
 
 ## The feeling
 

package/docs/archive/planning/release-notes-v0.0.13.md

@@ -0,0 +1,77 @@
+# v0.0.13 release notes
+
+Everything since v0.0.12. One theme: **Qwen 3.8**. The current-generation
+Qwen (released August 2026) is brought up on the published OptiQ
+artifact at the repo's standard bar — bit-exact logit parity with
+mlx-lm — with its thinking controls served faithfully. Vision, video,
+and native Qwen MTP remain separately gated follow-ups.
+
+## Qwen3.8-27B (text, bit-exact)
+
+- `mlx-community/Qwen3.8-27B-OptiQ-4bit` serves on the existing
+  qwen3_5 hybrid graph (gated DeltaNet + gated attention) — the
+  architecture audit found byte-identical geometry to the verified
+  port, and parity confirmed it: **every logit at every prompt
+  position plus 32 greedy decode steps, bit-exact vs stock mlx-lm**
+  (the parity harness grew a full prefill-grid golden and
+  manifest-driven step counts in the process).
+- The config's new `output_gate_type: "swish"` field is inert in every
+  implementation (transformers ground truth included) — a load-time
+  guard now fails loudly if a future checkpoint carries a value we
+  haven't verified.
+- Fit reality: the artifact is 20.35 GB of shards. 32 GB machines
+  serve it comfortably; 24 GB machines need `--memory-budget` and
+  should prefer the uniform 4-bit conversion until the planned
+  ~4 bpw TurboQuant×weights artifact lands (PLAN 14z).
+
+## Thinking controls (Qwen 3.8's serving surface)
+
+- Thinking is on by default and streams as OpenAI `reasoning` deltas;
+  `chat_template_kwargs.enable_thinking: false` selects instruct mode.
+- `reasoning_effort` is now a real depth control on templates that read
+  it: OpenAI levels map onto Qwen's `low`/`medium`/`xhigh` (with
+  `xhigh` accepted as a first-class request value), and the variable is
+  only passed to templates that declare it — the Qwen 3.8 template
+  raises on unknown level names, so the server never forwards unmapped
+  strings.
+- `preserve_thinking` (new in Qwen 3.8, default on) is forwarded:
+  history keeps its think blocks, which also improves prompt-cache
+  reuse in agent loops.
+- Tool calling: Qwen 3.8's XML call format
+  (`<tool_call><function=name><parameter=…>`) parses through the
+  existing Qwen-style parser into OpenAI `tool_calls`, multiline
+  parameters included.
+
+## Qwen native MTP is deliberately not shipped yet
+
+- Qwen 3.8 ships a multi-step MTP head trained alongside the model;
+  mlx-community publishes it split out
+  (`mlx-community/Qwen3.8-27B-MTP-bf16`). Review found that the target's
+  48 recurrent DeltaNet caches cannot roll back rejected verify rows,
+  while the shared speculative loop requires exactly that operation.
+  The initial implementation therefore never reached a draft round.
+- MTP artifacts are detected and refused at startup with the exact reason,
+  before the 20 GB target is opened. Shipping a switch that silently disables
+  itself—or corrupts recurrent state when forced—would be worse than a clear
+  deferral. The follow-up needs recurrent-state snapshot/restore or a verify
+  schedule that never advances state beyond the accepted prefix.
+
+## GLM-5.2 client compatibility
+
+- Fixed-context GLM serving now treats request `max_tokens` as an upper bound:
+  when a client sends a family-wide value larger than the planned remaining
+  context, the server caps it instead of rejecting an otherwise valid first
+  prompt. The reported 2,788-prompt + 8,192-cap failure now admits a 1,308-token
+  completion ceiling within the 4,096-token plan. Prompts that consume the
+  whole context remain rejected before generation.
+
+## Also in this release
+
+- The parity harness's step-0 check now covers the full prefill logit
+  grid for all Qwen targets — masking/position bugs can no longer hide
+  behind a last-position comparison.
+- A GPU command-buffer failure mode on memory-saturated machines was
+  root-caused (Metal completion-thread exception, uncatchable by
+  design) and documented in PLAN 14g, along with the finding that some
+  mlx-c paths surface C++ errors as process panics instead of
+  catchable errors (hardening item).

package/docs/{planning → archive/planning}/release-notes-v0.0.9.md

@@ -117,6 +117,6 @@ overturning a load-bearing performance assumption.
   "failures" were M4-Pro fixtures; all code exonerated — mlx-lm reproduces
   mlx-bun token-for-token per machine); CI gate (typecheck + model-free tests).
 - **Research (the lab):** decode-roofline re-measurement overturned the "at
-  the floor" assumption (docs/investigations/decode-roofline-lookagain.md);
+  the floor" assumption (docs/archive/investigations/decode-roofline-lookagain.md);
   curve-sampler distinctness theorem + witness numbers + preregistered
   protocol (docs/planning/curve-sampler-research-plan.md).

package/docs/{planning → archive/planning}/website-readme-pass-plan.md

@@ -20,7 +20,7 @@ Two coherent options:
 
 - **(A) Recommended: cut v0.0.9, then deploy the site.** All docs become
   true simultaneously; nothing below needs version annotations. The
-  release-notes draft already exists (`docs/planning/release-notes-v0.0.9.md`).
+  release-notes draft already exists (`docs/archive/planning/release-notes-v0.0.9.md`).
 - **(B)** If v0.0.9 is not imminent: hold site deploys, and treat every
   item marked *v0.0.9* below as blocked. (Reverting docs to 8090 is churn
   for nothing — don't.)

package/docs/design/colibri-glm52-port.md

@@ -692,7 +692,7 @@ batch.
 
 G0 inventory note (2026-07-21): the exact pin, artifact/layout contract, and
 manual checklist are recorded in
-[`../investigations/colibri-oracle-pin.md`](../investigations/colibri-oracle-pin.md).
+[`../archive/investigations/colibri-oracle-pin.md`](../archive/investigations/colibri-oracle-pin.md).
 Because the pinned Makefile writes ignored build artifacts and even creates a
 configuration stamp while parsing, model-free oracle targets must run from a
 temporary `git archive` extraction, not in the read-only checkout. The pinned
@@ -1425,6 +1425,13 @@ advertised false, not emulated.
     `native-v0.2.0` GitHub release. Both assets are uploaded; anonymous HTTP
     resolution and an empty-cache default-URL download/checksum/extraction
     passed with all five required files. G8 is closed.
+  - [x] Published mlx-bun v0.0.12 itself: the signed/notarized GitHub release
+    and stable asset, npm package, and Homebrew tap are live and independently
+    verified. Both 80,420,638-byte binary assets carry SHA-256
+    `64c4d697faba65789c2af7c1344ee39024f8a03bd6839d2c8df4ec7dce872a74`;
+    npm reports shasum `0dcc5c200fa81dbea1f8be854e21a0efbbdebbfa`.
+    The final full gate passed 1,936 tests / 28,378 assertions with 71 skips
+    and zero failures.
 - Update README plus `docs/reference/{models,memory,cli,server-config,
   server-api,library-api,features-matrix}.md` in the same feature changes that
   add the corresponding flags, fields, routes, defaults, and limitations.

package/docs/design/compat-cli-surface-design.md

@@ -85,7 +85,7 @@ mlx-lm" half.
 
 ### pi — the built-in agentic coding CLI
 
-(Phase 16; full plan in **docs/investigations/pi-builtin-investigation.md**.) pi is an
+(Phase 16; full plan in **docs/archive/investigations/pi-builtin-investigation.md**.) pi is an
 MIT, Bun-native (`bun build --compile`) coding agent — the "CLI
 experience inside our package" that neither Python package has. Two
 commands, one for each audience:

package/docs/design/decode-speed-program.md

@@ -66,7 +66,7 @@ grammar composition, and `usage.speculation` telemetry ALL landed
   serve wiring: 27B/12B retarget (regen+train, Josh's shell), data scale
   (thousands of on-distribution generations vs 160), draft-loop
   tightening. At τ≈3 on the 27B agent workload: **~15 → ~35–45 tok/s**
-  (docs/investigations/dspark-handoff.md). Slots in as `DflashSource`,
+  (docs/archive/investigations/dspark-handoff.md). Slots in as `DflashSource`,
   no-oracle/KL-gated (a Lab item).
 
 ### 2. mlx bump — narrow 26B / spec-decode wins, NOT a general decode lever  [main-only, from-source]

package/docs/design/docs-reorg-plan.md

@@ -140,7 +140,7 @@ files, not benchmark output. Leave entirely alone.
 | 5 | Add `STATUS.md` (or a pinned top section in PLAN.md) holding only live handoff: current state + next action + blockers. Move PLAN.md's `NEXT UP` / `NEXT SESSION PICKUP` / `SESSION SWEEP` blocks into it. | Separates transient "do this next" from 2,475 lines of durable phase history; gives agents one entry point. |
 | 6 | Create `docs/planning/` and move `PRODUCT_ROADMAP.md`, `IDEAS.md`, `ResearchTopics.md`, `journal.md` under it. Leave only README + PLAN.md (+ STATUS.md) at root. Add a ~6-line "doc map" to README. | Root is currently a 6-file planning thicket; extends the taxonomy that already works in `docs/`. |
 | 7 | Pick one home for the optimization plan: fold `docs/design/optimization_plan.md` into PLAN.md Phase A–E, or have PLAN.md link out to it as canonical. | Two homes for the same plan = drift. |
-| 8 | Resolve the archive overlap: `archive/pi-builtin-investigation.html` duplicates [docs/investigations/pi-builtin-investigation.md](../investigations/pi-builtin-investigation.md). Decide whether `archive/` (tracked; 2 HTML files: `mlx-bun-lab-report.html` + `wwdc-mlx-bun.html`) should be tracked at all, or moved to an ignored location. Keep the `.md`, drop the duplicate. | Stops committing heavyweight generated HTML; one source per investigation. |
+| 8 | Resolve the archive overlap: `archive/pi-builtin-investigation.html` duplicates [docs/archive/investigations/pi-builtin-investigation.md](../archive/investigations/pi-builtin-investigation.md). Decide whether `archive/` (tracked; 2 HTML files: `mlx-bun-lab-report.html` + `wwdc-mlx-bun.html`) should be tracked at all, or moved to an ignored location. Keep the `.md`, drop the duplicate. | Stops committing heavyweight generated HTML; one source per investigation. |
 
 ## P2 — Polish (optional)
 

package/docs/design/dspark-serving-program.md

@@ -4,7 +4,7 @@ Status: **PLANNED** (2026-07-07). Trigger for Josh's pickup: TurboQuant merge
 but only Phase 5 actually depends on it; Phases 0–4 are start-anytime.
 Owner: decode / spec. Predecessors: PR #19 (DSpark paper code-complete +
 serve-integrated + DeepSpec oracle), the first-live-run findings in
-[dspark-handoff.md](../investigations/dspark-handoff.md) "FIRST LIVE RUN".
+[dspark-handoff.md](../archive/investigations/dspark-handoff.md) "FIRST LIVE RUN".
 
 ## The problem, in numbers (2026-07-07 first live run, loaded machine)
 

package/docs/design/dspark-speculative-decoding.md

@@ -247,6 +247,56 @@ regenerated by the target, 10 epochs, batch 512, lr 6e-4, position decay
 exp(−pos/4), ~38 TB cached hiddens — i.e. our "thousands of generations" data
 estimate was directionally right and their scale is far beyond a laptop run.
 
+## 27B program (2026-08-19): the TQ quant unlocks the real target
+
+The turboquant-weights campaign shipped rot-sens48 Qwen3.8-27B at 17 GB
+(docs/design/turboquant-weights.md) — and it changes both DSpark blockers
+this doc recorded:
+
+- **Target speed:** measured ~11.8 tok/s decode. This is the slow-target
+  regime where the doc's own analysis says τ≈3 nets 2–3× (≈25–35 tok/s) —
+  "the ideal target and the real motivation," now actually runnable.
+- **Training feasibility:** "27B memory-infeasible to train on 24 GB" (open
+  items below) assumed the bf16 trunk (54 GB). With the quantized trunk
+  FROZEN (inference-only: hidden taps + teacher logits) and only the small
+  drafter (~5 layers) holding grads/optimizer state in bf16, 27B-target
+  drafter training fits a 32 GB machine. The premise is dead; the line in
+  the gated item is superseded by this section.
+- **Rollback risk retired:** the stock Qwen-MTP spec path already serves
+  this model losslessly (68% per-token acceptance), so verify/rollback
+  across the 48 DeltaNet recurrent-state layers is proven engine behavior,
+  not new work.
+
+Two tracks, cheap-first:
+
+- **Track A — confidence-scheduled verification on the stock MTP head (no
+  drafter training).** Dynamic per-step block length instead of fixed
+  `--num-draft-tokens`: v0 confidence = the draft's own token probability
+  (no trained head), mapped through STS calibration
+  (`scripts/dspark-calibrate.ts` pattern) to expected acceptance; the
+  scheduler stops drafting when marginal expected-accept drops below the
+  verify amortization point. Calibration needs thousands of
+  (confidence, accepted?) pairs from served traffic — hours, not weeks.
+  Gate: paired A/B decode tok/s vs fixed-γ MTP on the same prompts;
+  lossless by construction (verify unchanged).
+- **Track B — true DSpark drafter for the 27B (multi-token single-pass).**
+  The faithful v2 (KV injection, Markov head) retargeted: `hiddenTap` added
+  to `qwen3_5.ts` forwardLayers (gemma4 has it; parity-safe no-op when
+  off), tap-layer selection for the 64-layer trunk (bias toward the 16
+  full-attention layers + post-finalNorm), data generated by TEACHER-FORCED
+  passes over corpus text with the frozen quantized trunk (every position
+  of a forward yields a sample — data scale is forward-passes over tokens,
+  not generate calls). Open idea: distill from / initialize against the
+  shipped MTP head to shortcut the acceptance floor. Gate: generalizing
+  per-position acceptance must beat the MTP head's 0.68 or Track B loses to
+  Track A + MTP and gets dropped.
+
+Sequencing: after the benchmark campaign closes (GPU is owned by the
+certification suite). Track A first — it's measurable in a day and its
+calibration data collection is also Track B's baseline instrumentation.
+Adapters/DSpark drafts trained on the TQ artifact are married to its
+rotation basis (fine for our bundle; note on the card if published).
+
 ## Open items / next
 
 - [x] Serve integration (Phase 1) · [x] Alg-1-shaped scheduler (matches the
@@ -258,11 +308,11 @@ estimate was directionally right and their scale is far beyond a laptop run.
   oracle scripts — the no-training path to the 12B speedup (in progress).
 - [ ] **Josh-gated GPU (the payoff):** real data scale (thousands of
   on-distribution generations) + **retarget to 12B** (`--model` +
-  `--tap-layers 5,17,29,41,46` (DeepSeek's trained taps); 27B memory-infeasible to train on 24 GB, kept
+  `--tap-layers 5,17,29,41,46` (DeepSeek's trained taps); ~~27B memory-infeasible to train on 24 GB~~ (superseded — the 17 GB TQ trunk makes it feasible; see "27B program" above), kept
   dim-generic) + train (`--seq-head` A/B optional) + **calibrate**
   (`scripts/dspark-calibrate.ts`) + live-τ measure. Recipe:
-  [docs/investigations/dspark-handoff.md](../investigations/dspark-handoff.md).
+  [docs/archive/investigations/dspark-handoff.md](../archive/investigations/dspark-handoff.md).
 - [ ] Verify the Eq 6 / §3.2.1 shapes against the actual paper when the PDF
   is available (both flagged in code).
 
-Full session handoff: `docs/investigations/dspark-handoff.md`.
+Full session handoff: `docs/archive/investigations/dspark-handoff.md`.

package/docs/design/grammar-spec-batching-integration.md

@@ -15,7 +15,7 @@ three workstreams so they compose deliberately instead of colliding:
   (docs/design/batching-perf-path.md).
 - **Speculative decoding** — research proven (assistant drafter bit-exact
   vs optiq, 12B γ=1 ≈ 1.09× win, docs/design/spec-decode-larger-targets.md;
-  DSpark architecture verified, docs/investigations/dspark-handoff.md) but
+  DSpark architecture verified, docs/archive/investigations/dspark-handoff.md) but
   **not served**: no `--draft-model`. Build plan already written:
   docs/design/mlx-lm-tool-parity-plan.md §7 (the `DraftSource` interface,
   two-model L1 source, serve loop, admission, prompt-cache composition).