mlx-bun 0.5.0 → 1.0.0

package/docs/archive/planning/curve-sampler-research-plan.md

@@ -1,331 +0,0 @@
-# Curve sampler — preregistered research plan (distinctness track)
-
-*2026-07-01. Status: PREREGISTERED — hypotheses and analysis fixed BEFORE the
-fresh runs. Mandate (Josh): "I am not ready to give up on the curve sampler.
-I think there ARE outputs that cannot be reached by just p, k and temp — temp
-means you cannot control different areas of prob." The old experiments are not
-trusted as-is (audit in §6); this plan replaces them. The distinctness track is
-being PURSUED, not folded into the assessment's "honest negative" framing
-(reports/curve-designer-paper-assessment-2026-07-01.md) — the assessment's
-venue advice (workshop/demo tier unless the empirical section lands) is noted,
-not contested.*
-
-Object under study: `src/curve-sampler.ts` — the v2 monotone-cubic (PCHIP)
-log-prob transfer curve, `p_out ∝ exp(curve(log p_in))`, replacing
-temperature+top-p/top-k when active.
-
----
-
-## 1. The theorem (in hand — pure math, section-ready)
-
-**Setup.** Base next-token logprobs ℓ ∈ ℝ^V, base probs p = softmax(ℓ). Call a
-sampler a **single-slope truncation sampler** if its output is
-
-  q_i ∝ exp(ℓ_i / T) for i ∈ S,  q_i = 0 otherwise,
-
-for some temperature T > 0 and survivor set S. This family contains, exactly:
-
-| method | survivor set S | S is a rank prefix? | slope on S |
-|---|---|---|---|
-| temperature | V | yes (trivially) | 1/T |
-| top-k | k highest | yes | 1/T |
-| top-p | smallest prefix with mass ≥ p | yes | 1/T |
-| min-p | {i : p_i ≥ α·p_max} | yes | 1/T |
-| top-nσ | {i : ℓ_i ≥ ℓ_max − n·σ(ℓ)} | yes | 1/T |
-| ε / η (desmoothing) | absolute / entropy-scaled floor | yes | 1/T |
-| typical | surprisal closest to H | **not necessarily** | 1/T |
-| mirostat | feedback-chosen k per step | yes (per step) | 1/T |
-
-Every published truncation sampler differs only in HOW it picks S — on the
-survivors, all of them apply ONE global slope.
-
-**Gap-ratio invariant.** For any a, b, c ∈ S with distinct ℓ values:
-
-  R(q) := (ln q_a − ln q_b) / (ln q_b − ln q_c)
-        = (ℓ_a − ℓ_b) / (ℓ_b − ℓ_c) = R(p).
-
-Proof: ln q_i = ℓ_i/T − ln Z_S; the normalizer cancels in differences, T
-cancels in the ratio. So **no choice of T and no choice of survivor set can
-change the log-gap ratios of surviving tokens** — one scalar cannot set
-different sharpness in different probability regions.
-
-**The curve breaks it.** A monotone map w with slope s₁ on one log-prob region
-and s₂ ≠ s₁ on another gives R(q) = (s₁/s₂)·R(p) for tokens straddling the
-regions — order preserved (monotonicity), ratios changed. Hence a curve
-distribution with mismatched gap ratios is unreachable EXACTLY by any member of
-the family above; the witness (§2) shows the inexact gap is also structurally
-large where it matters. Truncating the mismatched region instead costs its
-whole mass in TV — so TV_min ≳ min(ratio-mismatch cost, lifted-band mass / 2).
-
-**Honest boundary (both directions).** The curve is a FIXED pointwise map of
-the token's own value: it cannot express distribution-ADAPTIVE head selection
-(min-p's α·p_max, top-nσ's σ(ℓ), typical's H, mirostat's feedback) nor
-non-monotone re-ranking (XTC). The two families intersect exactly on
-{temperature + absolute-threshold gates}; **neither contains the other**. The
-claim being pursued is "the curve reaches per-step distributions the standard
-family cannot", not "the curve subsumes it". (The fork-routing impossibility —
-fork-ness is a trajectory property invisible to any local warp — stands as the
-other half of the characterization; see curve-bisector-routing.md, strengthened
-per §6 F5.)
-
-## 2. The witness (in hand — measured 2026-07-01)
-
-`scripts/experiments/curve-distinctness.ts` (this session; MiniCPM5-1B-OptiQ-
-4bit, M1 Max 32 GB). 20 real next-token distributions (5 prompts × {start,
-max-entropy "fork", min-entropy, after-comma}); per position, a witness curve
-that (i) keeps the top-2 gap EXACTLY as sharp as T=0.7 and (ii) lifts the
-p∈[0.001, 0.02] band's total mass to 2× its T=0.7 value (or the largest
-feasible factor on flat distributions). Fit = exhaustive (T ∈ [0.05, 3] step
-0.001-refined, survivor-prefix m ∈ {1..300, 325..2000, V}) minimizing total
-variation — since every (p, k, min-p, top-nσ, ε) survivor set is a rank
-prefix, the m-sweep covers ALL of them jointly, any application order.
-
-| pos | kind | H (nats) | band mass ref→witness | TV_min | (T*, k*) |
-|---|---|---|---|---|---|
-| creative start | start | 1.67 | 0.011→0.022 (×2.0) | 0.0105 | (0.73, 1773) |
-| creative fork | max-H | 4.94 | 0.270→0.512 (×1.9) | **0.187** | (1.73, 168) |
-| creative comma | after-comma | 4.12 | 0.068→0.136 (×2.0) | 0.0630 | (0.77, 402) |
-| advice start | start | 1.10 | 0.010→0.021 (×2.0) | 0.0075 | (0.74, 798) |
-| advice fork | max-H | 3.99 | 0.204→0.408 (×2.0) | **0.167** | (0.88, 265) |
-| advice comma | after-comma | 1.15 | 0.002→0.004 (×2.0) | 0.0020 | (0.70, 1773) |
-| factual start | start | 1.16 | 0.015→0.030 (×2.0) | 0.0096 | (0.77, 94) |
-| factual fork | max-H | 3.43 | 0.072→0.143 (×2.0) | 0.0593 | (0.76, 243) |
-| factual comma | after-comma | 1.92 | 0.028→0.056 (×2.0) | 0.0265 | (0.74, 101) |
-| continuation start | start | 1.01 | 0.009→0.017 (×2.0) | 0.0067 | (0.74, 1323) |
-| continuation fork | max-H | 5.19 | 0.369→0.568 (×1.5) | **0.119** | (1.23, 235) |
-| continuation comma | after-comma | 2.13 | 0.032→0.064 (×2.0) | 0.0165 | (0.78, 500) |
-| brainstorm start | start | 2.16 | 0.014→0.029 (×2.0) | 0.0142 | (0.72, 1723) |
-| brainstorm fork | max-H | 5.76 | 0.434→0.585 (×1.35) | **0.114** | (1.20, 264) |
-| brainstorm comma | after-comma | 1.73 | 0.016→0.033 (×2.0) | 0.0177 | (0.73, 1148) |
-
-(5 min-entropy positions skipped: band empty — near-deterministic steps have
-nothing to lift; the theorem is about positions where sampling matters.)
-
-- **Irreducible TV: min 0.0020, median 0.0177, mean 0.0547, max 0.187.**
-- **Fitter control: refitting plain T=0.7 gives max TV 0.008** (mostly
-  ≤0.002) — the gaps are real, 10–20× above fitter slack at forks.
-- **The gap concentrates exactly at forks** (high-entropy positions): TV
-  0.11–0.19 — no (T, p, k, min-p, top-nσ) combination gets within 11–19% total
-  variation of the witness there. Best fits either keep T≈0.7-sharp heads and
-  miss the band, or go hot (T*=1.2–1.7) to buy band mass and give up the top-2
-  gap. Full-support pure temperature is worse still (TV 0.17–0.28 at forks).
-- The witness is realizable by the shipped designer: the PCHIP spline through
-  the printed knots reproduces the analytic piecewise-linear witness to mean
-  TV 0.0083; the curve JSON is printed by the script for pasting into
-  `/curves`.
-- **Text-level (directional, N=30/arm, 3 prompts, not preregistered):** under
-  a fixed global witness curve vs its best global match (T=0.77, k=750),
-  per-step TV along generated trajectories averaged 0.024–0.061 (max 0.24),
-  but distinct-1/2/3 and junk were indistinguishable at this N. Honest read:
-  **per-step distinctness is proven; whether it produces measurably different
-  TEXT distributions is exactly H2 below, and is open.**
-
-Reproduce: `bun scripts/experiments/curve-distinctness.ts` (flags:
-`--model`, `--positions-per-prompt`, `--gen-n`, `--gen-tokens`, `--skip-text`).
-
-## 3. Hypotheses (fixed before the fresh runs)
-
-- **H1 — per-step distinctness. PROVEN** (§1 theorem + §2 witness). The curve
-  family reaches next-token distributions with TV ≥ 0.05 (median-fork ≥ 0.1)
-  from the entire single-slope truncation family, at matched top-2 sharpness.
-  Remaining H1 work is replication breadth only: same probe on e4b + 12B
-  (262k vocab) and 20 → 100 positions. *Null outcome possible:* larger-vocab
-  models could shrink the band-lift headroom; report whatever comes out.
-- **H2 — text-level distributional distinctness at matched coherence.** There
-  exists a curve (the §2 global witness is the preregistered candidate) such
-  that the distribution of its generations differs from EVERY tuned
-  single-slope baseline's at equal coherence: MAUVE(curve, baseline) <
-  MAUVE(baseline-seed-A, baseline-seed-B) − δ, with δ set by the bootstrap CI.
-  *Null outcome is live:* per-step TV of 0.02–0.06 per token may wash out in
-  60-token texts (the directional N=30 probe saw no distinct-n separation).
-  A null here = "per-step distinctness does not surface in text statistics at
-  this scale" — publishable as the boundary of claim 1, and the method paper
-  stays closed.
-- **H3 — a task/regime where curve-reachable points lie OUTSIDE the
-  (T,p,k)+min-p+top-nσ Pareto front** (quality × diversity at matched
-  coherence). Candidate regimes (fixed now): (a) constrained-form generation
-  where the head must stay sharp while mid-band alternatives carry the
-  variety (structured lists, fixed-opening continuations); (b) fork-dense
-  creative prompts (the §2 fork TV is largest there); (c) repeated-sampling
-  best-of-N settings where band mass controls candidate coverage. *Null
-  outcome is live* and would land exactly on the assessment's analysis-paper
-  framing.
-
-## 4. Preregistered protocol (the referee-grade run)
-
-**Models:** MiniCPM5-1B (73k vocab), gemma-4-e4b (262k), gemma-4-12B (262k) —
-all cached OptiQ-4bit builds; the vocab split is a known moderator (hlg
-investigation §15).
-
-**Arms (per model, per prompt):**
-1. `default` — the model's own generation_config recipe (temperature/top-p/top-k).
-2. `best-Tpk` — (T, p, k) tuned on a held-out prompt set for the target
-   coherence level (grid: T ∈ {0.5..1.5 step 0.1} × p ∈ {0.85, 0.9, 0.95, 1} ×
-   k ∈ {0, 40, 64, 100, 200}).
-3. `min-p` — α ∈ {0.02, 0.05, 0.1, 0.2} × T ∈ {0.7..1.5}.
-4. `top-nσ` — n ∈ {1, 1.5, 2, 3} × T ∈ {0.7..1.5}.
-5. `mirostat` — τ ∈ {3, 4, 5} (implement or mark N/A if not landed; absence
-   documented, not silently dropped).
-6. `curve-witness` — the §2 global witness curve (knots frozen in the script
-   output, checked into the plan by hash once the run starts).
-7. `curve-tuned` — ONE curve hand-tuned in the designer per model BEFORE
-   scoring (tuning prompts disjoint from eval prompts), then frozen.
-
-**Prompts:** 30 prompts, 10 per pole {creative/open, advice/constrained,
-factual} — fixed list checked in before the run; disjoint 10-prompt tuning set.
-
-**N and power.** N = 100 continuations per (arm × prompt-pole × model) cell,
-64 tokens each. Basis: the old N=10 runs put the sd of a cell's self-BLEU
-run-mean at ≈0.06 (runO swing 0.083 between two seed bands), i.e. a minimum
-detectable effect ≈ 0.17 at N=10 — bigger than every effect ever claimed. At
-N=100 the run-mean sd scales to ≈0.019, MDE ≈ 0.053 at α=.05/power .8; for
-Δ≈0.05 effects run the planned replication (below) and pool. MAUVE gets
-bootstrap CIs (1000 resamples); LLM-judge cells get binomial CIs.
-
-**Seed discipline.** Explicit integer seeds only — no wall-clock seeding
-anywhere (the batch same-ms collision class). Disjoint bands per arm:
-arm i uses seeds `10000·(i+1) + {0..N−1}`. The WHOLE grid is run TWICE with
-band offset +5000 (built-in fresh-seed replication — the discipline that
-caught both premature verdicts in hlg §14). No cross-arm seed pairing (arms
-are different distributions; pairing buys nothing and invites accidental
-correlation stories).
-
-**Metrics (all fixed now):**
-- **Coherence gate (per sample, gates everything else):** (a) non-Latin
-  letter ratio < 1% AND (b) mean per-token logprob under the model's OWN
-  default recipe ≥ (pole-median of the default arm − 1.5 nats) AND (c) no
-  4-gram repeated ≥ 3× within the sample. (b)/(c) close the F4 hole — Latin
-  word-salad and repetition-degeneration currently pass the gate.
-- **Diversity:** coherence-GATED distinct-1/2/3 (computed only over gate
-  survivors, reported with survivor rate) + self-BLEU (leave-one-out, so it
-  has per-sample values and a real variance estimate).
-- **Distributional:** MAUVE between arm outputs and (i) the default arm and
-  (ii) each other, per pole; embedding model = a real sentence encoder (not
-  the LM's own hidden states — a known weak proxy).
-- **Quality:** LLM-judge per the dreaming eval methodology (cloud judge;
-  hand-curated gold anchors drafted before scoring; surface-variant dedup;
-  judge the artifacts, blind to arm, position-flipped pairs). Judge prompt
-  frozen in the harness before the run.
-- **Per-step (mechanism):** mean TV along trajectories between the curve arm
-  and its best-fit single-slope arm (already implemented in the witness
-  script) — connects H2 outcomes back to H1 magnitude.
-
-**Pareto construction (H3):** per pole × model, plot (coherence-gated
-diversity, judge quality) for every arm-cell; H3 is supported iff a curve
-cell sits outside the convex hull of ALL single-slope cells with
-non-overlapping bootstrap CIs, in ≥2 of 3 models.
-
-**Commands (harnesses to extend from the existing probe):**
-```bash
-# H1 replication breadth (exists today):
-bun scripts/experiments/curve-distinctness.ts --model gemma-4-e4b-it-OptiQ-4bit --skip-text
-bun scripts/experiments/curve-distinctness.ts --model gemma-4-12B-it-OptiQ-4bit --skip-text
-# H2/H3 (to build: curve-frontier.ts = hlg-frontier.ts skeleton + arms above,
-# N=100, gate (a)+(b)+(c), leave-one-out self-BLEU, MAUVE export):
-bun scripts/experiments/curve-frontier.ts --model <m> --n 100 --seed-band 10000
-bun scripts/experiments/curve-frontier.ts --model <m> --n 100 --seed-band 15000   # replication
-# LLM-judge pass: reuse the dreaming judge protocol (docs/design/* memory-synthesis eval).
-```
-Machine note: label every result with host/chip/RAM (two laptops in rotation —
-M1 Max 32 GB / M4 Pro 24 GB; neither canonical). Nothing here is a perf claim,
-but the labeling rule stands.
-
-**Decision rules (fixed now).**
-- H2 supported → the paper gains an empirical section 4; method-adjacent
-  framing becomes defensible at workshop+.
-- H2 null, H3 null → ship the assessment's analysis paper (theorem + witness +
-  falsification methodology + tool); the distinctness result stays as the
-  per-step section. No re-running with new metrics until a NEW preregistered
-  amendment is written.
-- Any post-hoc metric additions are labeled exploratory, never headline.
-
-## 5. Paper skeleton this feeds
-
-1. The curve designer (tool, live demo). 2. Expressivity: the gap-ratio
-invariant + the two-sided boundary (§1) + fork-routing locality impossibility.
-3. The witness — per-step unreachability, quantitative (§2). 4. Text-level
-results (H2/H3, whatever they are). 5. Sampler-evaluation hygiene (fresh-seed
-repeats catching both false negative and false dominance; coherence-gated
-diversity; the audit below as methods material).
-
-## 6. Why the old data is not trusted — audit of the prior experiments
-
-Committed artifacts checked: `docs/archive/investigations/curve-runs/*.json`,
-`docs/archive/investigations/hlg-runs/*`, harness sources. Severity: **INVALIDATES** /
-**WEAKENS** / cosmetic.
-
-- **F1 — INVALIDATES (the old distinctness claim).** The curve-temp family
-  (`scripts/experiments/curve-temp-match.ts:53-69`, `curve-temp-seedsearch.ts:23-47`,
-  `curve-temp-grid.ts:26-41`, `curve-temp-weights.ts:28-52`) tests whether pure
-  temperature EXACTLY reproduces a specific 64–90-token curve-generated string
-  across ~924 samples. (a) No control arm: a temperature-generated string would
-  also never be reproduced at other seeds — P(specific sequence) =
-  e^(−Σ per-token surprisal) ≈ 0 for ANY stochastic sampler, so "0 exact
-  matches" is the guaranteed outcome and distinguishes nothing. (b) With
-  top_p=0/top_k=0 the support is FULL — every string is reachable by
-  temperature with p>0, so "temperature won't go there" is a category error at
-  the string level; the meaningful object is the per-step distribution (now
-  measured properly in §2). (c) The headline "0 crossed the fork" is
-  conditioned on first reproducing the 84-char prefix exactly
-  (`curve-temp-grid.ts:11,31`; `curve-temp-seedsearch.ts:28-30`) — essentially
-  only the curve's own seed ever reached the fork, so the fork test had
-  effective N≈0. Consequence: `curve-bisector-routing.md` §1's "the curve still
-  reaches outputs temperature can't" (repeated in its §3 conclusion) is
-  unsupported by those runs. The claim happens to be TRUE per §1–2 here, but
-  for the per-step reason, not the exact-string one.
-- **F2 — INVALIDATES (transfer of the "wash" verdict to the v2 curve).** The
-  only terrain map of the v2 designer family, `scripts/experiments/curve-terrain.ts:18`
-  (`--n` default 2, max 5), ran at **N=2 samples/cell, 48 tokens, 2 prompts**
-  (committed artifact `curve-runs/curve-terrain.json`: n=2) — self-BLEU at N=2
-  is meaningless. Every N=10 frontier number (hlg-frontier/runK-runO) measured
-  the **v1 HLGShaper** — a different sampler (adaptive windowed-anchor, i.e.
-  distribution-dependent, OUTSIDE the fixed-curve family). **The v2 drawn-curve
-  family has never been competitively evaluated at any usable N.** The
-  assessment's "method paper closed by own data" inherits this gap.
-- **F3 — WEAKENS (every diversity comparison at N=10).** From the
-  investigation's own runO: a cell's self-BLEU run-mean moved 0.083 between
-  seed bands → sd(run-mean) ≈ 0.06 → minimum detectable effect ≈ 0.17 at N=10
-  with one run/cell. Every delta ever claimed (0.05–0.11) is below MDE. The doc
-  ultimately landed there honestly ("wash at this N"), but intermediate
-  verdicts (§12 "conclusive", §13 "definitive", §14 "DOMINANCE") each
-  overran the resolution; ~200+ samples/cell is the floor for Δ≈0.05 (§4 N).
-- **F4 — WEAKENS (coherence gates).** All automated verdicts gate coherence on
-  non-Latin-script ratio alone (`hlg-map.ts:51-56`, `hlg-frontier.ts:55-59`,
-  `curve-terrain.ts:94-98`): Latin-script incoherence ("the planet' adorable
-  axis", "—aving purpose", repetition loops) passes as 0% junk, so
-  diversity-vs-coherence frontiers can be bought with undetected degeneration.
-  The doc's "read the text" discipline patched this manually; the §4 gate
-  (logprob + repetition + script) mechanizes it.
-- **F5 — WEAKENS (the fork-routing "falsification").** `bisector-route.ts:16`
-  — 20 seeds × 1 prompt/pole; the FORK/REMERGE hazard ratios rest on 3–16
-  fork-departure events per policy (`curve-runs/bisector-route.json` cohN);
-  binomial SE on the rates is ±0.1–0.2, so "router 0.79 ≈ identity 0.77" is an
-  equivalence claim an underpowered test cannot establish (it could not
-  distinguish a 1.5–2× real ratio). The point estimates being identical is
-  suggestive, and the locality argument is sound a priori — but the doc's
-  headline "Falsified" and the assessment's "falsified with a proper control"
-  overstate; the doc's own caveats (5 prompts/pole, more seeds, user-drawn 5th
-  policy) are the fix and move into this protocol.
-- **F6 — cosmetic (seeding).** No wall-clock/same-ms seeding in any audited
-  harness — all fixed explicit seeds (curve-temp 100+i / 0..299 / 200+i;
-  curve-terrain 7300; hlg-map 1234+i, canary 7+i; hlg-frontier 1000+i;
-  hlg-grid 2000+i; bisector-route 1..20) and `/generate` derives per-sample
-  seeds as base+i (`src/server.ts:1680`). The batch same-ms collision bug does
-  not taint these. Arms share seed bases (paired design) with only runO as a
-  fresh-seed repeat — §4 makes replication structural instead.
-- **F7 — cosmetic.** `bisector-trace.ts` computes rank-2 labels via
-  `forwardHidden+logitsFromHidden` while the greedy reference comes from
-  `generate()` — the two are known to diverge on near-ties
-  (`src/eval/runner.ts:109-113`), and near-ties are forks; the committed
-  artifact shows tfMismatch 0/1/0, so no material impact, but the assert
-  should stay.
-
-## 7. Doc map
-
-- This plan: `docs/planning/curve-sampler-research-plan.md` (preregistration —
-  amend by appending, never by silent edit).
-- Witness probe: `scripts/experiments/curve-distinctness.ts`.
-- Assessment: `reports/curve-designer-paper-assessment-2026-07-01.md`.
-- Prior investigations (superseded on the points in §6):
-  `docs/archive/investigations/hlg-sampling-investigation.md`,
-  `docs/archive/investigations/curve-bisector-routing.md`.

package/docs/archive/planning/journal.md

@@ -1,316 +0,0 @@
-# Engineering Journal
-
-Ongoing, chronological record of AI/agent decisions, investigations, and
-corrections — newest work appended under a dated heading. Purpose: bring
-a fresh agent up to speed on *why* the code is the way it is. PLAN.md is
-the what/when (phases, exit criteria); this is the narrative behind it.
-
-## 2026-06-13 — MiniCPM5 starter port (branch `codex-minicpm5-starter-port`)
-
-- Created a dedicated branch for the MiniCPM5 starter-model port.
-  - Attempted `codex/minicpm5-starter-port`, but git ref creation was blocked by the sandbox/ref layout.
-  - Used `codex-minicpm5-starter-port`.
-- Corrected the execution order per Josh's direction:
-  - Goldens first.
-  - Build the port second.
-  - Compare implementation against the goldens continuously.
-- Downloaded `mlx-community/MiniCPM5-1B-OptiQ-4bit`.
-  - Snapshot: `~/.cache/huggingface/hub/models--mlx-community--MiniCPM5-1B-OptiQ-4bit/snapshots/664aabaed233c653f82716d8dc822234d0091f78`.
-  - Verified by the repo downloader.
-- Added MiniCPM5 snapshot constants to `tests/paths.ts`.
-- Added `scripts/regen-minicpm5-goldens.ts`.
-  - Uses `MLX_BUN_ORACLE_VENV=/Users/joshrossi/Code/mlx-lm-example/.venv`.
-  - Drives stock `mlx_lm.load()` against the MiniCPM5 snapshot.
-  - Writes `minicpm5-parity.json` and `minicpm5-logits-step*.bin`.
-- Generated oracle goldens before porting.
-  - Output dir on this machine: `goldens/apple-m1-max/`.
-  - Prompt: `The capital of France is`.
-  - Prompt ids: `[0, 608, 4894, 304, 6918, 357]`.
-  - Logit steps: 4.
-  - Greedy tokens: 100.
-- Inspected MiniCPM5 config and tensor layout.
-  - `model_type: "llama"`.
-  - 24 full-attention layers.
-  - Hidden size 1536.
-  - 16 query heads, 2 KV heads.
-  - Head dim 128.
-  - RoPE theta 5,000,000.
-  - RMS norm epsilon `1e-6`.
-  - SiLU/SwiGLU MLP.
-  - Untied embeddings with quantized `lm_head`.
-  - Weight paths are standard `model.layers.N.*`, plus `model.embed_tokens`, `model.norm`, and `lm_head`.
-- Decision: first implementation is the naive Llama path only.
-  - No compiled decode.
-  - No fused custom kernels.
-  - No speculative decode.
-  - No vision path.
-  - Compare against goldens before optimizing.
-- Added initial Llama port edits.
-  - `src/config.ts`: flat Llama config defaults, full-attention layer types, default RoPE params.
-  - `src/mlx/ffi.ts` / `src/mlx/ops.ts`: `mlx_sigmoid` binding for SwiGLU.
-  - `src/model/minicpm5.ts`: concrete MiniCPM5 graph mirroring `mlx_lm.models.llama`.
-  - `src/model/factory.ts`: dispatch this known `model_type === "llama"` artifact to `MiniCPM5Model`.
-  - `src/generate.ts`: widen runtime model type and gate compiled decode to Gemma-only.
-- Added `tests/minicpm5-parity.test.ts`.
-  - Reads the MiniCPM5 goldens.
-  - Runs the new `MiniCPM5Model`.
-  - Initially required 12 greedy ids and the first 4 logit vectors; expanded to the full 100-token golden after the first green run.
-- First MiniCPM5 parity run passed immediately.
-  - Command: `bun test tests/minicpm5-parity.test.ts`.
-  - Result: 12/12 greedy ids matched; first 4 full-logit vectors were bit-exact.
-  - Decision: expand the test to the full 100-token golden before starter wiring.
-- Expanded MiniCPM5 parity to 100 greedy tokens.
-  - Command: `bun test tests/minicpm5-parity.test.ts`.
-  - Result: 100/100 greedy ids matched; first 4 full-logit vectors remained bit-exact.
-  - Decision: naive Llama graph is correct enough to proceed to integration wiring.
-- Added shared supported-model predicate.
-  - `src/model/support.ts`: supports `gemma4*` and `llama`.
-  - CLI and server library support checks now use the same predicate.
-- Swapped the first-run starter repo to `mlx-community/MiniCPM5-1B-OptiQ-4bit`.
-  - Recommended Gemma download still runs in the background for the machine profile.
-- Widened server context model type to `RuntimeModel`.
-- Updated public/library/docs surfaces.
-  - `src/index.ts` exports `MiniCPM5Model` and `RuntimeModel`.
-  - `src/lora.ts` accepts `RuntimeModel` so server construction is type-consistent.
-  - README quickstart and supported-model table now include MiniCPM5.
-  - PLAN Phase 16 and publishing gate now record MiniCPM5 Track A as chosen/ported.
-- Process/testing note from Josh:
-  - Running the full sharded suite can start Bun test processes that load large models and in-process servers.
-  - Do not run the full suite again casually during this branch; use focused MiniCPM5 parity/smokes unless Josh explicitly wants the full model-loading suite.
-  - The suspected large Bun process was already killed before inspection; `ps` showed no remaining Bun processes afterward.
-- Test-proof correction:
-  - Josh called out that the `bun:test` pass looked suspiciously fast and was not good enough evidence as presented.
-  - Verified with an explicit one-off script that config/weights/model construction occurs and first eval touches the model (`weightsBytes` about 0.907 GB, first argmax token 8181).
-  - Added `scripts/check-minicpm5-port.ts`: hard check, no skip guards, requires snapshot + goldens, prints open/construct/eval timings, and compares 100 oracle tokens plus first 4 logit vectors.
-  - Hard-check result:
-    - `open`: 4.1 ms.
-    - `construct`: 2.0 ms.
-    - `first eval`: 81.7 ms.
-    - `decode`: 100 tokens in 691.8 ms.
-    - `parity`: 100/100 greedy ids, 100/100 full-logit vectors bit-exact.
-  - Explanation: `Weights.open` and model construction are lazy/mmap-backed; the model is actually touched at eval time, not construction time.
-- Oracle-strength correction:
-  - Josh clarified that oracle parity means bit-for-bit comparison against oracle logits, not just token agreement plus a few early logits.
-  - Changed MiniCPM5 golden regeneration to dump full last-position logits for all 100 decode steps.
-  - Changed the hard check and parity test to require/compare all 100 logit binaries.
-- MiniCPM5 parity matrix:
-  - Standard bf16 KV mode must match stock `mlx-lm`.
-  - Mixed precision KV mode using the shipped `kv_config.json` must match `mlx-optiq`.
-  - Server default should use the shipped mixed-KV config.
-  - `--kv-quant off` must remain the standard-cache mode.
-  - Added `scripts/regen-minicpm5-kv-goldens.ts` and `tests/minicpm5-kv-parity.test.ts` for the OptiQ mixed-KV path.
-- Strengthened `tests/minicpm5-parity.test.ts` after Josh's pushback.
-  - Removed skip guards for this MiniCPM5 proof.
-  - Requires the downloaded snapshot and MiniCPM5 goldens.
-  - Constructs the model inside the test body, asserts `weightsBytes > 900 MB`, and prints open/construct/first-eval/decode timings.
-  - The logit comparison is full-vector last-position logits from the same golden prompt; `lastPositionLogits()` forces evaluation via `toFloat32()`.
-- Live chat failure diagnosis:
-  - Josh opened `/chat`, sent `hi there`, and saw an empty assistant bubble.
-  - Direct curl to `/v1/chat/completions` returned `QuantizedKVCache: use updateAndFetchQuantized`.
-  - Cause: MiniCPM5 ships `kv_config.json`; the server applied mixed KV quant by default, but `MiniCPM5Model` only supports bf16 KV so far.
-  - Temporary workaround was to serve MiniCPM5 bf16 KV only; this was later reverted once MiniCPM5 got QuantizedKVCache parity.
-  - Also fixed `/chat` to surface streamed `{ error }` SSE payloads instead of swallowing them into an empty assistant bubble.
-  - Verified with a temporary in-process server on an ephemeral port:
-    - `/stats` reported KV mode `bf16`, 24 bf16 layers.
-    - `/v1/chat/completions` for `hi there` returned HTTP 200 with assistant text.
-    - Observed default MiniCPM5 behavior includes `<think>`; non-thinking starter UX still needs template/config handling.
-- Naming/scope correction from Josh:
-  - This branch should not become a generic Llama platform.
-  - Renamed the concrete model file/class to `src/model/minicpm5.ts` / `MiniCPM5Model`.
-  - The config still says `model_type: "llama"` because that is the upstream artifact; factory dispatch treats that as this known MiniCPM5 starter artifact for now.
-  - Re-ran focused parity after the rename: 100/100 greedy ids matched; first 4 logits bit-exact.
-- Tightened support recognition so this is not generic Llama support.
-  - Registry/library support uses repo id `MiniCPM5-1B-OptiQ-4bit` plus `model_type: "llama"`.
-  - Factory dispatch checks the known MiniCPM5 config shape before constructing `MiniCPM5Model`.
-  - Other Llama configs throw unsupported instead of silently using the MiniCPM5 graph.
-  - Re-ran focused parity after this tightening: 100/100 greedy ids matched; first 4 logits bit-exact.
-- Completed the oracle-strength MiniCPM5 parity matrix.
-  - Standard cache mode matches stock `mlx-lm`: 100/100 greedy ids and 100/100 full last-position logit vectors are bit-exact.
-  - Mixed precision cache mode matches `mlx-optiq` with the shipped `kv_config.json`: 100/100 greedy ids and 100/100 full last-position logit vectors are bit-exact.
-  - `MiniCPM5Model` now consumes `QuantizedKVCache` directly and routes quantized triples through `quantizedSdpa`.
-  - Production generation now mirrors OptiQ's quantization order: first prompt prefill runs bf16, then populated caches are quantized before decode.
-- Restored MiniCPM5 server default to mixed KV from `kv_config.json`.
-  - Temporary in-process server `/stats` reported `mixed (kv_config.json)`, 6 kv8 layers and 18 kv4 layers.
-  - `kvQuant: off` reported 24 bf16 layers and still served chat correctly.
-  - Non-streaming and streaming `/v1/chat/completions` returned HTTP 200 without the prior `QuantizedKVCache: use updateAndFetchQuantized` error.
-- Read the MiniCPM5 OptiQ manual.
-  - MiniCPM5's template contract is `chat_template_kwargs.enable_thinking`.
-  - Default starter behavior is no-think (`enable_thinking=false`), matching the manual's fast direct-answer mode.
-  - Explicit `chat_template_kwargs: { "enable_thinking": true }` opens the `<think>` reasoning channel.
-  - Server prompt rendering now forwards that flag and defaults MiniCPM5 to no-think when absent.
-- Pi harness correction after Josh's pushback:
-  - Mistake: briefly changed branch code toward `~/.pi/agent/models.json` upsert and described the generated extension as stale.
-  - Correction: reverted branch code/docs/tests back to the existing extension-based live-discovery methodology; the generated extension is the path that worked for Gemma and must remain first-class.
-  - Note: I had already run the harness while debugging, which modified Josh's local pi config outside the repo. Do not mutate that again without explicit instruction.
-- MiniCPM5 tool-call corruption fix:
-  - Reproduced Josh's broken output: `name="read"> name="path">...`.
-  - Root cause: the server applied Gemma's tool sentinel token ids globally. In MiniCPM5, token 49 decodes to literal `<`, and `<function` / `<param` are added special tokens stripped by `decode(..., true)`.
-  - Ported the OptiQ behavior: tool parsing is decoded-text based and active only when tools are declared. Gemma keeps its family sentinel path; MiniCPM5 tool-active decoding preserves special tokens and parses native `<function name="..."><param name="...">...` XML into OpenAI `tool_calls`.
-  - Added `tests/minicpm5-tools.test.ts`, covering non-streaming and streaming tool calls with the real MiniCPM5 snapshot.
-- Full-branch review pass after Josh reported "a lot of bugs" vs the Gemma 4 port quality. Four real defects found and fixed:
-  1. **Multi-turn tool conversations crashed at render time.** MiniCPM5's template uses `[a, b]|min` in its assistant tool-call-history branch; `@huggingface/jinja` 0.5.9 has no `min`/`max` array filter, so every second round of an agent loop returned 400 `prompt build failed: Unknown ArrayValue filter: min`. This is why pi looked broken. Fix: `ChatTemplate.load` rewrites `[a, b]|min`/`|max` into conditional expressions. Verified byte-for-byte against the oracle venv's `apply_chat_template` for the agent round-trip case (`tests/minicpm5-template.test.ts`); Gemma template parity stays bit-exact.
-  2. **Streaming with tools declared buffered the entire response.** `buffered-text` mode returned "" for every token and dumped everything at flush — pi streams nothing until the end, and prose before a tool call was dropped entirely when a call parsed. Fix: ported the oracle's incremental behavior (`_QwenXMLToolCallStreamParser` buffers only from the tool marker on): content streams live with a StopMatcher-style hold-back on `<tool_call>`/`<function` prefixes; only the markup is withheld; parse-failure falls back to releasing the raw text.
-  3. **Tool param values were JSON-coerced regardless of schema.** `<param name="path">2025</param>` became the number 2025. Oracle (`_decode_tool_parameter_value` + `_tool_parameter_schema`) keeps string-typed params as raw text. Ported; also made the `<param>` regex CDATA-safe (a `</param>` inside CDATA no longer truncates the value). Unit tests added.
-  4. **Sampling ignored the model's `generation_config.json`.** The server hardcoded temp 0.7 / no top-p; optiq serve injects the author-recommended sampling (`optiq/runtime/gen_config.py`) as defaults. Ported: `loadContext` reads `generation_config.json` (MiniCPM5: temp 0.9, top_p 0.95; Gemma: temp 1.0, top_k 64, top_p 0.95) and `toOptions` uses it when the request omits the field. Explicit request values still win. This was the likely "quality" gap on a 1B model.
-  - Verification: MiniCPM5 parity (bf16 + mixed-KV) still 100/100 bit-exact; minicpm5-tools, tool-call, chat-template, tools-template, parity (Gemma 12B), server-tools, and server suites all green. Live two-turn agent round-trip (tool call → tool result → final answer) confirmed working in-process.
-
-## 2026-06-16 — Segmented-backward LoRA training (PRs #9–10)
-
-Long-context LoRA training was OOMing: MiniCPM5 @4096 spiked to ~25.5 GB full
-backward because all activations had to stay live simultaneously.  The
-segmented-backward design threads the backward segment-by-segment so only one
-segment's activations are resident at a time.
-
-The key implementation decision was to drive the per-segment backward with
-`mlx_vjp` (a new `Vjp` binding in `autograd.ts`) rather than a surrogate
-`value_and_grad` over a reconstructed loss.  The surrogate path leaked roughly
-one activation buffer per segment per step because mlx `eval` does not detach;
-`mlx_vjp` is explicit about what it differentiates and stops the leak.
-Segment-boundary tensors are materialized as graph-free leaves via
-`fromBytesCopy` for the same reason.
-
-Phase A (MiniCPM5, PR #9) landed first: grads bit-exact vs the full backward
-(relNorm 0.000%), peak 10.91 → 3.29 GB @2048, no leak, trains end-to-end via
-`TrainConfig.segmentSize`.  The default training attention is `ops.sdpa`
-(correct gradients, one fused kernel); `MLX_BUN_TRAIN_ATTN=flash` is an
-opt-in for bit-exact grad comparison against the full backward only, because
-`ops.sdpa` has a pre-existing eager-vs-autograd asymmetry in bf16 (~6%) that
-is unrelated to the segmentation mechanism — the segmented path works
-correctly under either setting.
-
-Phase B (e4b / Gemma4, PR #10) was harder: e4b's KV-shared donor pattern
-means multiple sharer segments reference the same K/V tensors produced by a
-single producer segment, requiring cotangent accumulation across sharers before
-the producer vjp can run.  Implemented `SegmentedBackwardGemma4` with a
-two-boundary stream (per-layer-input + donor K/V) and a multi-output producer
-vjp `[h, donorK, donorV]` with accumulated `[dh, dKV.k, dKV.v]` cotangents.
-Grads are bit-exact for single-consumer donor reuse and 0.97% bf16-class for
-multi-consumer accumulation (confirmed the full backward also sums in bf16, so
-this is order-of-operations noise, not a logic bug).  e4b trains at 8 K context
-(~17.5 GB, segSize=2) where the full backward would OOM (~70 GB).
-
-A contiguity fix was also required: donor K/V are transposed views, so
-`detachLeaf` must row-major-copy them before `rawBytes` reads linearly.
-
-## 2026-06-16 — Qwen3.5 / MiniCPM5 reasoning-channel fix (PR #12)
-
-Two serving-layer bugs left reasoning-capable models unusable in chat:
-
-The first was a role-name mismatch.  pi-ai renames the system role to
-`developer` for reasoning models.  Our chat templates only accepted
-system/user/assistant/tool and returned 400.  The turn completed with
-`stopReason: "error"` without throwing, so the browser saw an empty turn with no
-error shown.  Fix: `normalizeMessages` maps developer→system (genuine OpenAI
-compat — OpenAI itself uses the developer role), and `mapEventToFrames` surfaces
-a `stopReason:"error"` turn as a visible error frame instead of silently
-discarding it.
-
-The second was reasoning leaking into content.  Qwen3.5 and MiniCPM5 templates
-prime an *open* `<think>` tag in the generation prompt, so the model's first
-token is the closing `</think>` — the opening tag never appears in the decoded
-stream.  `ThinkingTagSplitter` was waiting for the open tag before routing
-reasoning content into the OpenAI `reasoning_content` channel, so all of it
-leaked into `content` instead.  Fix: `promptEndsInOpenThink` detects this
-condition and seeds `ThinkingTagSplitter` via `startInThinking` so the splitter
-begins in the reasoning state.
-
-## 2026-06-16 — Adapters end-to-end (PR #13)
-
-The goal was to make LoRA adapter switching a first-class operation in both the
-web chat UI and the Pi CLI, without building a custom protocol — lean on Pi's
-`before_provider_request` hook instead.
-
-Server-side: `GET /v1/adapters/available` scans the two adapter stores
-(`~/.cache/mlx-bun-finetunes`, `~/.cache/mlx-bun/adapters`) and returns
-`{id, path, rank, scale, mounted}` for weight-bearing checkpoints (dataset-only
-dirs are skipped).  `lora.ts` gained `listAvailableAdapters` for the scan and
-base-model detection so the web selector can filter to compatible adapters only.
-
-Pi hook: `pi-web.ts` registers `pi.on("before_provider_request")` to inject the
-per-connection selected adapter into every outgoing provider payload using the
-existing inline-extension pattern.  A `set_adapter` WebSocket message sets the
-selection; default none leaves the payload unchanged so the base model runs.
-
-Web chat: an adapter dropdown was added next to the Thinking pill, populated
-from `/v1/adapters/available` on ready.  Selecting fires an idempotent `POST
-/v1/adapters` then a `set_adapter` WS message.
-
-CLI: `extensions/mlx-bun-adapter.ts` is a shipped Pi extension exposing
-`/adapter <id> | off | list` and the same hook.  Both UIs control adapters
-through Pi; no separate plumbing.
-
-## 2026-06-17 — First-run onboarding UX
-
-The previous startup story required knowing the right model ID, running a
-separate download command, and manually opening a browser.  The new path:
-`mlx-bun serve` (or bare `mlx-bun`) auto-downloads the starter if absent,
-starts the server, and opens the chat UI.  If a localhost tab is already open it
-focuses that tab rather than opening a duplicate (`--no-open` to skip).
-
-The web chat empty state was updated with mlx-bun-centric starter chips and a
-download-aware greeting.  A live background-download pill shows progress.  The
-system prompt briefs the model on mlx-bun and its own identity, with framing
-appropriate to MiniCPM5 being a fast starter while a larger model optionally
-loads in the background.
-
-`chat-template.ts` also tightened `supportsThinking` to require the `<think>`
-channel we actually split, so e4b / harmony-format models no longer leak raw
-reasoning markers into content for users who haven't configured a thinkingFormat.
-
-The runtime-isolation design doc (`docs/design/runtime-isolation.md`) was also
-written this session: inference running in-process on the Bun event loop is a
-known UI-lag footgun when the GPU is busy.  The doc proposes moving inference to
-a subprocess; the work is explicitly deferred (design, not started) — written
-now so the root-cause analysis is available cold.
-
-## 2026-06-17 — SigLIP vision sidecar for gemma-4 e4b
-
-Ported optiq's `vlm/gemma4` SigLIP encoder as `src/vision/siglip.ts`: a 16-layer
-vision transformer with clippable linears (trained clip bounds), manual-f32
-RMS norms on q/k/v, on-device 2D RoPE, fused SDPA at scale=1.0, and GeGLU →
-3×3 avg-pool → `MultimodalEmbedder` → `/embed_scale`.
-
-The tower selection is driven by `vision_config.model_type`: e2b/e4b get
-SigLIP, the 12B gets the existing encoder-free tower.  Lazy loading means
-text-only sessions never pay for it.  `gemma4.ts`'s `forwardEmbeddings` was
-extended to support per-layer-input models (e2b/e4b) — it previously threw for
-that path — threading zeroed image-token ids into the per-layer forward matching
-optiq's `where(text_mask, ids, 0)`.
-
-Parity: every mlx primitive is bit-exact vs the optiq oracle (verified
-model-free via `op-parity-{dump.py,check.ts}` — rms_norm, gelu, matmul, clip,
-cos, sin, full multidim RoPE, sdpa, pool).  The residual ~1% feature divergence
-is sub-bf16 full-graph composition order amplified by the encoder's scale=1.0
-peaked softmax (the topped-out softmax distribution is highly sensitive to small
-pre-softmax shifts in bf16).  The acceptance bar was exact spliced ids + greedy
-prefix + grounded output, which passes.  Driving the residual to zero would
-require matching optiq's exact op ordering across the full encoder; deferred as
-a TODO.
-
-## 2026-06-17 — Distribution: npm, bunx, Homebrew signed/notarized, direct download
-
-The question was how to ship a standalone binary that runs on a user's Mac
-without requiring Bun, Python, or anything else.  We settled on four parallel
-install paths rather than picking one.
-
-**npm / bunx**: `bunx mlx-bun` for users already in the Bun ecosystem.  A
-`publish-release.sh` script and `bun run publish` alias handle the npm side.
-Published as v0.0.4.
-
-**Homebrew**: `scripts/release-binary.sh` builds a standalone binary, signs it
-with a Developer ID (nested Mach-O first, then the executable with JIT
-entitlements from `packaging/entitlements.plist`), notarizes via `AC_PROFILE`, and
-produces a clean tarball + sha256 for the formula.
-`packaging/homebrew/mlx-bun.rb` is the formula source of truth (self-contained
-`libexec` bundle + `bin` symlink; Bun `realpath`s `execPath` so sibling dylibs
-resolve after relocation).  The tap lives at `joshuarossi/homebrew-tap`.
-`scripts/publish-release.sh` auto-syncs the formula sha256 on each release.
-One fix was required: `--disable-library-validation` in the entitlements so
-brew-relocated dylibs load without `CS_RESTRICT` blocking them.
-
-**Direct download**: the notarized tarball passes Gatekeeper even when
-downloaded via browser + Finder (quarantine worst case), so a stable versionless
-URL (`releases/latest/download/mlx-bun-arm64.tar.gz`) is published alongside the
-versioned asset and documented as a one-liner curl install.
-
-**Embedded library**: existing path, unchanged (`docs/reference/embedding.md`).