mlx-bun 0.5.0 → 1.0.0

package/docs/archive/investigations/orpo-uf-testing-handoff.md

@@ -1,126 +0,0 @@
-# ORPO-on-UF — results + testing-phase handoff
-
-**Status:** training done (2026-06-20); **testing phase = next.** This doc is the
-"where we are + what to run" so anyone (or a fresh session) can execute the measurements.
-Companion: [trainer-validation-experiment.md](trainer-validation-experiment.md) (the
-validation that got us here).
-
-## The run that just finished
-
-From-**base** ORPO on UltraFeedback, MiniCPM5-1B.
-- **Base:** `mlx-community/MiniCPM5-1B-OptiQ-4bit` (the full post-trained model; optiq quant).
-- **Data:** `~/.cache/mlx-bun/eval-data/uf-cpm5` — 14,691 train / 148 val, `{prompt,chosen,rejected}`.
-- **Config:** ORPO, **1 epoch (14,691 iters)**, B=1, seq 2048, rank 16, **λ=0.1**, cosine LR
-  1e-5, **no-segment**. From base (no warm-start).
-- **Command:** `SEQ=2048 EVAL_EVERY=500 RANK=16 SCHED=cosine LAMBDA=0.1
-  ADAPTER_DIR=./adapters/cpm5-uf-frombase bun scripts/experiments/pref-control.ts orpo
-  ~/.cache/mlx-bun/eval-data/uf-cpm5 uf-frombase 14691 1e-5`
-
-## Key result — the two ORPO halves decoupled
-
-| half | metric | best | at step | final (14690) |
-|---|---|---|---|---|
-| **SFT** | loss (NLL+λOR) ↓ | **1.5057** | **14500** (the end) | 1.506 |
-| **DPO** | margin ↑ | **0.143** | **6000** | 0.127 |
-| — | accuracy | **81/148** | ~5500 | 80/148 |
-
-- **SFT improved across the *whole* run** (loss bottomed at the end) → **final adapter = best SFT.**
-- **DPO peaked at ~6000 and faded** → **step ~6000 = best DPO**, slightly worse SFT (loss 1.5077).
-- **No single checkpoint has both.** Honest summary: a **small, early-peaking preference
-  signal** (~+6 questions, chance 74 → peak 81/148) that **drifted down in the tail**, while
-  SFT kept inching to its ~1.506 floor. Whether even that small lift **converts** on an
-  independent test is the open question the testing phase answers.
-
-## Artifacts + baselines
-
-- **Final adapter:** `./adapters/cpm5-uf-frombase/` (mountable: `eval.ts --adapter`).
-- **Trajectory:** `runs/uf-frombase.{json,csv}`; **plot:** `runs/uf-frombase.png` via
-  `scripts/experiments/plot-runs.py` (panels: loss=val+train-EMA; questions-correct/148;
-  margin — each zoomed to its band).
-- **x1 baseline** (base CPM5, full capability suite): **28.69** (in the eval DB; needs the
-  MMLU-argmax + HumanEval-python fixes — see Gotchas). optiq published is 30.28.
-- **⚠ No intermediate checkpoints this run** — `pref-control.ts` lacked `saveCheckpoints`
-  (now **fixed**; future runs checkpoint every val eval + track best-margin). The ~6k peak
-  is recoverable by **deterministic replay** (same seed/order → same adapter).
-
-## Testing plan
-
-**PRIMARY — the headline (READY TO RUN):**
-- **A. final adapter vs base** on x2 (capability) + Exp 2 (judge win-rate). Answers "did a
-  full epoch of ORPO-on-UF move a 1B, on an *independent* test?"
-
-**SWEEP / SYNTHESIS:**
-- **B. recover the ~6k peak** — re-run from base to ~7k (checkpoints now on), grab the
-  step-6000 (and neighbors, pick best-val). The early-stop peak arm.
-- **C. four-way** — base / 6k-peak / final / final+6k on x2 + Exp 2 → traces the
-  early-stopping curve on an independent test.
-- **D. DPO-boost (the day's synthesis) — keep best SFT, re-pressure the DPO.** Warm-start
-  from the **final** adapter (best SFT, NLL at floor), re-apply the **DPO-helpful examples
-  with HIGH λ** (or DPO-only). = dynamic-λ (ramp preference at SFT-saturation) + data-curation
-  in one move. Tests the fork: DPO stalled because of a **capacity ceiling** (won't help) or
-  **dilution / λ-too-gentle** (margin recovers past 0.143 while loss holds ~1.506 → better on
-  *both* axes than any single checkpoint).
-- **E. data-valuation control** — `final + (0–6000)` vs `final + (6000–14691)`, same size.
-  First-half wins → those examples carry the DPO signal; tie → it's "more preference training,"
-  not *which* examples. (We control which pairs go in, so this generalizes to **curating** the
-  data with the model as the probe.)
-
-## Commands
-
-`ORC=/Users/joshrossi/Code/mlx-lm-example/.venv/bin/python` (HumanEval interpreter, this machine).
-
-```bash
-# A — x2 capability (final vs base; base x1=28.69 already recorded)
-MLX_BUN_ORACLE_PYTHON=$ORC bun scripts/eval.ts capability --candidate MiniCPM5 --adapter ./adapters/cpm5-uf-frombase
-# A — Exp 2 (gen base+trained responses, then judge head-to-head)
-bun scripts/experiments/prefbench.ts gen mtbench ./adapters/cpm5-uf-frombase mtbench-uf   # GPU
-bun scripts/experiments/prefbench.ts judge mtbench-uf                                      # codex
-# B — replay base→7k to recover the ~6k checkpoint (now checkpoints)
-SEQ=2048 EVAL_EVERY=500 RANK=16 SCHED=cosine LAMBDA=0.1 ADAPTER_DIR=./adapters/cpm5-uf-replay \
-  bun scripts/experiments/pref-control.ts orpo ~/.cache/mlx-bun/eval-data/uf-cpm5 uf-replay 7000 1e-5
-```
-
-## Harness gaps to close for D / E
-
-`pref-control.ts` does **not yet** support (needed for the DPO-boost + control arms):
-1. **Warm-start from an adapter** (`--resume` / load a non-zero adapter before training) —
-   the trainer has `warm_start_adapter` (see `trainer.ts`); just not wired into pref-control.
-2. **Data-subset selection** (feed a chosen subset / order of pairs, e.g. rows 0–6000) —
-   pref-control feeds the whole `train.jsonl`; needs a row-range / id-list option.
-3. λ is already env-controllable (`LAMBDA=`), so high-λ is ready once 1+2 exist.
-
-## Validated infrastructure (all green — see trainer-validation-experiment.md)
-
-- **Trainer:** positive controls pass — DPO & ORPO drive prefer-uppercase val acc → 1.0;
-  grads match autograd. `scripts/experiments/pref-control.ts`.
-- **Capability harness:** reproduces optiq across 6 tasks after two fixes (below).
-  `eval.ts capability --adapter` wired.
-- **Judge:** `gpt-5.4-mini` via `codex exec`, **keyless**, structured, order-swapped,
-  3/3 positive control. `scripts/experiments/llm-judge.ts`.
-- **Exp 2 harness:** `scripts/experiments/prefbench.ts` (gen/judge); prompts downloaded
-  (`mt_bench.jsonl` 80, `alpaca_eval.json` 805).
-- **MMLU frozen set:** optiq's exact 969 questions + dev exemplars captured
-  (`mmlu_optiq_frozen.jsonl` / `mmlu_optiq_dev.jsonl`) for parity work.
-
-## Gotchas / load-bearing facts
-
-- **`AdapterManager.mount` affects the *serving* forward** (eval generation, chat) **but NOT
-  the *training* `branchLogpMean`.** Measure training metrics via the trainLora emit, not mount.
-- **Eval env:** `MLX_BUN_ORACLE_PYTHON=$ORC` (HumanEval code-exec — wrong default path on this
-  machine); evals default to **non-thinking** (optiq parity; `MLX_BUN_EVAL_THINK=1` to re-enable).
-- **MMLU parity:** our number (47.7 old / ~50 argmax) vs optiq 52.4 is **sampling + forward
-  parity**, not noise (both deterministic argmax). Use the frozen set; remaining gap = our
-  forward vs `mlx_lm` (logit-diff test on the frozen prompts — **queued, GPU**).
-- **Determinism:** same seed/order → same adapter. Replay recovers any checkpoint.
-- **Server adapter API** (`POST /v1/adapters` + per-request `"adapter":"id"`) is the clean way
-  to compare *many* adapters via chat; **raw eval (`--adapter`) is required for capability**
-  (MMLU is logit-argmax, not chat generation).
-
-## Recommended order
-
-1. **A** (final vs base) — the headline, READY. Run x2, then Exp 2.
-2. **B** — replay to recover the 6k peak (cheap, ~45 min).
-3. **C** — eval base/6k/final on the suite (four-way needs D for the +6k arm).
-4. Close the **pref-control harness gaps** (warm-start + subset), then **D** (DPO-boost) and
-   **E** (data-valuation control) — the synthesis experiments.
-5. (Parallel/queued) **MMLU forward-parity** logit-diff to nail x1 ≈ 30.28.

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

@@ -1,92 +0,0 @@
-# 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/archive/investigations/pi-builtin-investigation.md

@@ -1,308 +0,0 @@
-# Investigation: pi as a "built-in" terminal for mlx-bun
-
-*2026-06-12. Question (PRODUCT_ROADMAP "Harness UX" / PLAN direction A):
-can `mlx-bun pi` drop the user into a working pi agent session against
-the locally running model — and what's the best mechanism? Sources:
-https://pi.dev/docs/latest (sdk, tui, rpc, custom-provider pages) plus
-direct inspection of the installed packages
-(`~/.bun/install/global/node_modules/@earendil-works/*`, v0.79.1).*
-
-> **Outcome (2026-06-14, what actually shipped).** This investigation
-> proposed shipping the subprocess launcher first and promoting to an
-> embedded flagship later. We went straight to the embedded design and
-> then **dropped the subprocess path entirely** (Option 2 + the
-> `--external-pi` fallback in P4): `mlx-bun pi` runs pi's own
-> `InteractiveMode` **in-process** (src/pi-terminal.ts) with a custom
-> mlx-bun coding-agent prompt, full coding tools + web tools, and pi's
-> native approval prompts — nothing to install. A user who already runs
-> pi connects it to the local model with **`mlx-bun harness pi`**
-> (Option 1, src/harness-pi.ts) — that's the only "their pi" path, since
-> launching a pi they already have was pure duplication. The web-chat
-> half (Option 4) ships via src/pi-web.ts. The analysis below is the
-> point-in-time reasoning that led here.
-
-## TL;DR
-
-**Yes, and better than hoped.** pi is not just embeddable — it is a
-Bun-native, MIT-licensed npm package whose own release binary is built
-with `bun build --compile`, the exact toolchain mlx-bun's Phase 5
-single-binary bundle already uses. The full interactive TUI (editor,
-chat history, all built-in commands) is an exported SDK class
-(`InteractiveMode`), not CLI-only internals. Four integration options
-exist, they are not mutually exclusive, and the recommended path is:
-ship the cheap subprocess launcher now, promote to a true in-binary
-embed as the flagship. pi's RPC mode separately gives us the protocol
-for the built-in web chat UI, so this investigation pays for direction
-A's part 1 as well.
-
-## What pi is, technically
-
-- Four MIT-licensed packages, all v0.79.1, all from
-  `github.com/earendil-works/pi`:
-  `pi-coding-agent` (13 MB, the agent + CLI + SDK), `pi-ai` (4.9 MB,
-  provider/streaming layer), `pi-agent-core` (1.3 MB), `pi-tui`
-  (1.9 MB, differential-rendering TUI lib). ~21 MB total on disk
-  before tree-shaking — negligible next to model weights, modest next
-  to mlx-bun's current binary.
-- **Bun-compile native**: `pi-coding-agent`'s `build:binary` script is
-  literally `bun build --compile ./dist/bun/cli.js ...` — upstream
-  ships a Bun single-file executable themselves. Embedding it in our
-  Bun bundle is a supported configuration, not an experiment.
-- Engines: node ≥ 22.19 (pi-tui uses `/v`-flag regexes — fails under
-  node 18, fine under Bun ≥ 1.3.x, which mlx-bun already pins).
-- Assets that must ride along in a binary (upstream's
-  `copy-binary-assets` is the manifest): theme JSONs, a few PNGs,
-  export-html templates, `photon_rs_bg.wasm` (image ops), and pi-tui's
-  prebuilt `.node` natives (`darwin-arm64`/`darwin-x64` ship in the
-  package).
-- Local-model support is **already proven on this machine**:
-  `~/.pi/agent/models.json` has an `mlx` provider
-  (`api: "openai-completions"`, baseUrl + `sk-optiq-` key, compat
-  flags) serving Qwen quants. mlx-bun's OpenAI surface is what pi
-  expects.
-
-## The four integration options
-
-### Option 1 — `mlx-bun harness pi`: configure the user's existing pi
-
-Write/merge the provider entry into `~/.pi/agent/models.json` (or drop
-a tiny extension that calls `pi.registerProvider(...)` — the
-documented programmatic route, which can even discover models
-dynamically from our `/v1/models`). Validate with one tiny request,
-print the launch command.
-
-- **Effort**: hours. **Risk**: low (must merge, not clobber, user
-  config — the docs' extension route avoids touching models.json at
-  all). **Verdict**: do regardless; this is the harness-adapter
-  pattern from the roadmap and it's nearly free.
-
-**Pros**: nearly free; respects the user's pi setup, sessions, themes,
-extensions; zero version coupling; the dynamic-discovery extension
-keeps the model list in sync with our server automatically.
-**Cons**: requires pi to already be installed; not "built-in" — the
-appliance story still has two moving parts; config-merge bugs are the
-classic way to annoy users (the extension route mostly avoids this).
-
-### Option 2 — `mlx-bun pi` (v1): spawn the user's installed pi
-
-Start our server, then spawn `pi` with a session-scoped provider
-config (extension dir or env) pointing at it. If pi isn't installed,
-print the install one-liner.
-
-- **Effort**: a day with polish. **Risk**: version skew with whatever
-  pi the user has; not "built-in" — two installs.
-- **Verdict**: the right v1. Real UX win immediately, zero coupling.
-- **Bonus**: unrecognized flags pass straight through, so
-  `mlx-bun pi -p "summarize @notes.md"` (pi's non-interactive print
-  mode), `--mode json/rpc`, `--continue`, `--resume` etc. all work on
-  day one without us implementing anything.
-
-**Pros**: fast to ship; full pi feature surface via passthrough;
-upgrades to pi arrive for free; failure modes are simple (no pi →
-print install hint). **Cons**: still two installs; we can't control
-the pi version (an upstream flag/behavior change can break our
-launcher); per-run provider injection needs care so we don't pollute
-the user's global config; process lifecycle (server + child TUI)
-needs clean shutdown handling.
-
-### Option 3 — SDK embed (the real "built-in"): pi inside the mlx-bun binary
-
-This is the one the question was really about, and the SDK is
-explicitly designed for it:
-
-- `createAgentSession({...})` builds a session; the
-  `examples/sdk/12-full-control.ts` example shows **zero-discovery**
-  embedding: in-memory `SessionManager`/`SettingsManager`/
-  `ModelRegistry`, custom `ResourceLoader`, explicit tool list,
-  runtime API keys — nothing leaks from/to `~/.pi` unless we want it
-  to.
-- `InteractiveMode` is exported: "full TUI interactive mode with
-  editor, chat history, and all built-in commands", constructed from
-  an `AgentSessionRuntime`. We do not rebuild a chat TUI from pi-tui
-  primitives (the tui docs are explicit that components are for
-  extensions, not a full-app kit) — we run *pi's own* TUI in-process.
-- Provider wiring: register an `openai-completions` provider at our
-  own server's baseUrl (loopback HTTP into our already-running
-  `Bun.serve` — simplest and keeps one code path for external
-  clients), models listed from our registry with real context-window
-  numbers per device profile.
-- Flow for `mlx-bun pi`: detect profile → ensure model → start server
-  in-process → `createAgentSession` against `localhost` →
-  `new InteractiveMode(runtime).run()`.
-
-Open engineering questions (all look tractable, none look fatal):
-
-1. **One process, two workloads**: the TUI event loop and the
-   server/generation queue share the JS thread; mlx compute happens in
-   native code but graph-build is JS-side (~ms-scale per decode step).
-   TUI rendering is differential and cheap; needs a smoke test for
-   input latency during decode, not a redesign.
-2. **Bundle plumbing**: embed pi's asset list + pi-tui `.node`
-   prebuilds + photon wasm into the Phase 5 compile. Upstream's own
-   binary build proves each piece works under `bun build --compile`;
-   our work is making *their* asset-path resolution find files inside
-   *our* bundle.
-3. **Version pinning**: pi moves fast (0.79.x); pin exact, upgrade
-   deliberately, keep Option 2 as the fallback path when upstream
-   breaks SDK surface.
-4. **Identity**: embedded pi should read/write its own session dir
-   (`~/.mlx-bun/pi-sessions` or similar) and not fight a user's
-   standalone pi install. The full-control example shows every knob
-   needed (`agentDir`, custom storage paths).
-
-- **Effort**: ~1–2 weeks including bundle work and latency testing.
-- **Verdict**: feasible and high-value; this is the appliance moment —
-  one binary, one command, a real agent on a local model. `-p` and
-  `--mode rpc/json` remain supported natively: `runPrintMode` and
-  `runRpcMode` are SDK exports, so the embedded CLI keeps pi's
-  headless modes.
-
-**Pros**: the true appliance — one binary, no prior installs; we pin
-and test the exact pi version we ship; full control of defaults
-(session dir, tools, system prompt, model list per device profile);
-in-process events shared with the web UI; offline-clean.
-**Cons**: most engineering (asset bundling, latency validation); we
-own the upgrade treadmill for a fast-moving 0.x dependency; embedded
-pi diverges from the user's own pi config/extensions unless we
-deliberately opt into discovery; binary grows ~20 MB.
-
-### Option 4 — RPC / JSON event-stream mode (not for the terminal — for the web UI)
-
-`pi --mode rpc` speaks JSONL over stdin/stdout: `prompt`, `steer`,
-`abort`, model control, state/stats queries, plus a streamed event
-model (`message_update` deltas, `tool_execution_*`, `turn_*`) and even
-an extension-UI sub-protocol. The docs name "custom frontends (web
-dashboards…)" as a primary use case.
-
-- **Verdict**: wrong tool for `mlx-bun pi` (we'd be rebuilding pi's
-  TUI on top of pi), but the **right backbone for the built-in web
-  chat UI**: `mlx-bun` serves a page; the server bridges
-  WebSocket ↔ RPC events (or drives `AgentSession.subscribe()`
-  in-process — same event shapes, no subprocess). Tool calls,
-  steering, and progress come for free instead of us re-implementing
-  an agent loop in the browser.
-
-**Pros**: documented, versioned JSONL protocol; UI-agnostic (web,
-IDE, bots); steering/abort/stats built in; works with either the
-subprocess or the embedded session as the engine. **Cons**: not a
-terminal UX at all; strict framing rules to honor; the extension-UI
-sub-protocol must be bridged if extensions prompt the user.
-
-## Does this make sense as a feature?
-
-Yes — it is arguably the highest-leverage product move available:
-
-- It converts mlx-bun from "a server you point things at" into a
-  complete local-AI appliance, which is the PRODUCT_ROADMAP north
-  star verbatim.
-- The marginal cost is small because the hard parts are already done
-  on both sides: our OpenAI surface is SDK-verified, pi's SDK is
-  designed for embedding, and both projects compile with the same Bun
-  toolchain. MIT licensing removes the bundling question.
-- One investigation, both deliverables: the same `AgentSession` event
-  stream powers the embedded TUI *and* the web chat UI, so direction
-  A's two halves share a core.
-- Caveats worth stating: we take on pi's release cadence as a
-  dependency; the agent quality ceiling is the local model's (12B
-  OptiQ tool-calling is decent but this becomes the showcase — the
-  Lucien-direction evals would tell us exactly how good); and the
-  embedded TUI must not degrade decode throughput (measure, per house
-  rules).
-
-## Implementation plan
-
-To be explicit about the recommendation: **the locally installed pi is
-the v1 stepping stone, not the destination.** Users who have their own
-pi always get first-class support (P1); the flagship `mlx-bun pi` ends
-as the embedded, single-binary experience (P3/P4).
-
-### P1 — `mlx-bun harness pi` (hours–1 day)
-
-1. Detect pi (`which pi`, `~/.bun/bin/pi`, npm global); report version.
-2. Generate an extension file (e.g. `~/.pi/agent/extensions/mlx-bun.ts`)
-   that calls `pi.registerProvider("mlx-bun", ...)` with **dynamic
-   discovery**: fetch our `/v1/models` at pi startup so the model list
-   tracks the server. No models.json surgery; trivially reversible
-   (delete one file).
-3. Validate: tiny completion against the running server through pi's
-   provider path; print `pi --provider mlx-bun` launch hint.
-4. Failure modes: pi missing → print install one-liner; server down →
-   offer to start it.
-
-### P2 — `mlx-bun pi` v1: subprocess launcher (~1–2 days)
-
-1. Ensure server: reuse a running instance if healthy, else start
-   in-process and wait for readiness.
-2. Resolve the pi binary; if absent, offer the installer.
-3. Spawn pi with stdio inherited and a **session-scoped provider**: a
-   generated `-e <tmp-extension>.ts` registering the provider for this
-   run only (no global config writes), plus
-   `--provider mlx-bun --model <profile default>`.
-4. **Pass through all remaining argv** — this is where `mlx-bun pi -p
-   "..."`, `--mode rpc`, `--continue`, `@file` args work for free.
-5. Lifecycle: child exit → optionally keep the server warm (flag);
-   SIGINT goes to the child (pi handles double-ctrl-C), server shuts
-   down cleanly after.
-
-### P3 — embed spike (≤1 week, run via `bun run`, no bundling yet)
-
-1. Add pi packages as pinned deps (exact `0.79.x`).
-2. Wire `createAgentSession` full-control style: in-memory
-   registry/settings, our provider at the loopback baseUrl, session
-   dir under `~/.mlx-bun/`, default tools, our system prompt.
-3. Run `new InteractiveMode(runtime)` in the same process as the
-   server.
-4. **Gates** (house rule — numbers on this machine): editor latency
-   during 12B decode subjectively clean + decode tok/s within noise
-   of server-only; tool-call round-trip (read/bash/edit) works against
-   the 12B; clean teardown.
-5. Decide discovery policy: default isolated; `--pi-config` opt-in to
-   the user's `~/.pi` extensions/skills/themes.
-
-### P4 — single binary + shared event plumbing (~1 week)
-
-1. Fold pi's asset manifest (theme JSONs, PNGs, export-html templates,
-   photon wasm, pi-tui darwin `.node` prebuilds) into the Phase 5
-   `bun build --compile`; patch/verify pi's asset-path resolution
-   inside the bundle (upstream's own binary build is the existence
-   proof).
-2. CLI surface: `mlx-bun pi [pi-args]` → embedded `InteractiveMode`;
-   `-p` → `runPrintMode`; `--mode rpc` → `runRpcMode`. Subprocess
-   path (P2) remains as `--external-pi` fallback.
-3. Web chat UI rides the same `AgentSession.subscribe()` events over
-   WebSocket (Option 4 shape, in-process — no subprocess needed).
-4. Upgrade policy: bump pi deliberately per release, re-run the P3
-   gates as the regression suite.
-
-### First-run starter model (folds into P2/P4; model gated on Phase 14)
-
-The first-run experience must not be "watch a progress bar for 10
-minutes." Plan: a sub-gigabyte **starter model** downloads first and is
-chatting within ~1 minute — with a docs-grounded "tour guide" system
-prompt (README + server-api + pi guide preloaded, so a 1B doesn't
-hallucinate about mlx-bun) and a banner: *"the ideal model for your Mac
-is downloading in the background."* The profile model streams behind it
-(sequenced, not parallel, so downloads don't split bandwidth); swap
-when ready.
-
-Measured sizes (HF tree API, 2026-06-12):
-
-| Candidate | Download | Note |
-|---|---|---|
-| gemma-4-e2b-it-OptiQ-4bit | 5.26 GB | smallest Gemma — disqualifies the family for the starter slot |
-| gemma-4-e4b / 12B OptiQ-4bit | 7.0 / 8.4 GB | profile models, not starters |
-| **Qwen3.5-0.8B-OptiQ-4bit** | **0.89 GB** | **preferred**: rides the Phase 14 Qwen port; doubles as the first tier-a parity target |
-| MiniCPM5-1B-OptiQ-4bit | 0.92 GB | strong (52% MMLU, +4.44 OptiQ delta) but a third architecture family — A/B later |
-
-Decisions: starter is **downloaded, never bundled** (a ~900 MB binary
-kills brew install); it stays on disk afterward (future
-speculative-decoding draft + always-works fallback). Hot-swap (or
-offer-to-swap) when the profile model lands is the only new runtime
-work. Dependency: a runnable sub-GB model requires the Phase 14 Qwen
-bring-up — the starter feature is the reason the 0.8B goes first there.
-
-## Recommended sequence
-
-P1 + P2 now (days, immediate demo value, zero coupling) → P3 spike
-with its latency gate → P4 single-binary flagship, reusing the event
-plumbing for the built-in web UI.