mlx-bun 0.0.10 → 0.0.11

package/docs/investigations/dspark-handoff.md

@@ -1,11 +1,176 @@
 # DSpark — handoff
 
-**State:** faithful DSpark (DFlash KV-injection + Markov + confidence) is **built
-and proven architecturally correct** (overfit τ=3.24, paper-range). It does not
-yet net a speedup on e4b — that's a data-scale + target-speed problem, not an
-architecture problem. Full design + measured numbers:
+**State (2026-07-06): the DSpark paper is CODE-COMPLETE and serve-integrated.**
+Architecture proven correct (overfit τ=3.24, paper-range); serve-integrated
+behind `--draft-model` (Phase 1 — the `DraftSource` seam is KV-borrowing-ready;
+sibling AssistantSource verified bit-lossless on real weights,
+`tests/spec-serve-assistant.test.ts`); and every remaining paper component
+landed in Phase 2 the same day: Alg-1 confidence-scheduled draft-length pruning
+(checkpoint-driven, zero change for uncalibrated checkpoints), STS calibration
+(§3.2.1, `calibration.ts` + `scripts/dspark-calibrate.ts`), the RNN sequential
+head (Eq 6, `--seq-head rnn`, init-equivalent to Markov), the tightened draft
+loop (on-device token chaining + deferred conf reads + `collectLogits:false`
+on serve — bit-identity pinned), and the `dspark` variant rename + central
+loader. Suites: smoke 21/21 · dspark tests 17/17 · adjacent server suites
+green. **What remains is exactly the GPU work below** — data scale + 12B
+retarget + train + calibrate + measure; e4b not netting a speedup is a
+data/target-speed problem, not architecture. Full design:
 [docs/design/dspark-speculative-decoding.md](../design/dspark-speculative-decoding.md).
 
+## PATH A (preferred, no training) — DeepSeek's published 12B drafter
+
+DeepSeek released a TRAINED drafter for our exact target:
+`deepseek-ai/dspark_gemma4_12b_block7` (6.86 GB bf16, γ=7; DeepSpec repo is
+the MIT reference impl + the oracle — see the "DeepSpec ground truth" section
+of the design doc). Once the deepspec-variant port lands:
+
+```sh
+# 1. download the trained drafter (~6.9 GB)
+mlx-bun get deepseek-ai/dspark_gemma4_12b_block7
+# 2. oracle gate: dump their reference trace (temp 0 = RNG-free deterministic)
+#    in a torch venv, then compare ours round-for-round (scripts staged)
+# 3. measure + serve (auto-detected via config.json architectures field)
+mlx-bun serve --model gemma-4-12B-it-OptiQ-4bit --draft-model <snapshot-of-dspark_gemma4_12b_block7>
+```
+
+### Oracle protocol (step 2, expanded)
+
+Two staged scripts implement the temp-0 deterministic trace protocol against
+DeepSpec's own reference implementation (github.com/deepseek-ai/DeepSpec, MIT).
+At temperature 0 their leaky-rejection verify degenerates to exact argmax
+token-match — the whole round trace is RNG-free and reproducible, so a
+plain round-for-round diff is a real bit-exact gate (same discipline as the
+D2 diffusion oracle, minus RNG parity entirely — see the design doc's
+"DeepSpec ground truth" section).
+
+```sh
+# a. dump the reference trace — needs its OWN torch venv (NOT the mlx-lm
+#    oracle venv at /Users/joshrossi/Code/mlx-lm/.venv, which has no
+#    torch/deepspec and shouldn't); see the script header for the exact
+#    venv-setup + pip install steps.
+.venv-deepspec/bin/python scripts/oracle-dspark-deepspec.py \
+    --target <snapshot-dir-of-google/gemma-4-12B-it> \
+    --drafter <snapshot-of-dspark_gemma4_12b_block7> \
+    --data prompts.jsonl --n 8 --max-new-tokens 128 \
+    --temperature 0 --confidence-threshold 0 \
+    --out goldens/dspark-deepspec/trace-thr0.jsonl
+
+# b. compare our port round-for-round
+bun scripts/dspark-deepspec-compare.ts \
+    --fixture goldens/dspark-deepspec/trace-thr0.jsonl \
+    --target gemma-4-12B-it-bf16 --drafter <snapshot-of-dspark_gemma4_12b_block7>
+```
+
+Run the pair twice — once at `--confidence-threshold 0` (no pruning), once at
+`0.5` — to gate both the base draft loop and the confidence-truncation path.
+
+Fixture location: `goldens/dspark-deepspec/*.jsonl` follows the house
+manifest convention (goldens/README.md) — these are machine-independent
+**JSON manifests** (prompts + token-id traces, no tensor blobs), so they are
+the **tracked** kind, not the `.bin` machine-specific kind. Regenerate by
+rerunning step (a); there is no `scripts/regen-*` wrapper for this family yet
+since the oracle run needs its own GPU-hosting torch venv, not the mlx-lm
+oracle venv this repo otherwise standardizes on.
+
+**The OptiQ-4bit caveat is load-bearing, not a footnote**: the fixture above
+is generated against the bf16 HF target. A `dspark-deepspec-compare.ts` run
+with `--target` pointing at our bf16 12B is the TRUE bit-exact gate. A run
+with `--target` pointing at the OptiQ-4bit-quantized 12B we actually serve is
+a **separate acceptance-rate measurement** — tapped hiddens differ
+numerically at 4-bit, so round-for-round divergence there is expected, not a
+bug; pass `--acceptance-only` on that arm so the script reports an aggregate
+accept-length reading instead of a PASS/FAIL assert.
+
+Caveat: trained against the bf16 HF target; our serving 12B is OptiQ-4bit —
+tapped hiddens differ numerically, so measure acceptance rather than assuming
+their 60–85%.
+
+**FIRST LIVE RUN (2026-07-07, loaded machine — directional only):** τ ≈ 2.8
+committed/target-forward (200 tok / 72 verify rounds; per-token acceptance
+26–33% — the predicted OptiQ-4bit degradation), output coherent, losslessness
+holding. **But wall-clock LOST ~3.4×** (spec 14.6 vs serial 49.8 agg tok/s;
+the 20 s bench TTFT is conc-4 queueing on the serial-forced spec lane, not
+prefill). The tax is the drafter itself. **The full step-by-step program for
+the next pass is
+[docs/design/dspark-serving-program.md](../design/dspark-serving-program.md)**
+(phases, gates, dependency graph; pickup at TurboQuant merge, only its
+Phase 5 waits for it). Lever summary:
+1. **Quantize the drafter** — the big one, and the ideal quantization target
+   PERIOD: drafter numerics only move ACCEPTANCE, never correctness
+   (losslessness is structural), so aggressive bpw is safe and the gate is a
+   single acceptance A/B. 6.9 GB bf16 → ~1.8 GB @4-bit kills both the
+   ~3 GB/round bandwidth tax (2 GB lm_head + 7×134 MB markov_w2 reads) and
+   the 14 GB two-model memory pressure on 24 GB. Uniform 4-bit (mlx-native)
+   first as the baseline; **TurboQuant (Phase 13), when it lands, competes
+   on acceptance-per-byte against that baseline** — the drafter is its
+   lowest-risk first customer. Enabler either way: quantized-weight support
+   in deepspec-module's forward (quantized_matmul, the house pattern).
+2. **Tighten deepspec draftBlock** — ~14 host syncs/round (7 argmax + 7
+   confidence reads); replay the on-device chaining + deferred-conf
+   tightening already done for our own module (threshold=0 needs NO conf
+   reads).
+3. **captureLayer in the GENERATED gemma forwards** — tapped verifies
+   currently fall back to the monolith (correct-but-unspecialized); teach
+   scripts/gen-model.ts to emit the tap so spec verifies keep the fast path.
+4. **γ sweep** — γ=7 at ~30% acceptance wastes drafts;
+   `--num-draft-tokens 2..3` may net better wall-clock free of any code.
+
+## PATH B — train our own module (custom targets / research)
+
+The payoff target is **12B** (27B is memory-infeasible to train on 24 GB; the
+pipeline stays dim-generic so 27B remains a future recipe). All three scripts
+take `--model` and (new, 2026-07-06) `--tap-layers` — the retarget is now a
+pure parameterization, no code edits. **`--tap-layers` MUST be identical across
+regen and train** (the shard feature dim is `m*H`, `m = tapLayers.length`).
+
+12B tap set: use **`5,17,29,41,46`** — DeepSeek's actual trained
+`target_layer_ids` for this model (their layer-output convention matches our
+tapLayers indexing; audited 2026-07-06). Our earlier `24,37,47,48` guess is
+superseded.
+
+```sh
+# 0. one-time: cache the 12B target + a prompt/topic corpus (thousands of
+#    on-distribution topics — the data-scale lever; 160 only reached per-pos ~0.17).
+mlx-bun get mlx-community/gemma-4-12B-it-OptiQ-4bit
+# (12B target may need the serve process stopped to free memory for regen.)
+
+# 1. regen multi-layer training shards from the 12B target's own generations
+bun scripts/dspark-regen-dflash.ts \
+  --model gemma-4-12B-it-OptiQ-4bit --tap-layers 5,17,29,41,46 \
+  --topics <thousands-of-topics.txt> --out data/dspark-12b --max-resp 320
+
+# 2. train the drafter against the 12B (warm-start survivable via --resume;
+#    GPU runs kept getting killed ~step 5000 pre-resume). Optional A/B:
+#    --seq-head rnn trains the Eq-6 RNN head instead of Markov (Eq 5).
+bun scripts/dspark-train-dflash.ts \
+  --model gemma-4-12B-it-OptiQ-4bit --tap-layers 5,17,29,41,46 \
+  --data data/dspark-12b --out ckpt/dspark-12b \
+  --iters 8000 --batch 8 [--seq-head rnn] [--ddraft 2560] [--resume ckpt/dspark-12b]
+
+# 3. STS-calibrate (§3.2.1): fit per-position confidence thresholds on real
+#    verify outcomes and stamp them into dspark.json — this ACTIVATES the
+#    Alg-1 confidence scheduler at decode (uncalibrated = fixed-γ, no change).
+bun scripts/dspark-calibrate.ts \
+  --model gemma-4-12B-it-OptiQ-4bit \
+  --drafter ckpt/dspark-12b --data <prompts.jsonl> [--target 0.5]
+
+# 4. measure live τ + tok/s vs vanilla 12B decode (clean machine — dirty
+#    numbers are garbage). Run BOTH pre- and post-calibration for the
+#    scheduler's own A/B (MLX_BUN_DSPARK_MINCONF=<c> = manual uniform knob).
+bun scripts/dspark-measure-dflash.ts \
+  --model gemma-4-12B-it-OptiQ-4bit \
+  --drafter ckpt/dspark-12b --data <prompts.jsonl>
+
+# 5. serve it (auto-detected as kind=dspark via dspark.json; γ pinned to cfg.gamma)
+mlx-bun serve --model gemma-4-12B-it-OptiQ-4bit --draft-model ckpt/dspark-12b
+```
+
+Decision gate (write it down, RESULTS.md only if clean-machine): does 12B live
+τ net a wall-clock win? If the draft loop dominates, do the loop-tightening
+(per-position host syncs + double 262K LM-head) first — see the open items in
+the design doc. Memory guard (`server.ts`) caps context to fit; a client
+sending huge `max_tokens` trips admission — lower it.
+
 ## What happened (short version)
 - Built v1 first as a single-vector shortcut — it dropped the paper's core KV
   injection and was never really DSpark. Chunk (τ≈1.26) and article (τ≈1.16)
@@ -31,20 +196,21 @@ architecture problem. Full design + measured numbers:
 - Training `--resume` (warm-start from checkpoint) — the GPU runs kept getting killed ~step 5000; resume survives that.
 
 ## Next (in priority order)
-1. **Retarget to a slow model (27B or 12b).** The drafter reads dims from the
-   model + tapLayers is config, so it ports — but needs regen+train on that
-   model. 27B on 32GB is memory-tight (17.75GB weights); may need the serve
-   process stopped to free the ~14GB for regen. This is where a real speedup lives.
-2. **Scale training data** — thousands of on-distribution generations (not 160)
-   to lift generalizing τ toward the overfit ~0.75.
-3. **Tighten the draft inference loop** — per-position host syncs + double 262K
-   LM-head make the draft heavy; needed for τ to translate to wall-clock.
-4. **Finish the paper:** RNN head (Eq 6), STS calibration (§3.2.1), hardware-aware
-   prefix scheduler (Alg 1 — single-user = confidence-scheduled draft-length pruning).
-5. **Rename** `dflash`→`dspark` (faithful module IS DSpark; v1 = legacy single-vector).
+1. **Retarget to 12B + scale data + train + calibrate + measure** — the GPU
+   recipe above is the complete remaining work. (27B stays a future recipe:
+   memory-infeasible to train on the 24 GB M4 Pro.)
+2. ~~Tighten the draft inference loop~~ **DONE 2026-07-06** (on-device token
+   chaining, deferred conf reads, `collectLogits:false`; bit-identity pinned).
+3. ~~Finish the paper~~ **DONE 2026-07-06**: RNN head (Eq 6, `--seq-head rnn`),
+   STS calibration (§3.2.1), Alg-1 confidence-scheduled draft-length pruning
+   (single-user form). ⚠ Eq 6 + §3.2.1 shapes are design-doc-faithful readings
+   (paper PDF absent) — verify against the paper when available.
+4. ~~Rename `dflash`→`dspark`~~ **DONE 2026-07-06** (canonical variant +
+   central loader `src/spec/dspark/loader.ts`; legacy stamps still load).
 
 ## Key files
-`src/spec/dspark/{module,data,generate}-dflash.ts`, `{loss,sample}.ts`;
+`src/spec/dspark/{module,data,generate}-dflash.ts`, `{loss,sample,calibration,loader}.ts`;
+`src/spec/{source,serve-loop,dflash-source,assistant-source}.ts` (the serve seam);
 `src/model/gemma4.ts` (hiddenTap), `gemma4-base.ts` (trim bypass);
 `scripts/dspark-{regen,train,measure}-dflash.ts`, `dspark-dflash-smoke.ts`.
 

package/docs/investigations/lab-build-journal.md

@@ -1,7 +1,7 @@
 # Build journal — mlx-bun Lab (web UI + native quantize/train/dataset + pi web chat)
 
 *Branch `web-ui-and-native-lab`, 2026-06-13/14. Visual summary:
-[archive/mlx-bun-lab-report.html](../../archive/mlx-bun-lab-report.html). Evidence
+[archive/mlx-bun-lab-report.html](../../docs/archive/mlx-bun-lab-report.html). Evidence
 artifact: `benchmarks/lab-verification.json` (regenerable, gitignored — produced by
 `scripts/verify-lab.ts`).*
 
@@ -22,7 +22,7 @@ page. Compute is **native Bun/MLX (no Python)** per Josh's decision.
 
 2. **Gate the riskiest unknown first.** Native LoRA needs autograd across the
    FFI boundary. Rather than discover mid-build that it's infeasible, the first
-   thing built was `spikes/phase-train-vag.ts`: a tiny LoRA-shaped loss
+   thing built was `lab/spikes/phase-train-vag.ts`: a tiny LoRA-shaped loss
    (`mean((x + (x@A)@B − y)²)`) differentiated by `mlx_value_and_grad` through a
    `bun:ffi` JSCallback closure, checked against central finite differences.
    **PASS (<1e-2), exactly 2 grads returned (base frozen).** Only then was the

package/docs/investigations/openwiki-evaluation.md

@@ -0,0 +1,249 @@
+# OpenWiki — evaluation & fit analysis
+
+**Date:** 2026-07-06
+**Author:** investigation (agent), worktree `investigate/openwiki-memory`
+**Subject:** [langchain-ai/openwiki](https://github.com/langchain-ai/openwiki) — "a CLI that writes and
+maintains agent documentation for your codebase, built specifically for agents to consume."
+**Question asked:** how (if at all) does OpenWiki fit inside our memory system ("The Dreaming"), and
+is it a good fit anywhere else in mlx-bun?
+
+---
+
+## TL;DR — four verdicts
+
+| # | Question | Verdict | One-liner |
+|---|----------|---------|-----------|
+| 1 | Adopt OpenWiki **as the memory engine**? | ❌ **No** | Architecturally the mirror-image of The Dreaming; would throw away the hard-won decomposition + gate design and drag LangChain into a Bun/MLX-only repo. |
+| 2 | Borrow OpenWiki **patterns** into memory? | 🟡 **Marginal** | We already independently arrived at its good ideas, usually in stronger form. One minor borrow (the `_plan.md` durable-plan artifact). |
+| 3 | Run OpenWiki **on mlx-bun the repo** (its own agent docs)? | ✅ **Yes, good fit** | It targets exactly our named failure mode — reference-doc drift — and runs as an external dev tool, not a vendored dep. |
+| 4 | Point OpenWiki **at our own OpenAI-compatible server**? | ✅ **Yes — the strategic find** | DeepAgents-over-local-mlx-bun is an on-brand, zero-cloud dogfood showcase *and* a hard agentic-tool-use conformance test for the server. |
+
+The headline: **OpenWiki is not a fit *inside* the memory pipeline, but it is a fit *around* mlx-bun** —
+as a doc tool for our own repo and, more interestingly, as a real LangChain agent to run *against* our
+server to prove the "drop-in, local, agentic" thesis.
+
+---
+
+## 1. What OpenWiki is (full rundown)
+
+A CLI (`npm install -g openwiki`) from LangChain, released **v0.0.1 on 2026-07-05** (i.e. one day old at
+time of writing; ~7.7k stars, but 42 open PRs / 48 issues — treat as brand-new and unstable). MIT
+licensed. TypeScript/JavaScript.
+
+**Purpose.** Generate and maintain a repo's documentation *for coding agents*, not for humans. The
+generated wiki is "structured markdown optimized for LLM context — headings, cross-references, and
+summaries designed for an agent to quickly find relevant context." Motivation from the launch post:
+*"Agents write better code when they understand the repo they're working in,"* and stuffing the whole
+repo into one `CLAUDE.md` wastes context in large repos.
+
+**Surface.**
+```
+openwiki --init            # pick provider + API key, then generate the wiki
+openwiki                   # interactive
+openwiki "<request>"       # interactive, seeded
+openwiki -p "<request>"    # one-shot, non-interactive
+openwiki --update          # refresh from repo changes since last run
+```
+- Writes an `openwiki/` directory of markdown pages.
+- Patches `AGENTS.md` / `CLAUDE.md` with a pointer to the wiki **and a "when to use it" note**.
+- Ships a **GitHub Action** and **GitLab CI** template that open a PR/MR when docs need updating.
+- Config in `~/.openwiki/.env`: provider, API key, model id, optional LangSmith tracing.
+- Providers: OpenRouter (default, an open model), Fireworks, Baseten, OpenAI, Anthropic, and
+  **OpenAI-compatible** via `OPENAI_COMPATIBLE_BASE_URL` (also `ANTHROPIC_BASE_URL`). ← load-bearing
+  for verdict 4.
+
+## 2. How OpenWiki works (architecture)
+
+Built on LangChain's **DeepAgents** + **LangGraph**. The construction is deliberately thin:
+
+```ts
+const agent = createDeepAgent({
+  model,
+  tools: [],                         // NO custom tools
+  checkpointer,                      // thread memory
+  backend: new LocalShellBackend({ /* vfs → repo root */ }),
+  systemPrompt: createSystemPrompt(command),
+});
+```
+
+- **No bespoke tools.** It hands a general coding agent a `LocalShellBackend`: a virtual filesystem
+  mapped to the repo root exposing `ls / read_file / write_file / edit_file / glob / grep` plus a
+  sandboxed `execute` (120 s timeout, 100 KB output cap). All capability comes from the shell backend.
+- **All the IP is in the system prompt + the loop.** The prompt encodes:
+  - **Discovery → plan.** Before writing, the agent writes a temporary `openwiki/_plan.md` listing
+    *intended pages, source evidence per page, and remaining questions.*
+  - **Granularity rules.** ≤~10 primary source files → a `quickstart.md` + at most 1–2 supporting
+    pages. *"Do not create a directory unless it represents a real documentation area."*
+  - **One canonical page per concept.** *"Keep each concept in one canonical page… keep the detailed
+    explanation in the canonical page and make other mentions brief or link-only."* Inline source-file
+    references so a reader can verify.
+  - **Surgical, diff-budgeted updates.** On `--update` it *"checks which commits landed since the last
+    run, uses git diffs to understand what changed, then updates the wiki."* Soft budget: *"if fewer
+    than about 5 source files changed, update at most 1–2 wiki pages… Updates may be a no-op."*
+- **Change detection** by content snapshot (`createOpenWikiContentSnapshot`); persists run metadata
+  only when the wiki actually changed.
+- Streaming LangGraph invocation with a checkpointer keyed by `thread_id` (interactive Q&A over the
+  wiki + codebase reuses the thread).
+
+**Design bet:** a *strong single model* + a *good prompt* + a *free-roaming agent* with raw shell
+tools. Trust the model to hold the repo in its head and write files directly.
+
+## 3. The Dreaming, in one screen (for contrast)
+
+Our memory system ("The Dreaming", `src/memory/*`, ~12 k LoC, running end-to-end on real data):
+
+- **Corpus:** the user's conversation history (pointer-DB of `messages` → `chunks` as
+  `(conv,start,end)` ranges), not a code tree.
+- **Engine:** ONE local model (`gemma-4-e4b-it-OptiQ-4bit`) + per-stage LoRAs, loaded once. No cloud.
+- **Pipeline:** `SEGMENT → EXTRACT → ROUTE → SECTION-ROUTE → PATCH → NORMALIZE → LINK → WIKIFY →
+  RECONCILE → COMMIT`, every stage the *smallest atomic task* (binary yes/no preferred).
+- **Output:** entity-centric wiki — articles are *things*, with infoboxes, wikilinks, categories.
+- **Invariants enforced by code, not the model:** *"LoRAs propose, gates dispose"* — ≥70% prose floor,
+  every citation survives, weak output → NO-OP, deterministic footnote bijection + wikilink
+  canonicalization, one git commit per run.
+- **Single writer:** *"Chat agents read memory; `mlx-bun memory synthesize` is the only writer."* Reads
+  go through 7 read-only `memory_*` tools + a bundled skill.
+- **Self-healing:** chronological walk; latest statement wins; AI errors silently overwritten.
+
+**Design bet:** the exact opposite of OpenWiki — a *weak local model* + *heavy decomposition* +
+*deterministic scaffolding*. Assume the model **cannot** hold an article in its head or be trusted to
+write files freely, and engineer around that.
+
+## 4. Head-to-head: same shape, opposite philosophy
+
+Both are *"corpus → agentic synthesis → LLM-navigable markdown wiki → agent consumes it, kept fresh
+incrementally."* That surface similarity is why the question is worth asking. But under the hood they
+are mirror images:
+
+| Axis | OpenWiki | The Dreaming |
+|------|----------|--------------|
+| Corpus | Code repository | Personal conversation history |
+| Model | Strong cloud model (default OpenRouter) | Weak local e4b + LoRAs, no cloud |
+| Capacity model | Big context — model holds the repo | *Capacity by decomposition* — can't hold an article |
+| Harness | Thin (shell tools + one prompt) | Thick (10-stage DAG, ledgers, gates) |
+| Writes | Agent writes files freely | Single writer, gated, git-committed |
+| Dedup | Prompt rule ("one canonical page") | Deterministic entity name-match routing |
+| Update trigger | `git diff` since last commit | Chronological chunk cursor / new sessions |
+| Self-healing | Re-edit page on diff | Chronological latest-value reconcile |
+| Determinism | Trusts the model | Code enforces invariants |
+| Deps | LangChain + DeepAgents + LangGraph | Bun-native, MLX-only, minimal |
+
+Pithily: **OpenWiki = smart model, dumb harness. The Dreaming = dumb model, smart harness.** They solve
+the same *shape* of problem from opposite ends of the model-capability axis.
+
+## 5. The four fit verdicts, argued
+
+### Verdict 1 — OpenWiki as the memory engine: ❌ No
+
+- **Architectural inversion.** The Dreaming's entire thesis is that a local 4-bit e4b *cannot* do
+  OpenWiki's free-roaming, hold-it-in-context, write-files-directly loop — which is *why* the
+  decomposition + gate architecture exists. Adopting OpenWiki means discarding the exact design that
+  makes local synthesis work.
+- **Contract violation.** OpenWiki's agent writes files freely; The Dreaming has a single gated writer
+  with a git-commit-per-run audit trail and NO-OP-on-weak-output. These are incompatible write models.
+- **Corpus mismatch.** OpenWiki reads a code tree via shell/grep; The Dreaming reads a pointer-DB of
+  conversation chunks with chronological self-healing. Different input, different invariants.
+- **Identity/deps.** Pulling LangChain + LangGraph into a repo whose stated identity is Bun-native,
+  MLX-only, minimal-dep, private (see the `mlx-bun scope & framing` and `drop-in replacement` notes)
+  is a non-starter as a runtime dependency.
+- **Maturity.** v0.0.1, one day old. Nothing load-bearing should sit on it yet.
+
+### Verdict 2 — Borrow OpenWiki's patterns: 🟡 Marginal
+
+We have *convergently* arrived at most of OpenWiki's good ideas, usually stronger:
+
+| OpenWiki idea | Our equivalent | Who's ahead |
+|---------------|----------------|-------------|
+| `_plan.md` before writing | CREATE flow: sub-cluster → outline → draft | ~tie; their durable, reviewable *plan artifact* is a nice touch |
+| Soft diff budget, updates may be no-op | Idempotency ledger + conservative gate + NO-OP | **us** (ledger is stronger than a prompt heuristic) |
+| One canonical page (prompt rule) | Deterministic entity name-match routing | **us** (mechanism > instruction) |
+| Patch `AGENTS.md`/`CLAUDE.md` with pointer | 7 read-only `memory_*` tools + bundled skill | **us** (tools > prose pointer) |
+| git-diff-driven refresh | chronological chunk cursor | different corpus; both valid |
+
+**Only genuinely fresh borrow:** emit a durable, auditable **plan artifact** (their `_plan.md`) in the
+CREATE flow, so a synthesis run's *intended* article/section changes are reviewable in the git diff
+alongside the result. Low effort, small upside. Not worth a dedicated work item; fold in opportunistically.
+
+### Verdict 3 — Run OpenWiki on mlx-bun the repo: ✅ Good fit
+
+This is where OpenWiki was literally built to help, and mlx-bun is close to a canonical target:
+
+- **It attacks our named failure mode.** `CLAUDE.md` calls reference-doc drift *"the observed failure
+  mode"* (the 2026-07-03 sweep found undocumented flags, dead version pins). The doc-map even carries a
+  manual chore: *"keep these lists in sync with `ls docs/…`."* OpenWiki's diff-driven refresh + CI-PR is
+  exactly this job.
+- **Additive, not a replacement.** It would generate a *derived, agent-facing structural index of the
+  code* — it does **not** replace the curated, opinionated human docs (`PLAN.md` is "the engineering
+  contract"; `STATUS.md`, design docs). Think: an auto-maintained `openwiki/` map of `src/` that points
+  back into the hand-written design docs.
+- **Nice synergy with the vault.** The memory vault already symlinks mlx-bun docs into
+  `~/.mlx-bun/wiki/Reference/` (read-only). An auto-maintained repo wiki would flow straight into that
+  Reference surface — the personal vault gets a fresher code map for free.
+- **Runs as an external dev tool**, a global npm CLI in CI — *not* a vendored dependency. No LangChain
+  contamination of the shipped codebase. This sidesteps the Verdict-1 dependency objection entirely.
+
+**Caveat:** the one tension is "cloud API on a local/private repo." Verdict 4 dissolves it.
+
+### Verdict 4 — Point OpenWiki at our own OpenAI-compatible server: ✅ The strategic find
+
+OpenWiki speaks **OpenAI-compatible base URL**; mlx-bun *is* an OpenAI-compatible server (the whole
+"drop-in replacement for mlx-lm / serving speed is the user metric" thesis). Compose them:
+
+```
+OPENAI_COMPATIBLE_BASE_URL=http://localhost:<mlx-bun-port> \
+OPENAI_COMPATIBLE_API_KEY=… openwiki --init   # generate mlx-bun's own wiki, 100% local
+```
+
+Why this is the most interesting outcome of the investigation:
+
+1. **On-brand, zero-cloud.** Resolves the Verdict-3 tension: a real LangChain agent documents our repo
+   with *no* cloud call, on a Gemma running in mlx-bun. Directly demonstrates the `local-to-you` and
+   `install-to-chat` theses on an external, third-party agent.
+2. **A hard conformance test.** DeepAgents drives many tool calls + long contexts + streaming. Chat
+   parity is easy; *agentic tool-use conformance* is the bar that actually matters for "agents need the
+   server" (`serving speed is the user metric`). If OpenWiki runs unmodified end-to-end against our
+   server, that's a strong, concrete proof point for the README/website. If it *doesn't*, we've found a
+   real function-calling / prefill / KV gap under agentic load — also valuable.
+3. **Coverage/stress.** It exercises the server the way a coding agent does (glob/grep/read/write loops,
+   big prefills), complementing the batch/spec-decode perf work with a realistic agentic workload.
+
+**Caveat to measure, not assume:** DeepAgents presumes a *capable* model — the very assumption The
+Dreaming rejects for local e4b. A 4-bit e4b may drive the free-roaming loop poorly and produce a
+mediocre wiki. Mitigations: point it at a larger local model (the 12B parity target) via the same
+server, and/or judge output quality explicitly. Either way the *conformance* result (does the loop run?)
+is decoupled from the *quality* result (is the wiki good?), and both are worth knowing.
+
+## 6. Recommendation — what to actually do
+
+1. **Do not** put OpenWiki inside the memory pipeline. The Dreaming is more mature for its constraints
+   and philosophically opposite. (Verdicts 1 & 2.)
+2. **Spike Verdict 4 first — it's the highest-information, lowest-cost move.** Point OpenWiki at a
+   running mlx-bun server (Josh runs the server; no session starts it) and try `openwiki --init` on a
+   small repo, then on mlx-bun itself. Outcome is binary-useful: either a showcase demo of
+   "third-party LangChain agent runs locally on mlx-bun," or a concrete agentic-tool-use bug list for
+   the server. Bench it under the standard preflight if any perf number gets quoted
+   (`dirty-machine-numbers-are-garbage`).
+3. **If the spike is clean,** consider OpenWiki as an *external CI doc tool* for the repo (Verdict 3):
+   an auto-maintained `openwiki/` structural map that feeds the vault's `Reference/` surface. Keep it
+   clearly subordinate to the hand-written `PLAN.md`/design docs.
+4. **Opportunistically** add a durable `_plan.md`-style plan artifact to the memory CREATE flow for
+   reviewability (Verdict 2). Not a standalone work item.
+
+## 7. Risks & unknowns
+
+- OpenWiki is **v0.0.1, ~1 day old**, 42 open PRs / 48 issues — API and behavior will churn. Pin a
+  commit if used in CI.
+- **Local-model quality** driving DeepAgents is unproven (contradicts our own capacity-by-decomposition
+  finding). Measure; don't assume the wiki is good just because the loop runs.
+- **DeepAgents ⇄ our server function-calling compatibility** is the actual thing under test in Verdict
+  4 — tool-call formatting, streaming, and long-prefill behavior are where it could break.
+- Do **not** treat any OpenWiki-generated wiki as a source of truth over the curated docs; it's a
+  derived index.
+
+## Sources
+
+- [langchain-ai/openwiki](https://github.com/langchain-ai/openwiki) — repo, README, `src/agent/*`
+- [LangChain blog — Introducing OpenWiki](https://www.langchain.com/blog/introducing-openwiki-an-open-source-agent-for-repo-documentation)
+- Internal: `docs/design/memory-system.md`, `memory-synthesis.md`, `memory-inference-path.md`,
+  `write-pipeline-entity.md`, `the-dreaming-master-plan.md`, `the-dreaming-handoff.md`,
+  `docs/reference/memory.md`; `src/memory/*` (~12 k LoC).

package/docs/planning/IDEAS.md

@@ -53,3 +53,17 @@ persistent memory of *you*; mlx-bun is the local, private model runtime.
 Combined: a model that runs entirely on your machine **and** is continuously
 grounded in your own accumulated context — local in both senses, and yours in a
 way no hosted frontier model can be.
+
+
+## Library/app split (idea only — NOT planned, Josh 2026-07-05)
+
+Two pulls: "one executable, everything you want to do with local AI" (the
+product's charm) vs "some people just want a JS ML library — do they need
+the rest?" The runtime-isolation work (2026-07-05) drew the exact boundary
+either future needs: the engine child = the GPU stuff (src/model, src/mlx,
+caches, scheduler, generate); the parent = the app (serve/UI/registry/
+jobs/proxy). If a split ever happens it is a PACKAGING decision, not a
+refactor — e.g. npm subpath exports (mlx-bun/model vs the full CLI bundle)
+so library users import only the core. Library usage is unaffected by
+isolation today (in-process generate(), no server involved). Revisit only
+if Josh decides; both directions stay open from the current structure.

package/docs/planning/PRODUCT_ROADMAP.md

@@ -171,7 +171,6 @@ Each profile should eventually carry:
   kv: "mixed",
   memoryBudgetBytes: "...",
   compiledDecode: true,
-  perfKernel: false,
   expectedDecodeTps: 30,
   expectedTtftMs: 100,
   label: "Recommended for this Mac",
@@ -309,8 +308,8 @@ to text-only mode when no image is present, so the chat UI gains image support
 with no startup cost. Features are within ~1% rel-RMSE of the optiq oracle;
 every MLX primitive (rms_norm, gelu, matmul, SDPA, RoPE, pooling) is bit-exact.
 The residual is sub-bf16 floating-point accumulation across the deep encoder,
-not a porting gap. L1/L2/L3 paths all work; vision falls back to the monolith
-path on L1 and L2.
+not a porting gap. The L1 and L2 paths both work; vision falls back to the
+monolith path on L1 and L2.
 
 ### Adapter web selector and CLI /v1/adapters (shipped)