mlx-bun 0.5.0 → 1.0.0

package/docs/archive/planning/memory-docs-and-dag-plan.md

@@ -1,194 +0,0 @@
-# Memory docs organization + DAG-view refresh — review & plan
-
-Status: **proposal**, 2026-07-01. Read-only review; nothing here has been
-executed. Two mandates: (A) get the Dreaming doc set into an organized state,
-(B) assess and plan the refresh of the parity-tier DAG view. Josh's live,
-uncommitted edits (`dreaming-nightly-pipeline.md` + the two SUPERSEDED banners)
-are treated as the direction of record and untouched.
-
----
-
-## A. The Dreaming doc set
-
-### A.1 Inventory — role and verdict per doc
-
-| Doc | Role | State (verified 2026-07-01) | Verdict |
-|---|---|---|---|
-| `docs/design/dreaming-nightly-pipeline.md` (new, uncommitted) | **CANONICAL system design** — pipeline, fixed principles, decisions-overridden table, work plan | Current; self-declares supersession over master-plan / memory-synthesis / handoff | **Keep as the hub.** It's already the entry point by construction. |
-| `docs/design/the-dreaming-master-plan.md` | Execution spec (P0–P10 task DAG, port-source map, schemas) | Bannered PARTIALLY SUPERSEDED (Josh's edit). Carries no as-built state — a reader can't tell P0–P9 are DONE | Keep, banner is right. **Add a one-line as-built note** ("built through P9; live state in STATUS.md") so the task list reads as history+reference, not TODO. |
-| `docs/design/the-dreaming-handoff.md` | Session log / live handoff (2026-06-28) | **Stale as a handoff:** cursor 720 (now 900/2096 paused), "everything is uncommitted" (merged 2026-07-01), "wire through persistent server" (in-process gateway landed instead), batch default (now 1). Lessons §1–8 remain valuable | **Demote to historical.** Banner: "Session log 2026-06-28 — live state is STATUS.md § THE DREAMING; the numbered LEARNED/CORRECTED list remains load-bearing." Stop maintaining two live handoffs. |
-| `docs/design/memory-synthesis.md` | M1 design, 1st iteration (embeddings, section-route) | Bannered SUPERSEDED (Josh's edit) | Keep for history. No further action. |
-| `docs/design/bucketing-stage.md` | Classify-stage design (2026-06-26) | **No banner.** Core content (embeddings as candidate-narrower) is dead under "no embeddings anywhere"; the binary-question ladder survives inside the nightly BUCKET stage | **Needs a SUPERSEDED banner** (same shape as memory-synthesis's): dead = embedding narrower + silhouette; survives = capacity-by-decomposition, one-binary-question-at-a-time. |
-| `docs/design/write-pipeline-entity.md` | Entity-keyed routing design (2026-06-26); itself "supersedes bucket-centric routing" | **No banner.** Half-dead: pure entity ROUTE (no bucket layer) is replaced by BUCKET→RESOLVE; the personal-notability checklist is dead. Survives: articles-are-THINGS, name/alias/category lookup, no-embeddings routing | **Needs a PARTIALLY SUPERSEDED banner** mapping survives/dead — otherwise its own "supersedes bucketing" claim inverts the actual chain for a newcomer. |
-| `docs/design/memory-system.md` | M0 substrate design (vault, read tools, CLI, scheduling, consent) | **Status header is FALSE**: "synthesize is currently a safe no-op stub", "stage modules throw if called" — the pipeline is built and has produced 677+ articles. Directly contradicts `docs/reference/memory.md`. The four-adapter table + "Next implementation steps" describe the abandoned M1 sketch | **Fix the header + scope it down.** Retitle scope to "M0 substrate: vault + read path (landed)"; delete or banner the "Synthesis pipeline design (M1/M2)" and "Next implementation steps" sections, pointing at dreaming-nightly-pipeline. The substrate half (storage layout, tools, skill, scheduling, consent) is still the best writeup of the read side — keep it. |
-| `docs/design/memory-inference-path.md` | Inference-path rework: design + measured verification | Accurate, self-bannered (BUILT + VERIFIED; batching measured a loss). It's really an investigation record | Fine as-is. Optional (low priority): move to `docs/archive/investigations/` where measured-experiment records live. |
-| `docs/reference/memory.md` | User-facing reference | Mostly current (synthesize description matches as-built stages; status truth fixed 2026-07-01). **But** the "Synthesis roadmap" section still tells the old four-named-LoRA / HF-adapter-pack story (memory-bucket/memory-synthesis/memory-editor LoRAs "distributed from Hugging Face") — not the plan of record (`memory-<stage>` convention, only `memory-chunk` exists, base+policy otherwise) | **Rewrite the roadmap section** to the as-built stage list + the `memory-<stage>` adapter convention; update stage names again when BUCKET/RESOLVE land. |
-| `STATUS.md` § THE DREAMING | Live state | Current and correct (batch default 1, third-person fix merged, import paused at cursor 900/2096, inference-path landed) | Keep as the ONLY live-state location. |
-
-### A.2 Contradictions / staleness found (the concrete list)
-
-1. **memory-system.md vs reference/memory.md** — "synthesize is a no-op stub"
-   vs "runs the full local synthesis DAG". Two tracked docs, opposite claims.
-   Worst offender; fix first.
-2. **Stage-name drift across four vocabularies:**
-   - memory-system: `ingest→chunk→cluster→synthesize→wikify→changelog`
-   - memory-synthesis: `CHUNK→FILTER→CLASSIFY→SYNTHESIZE→NORMALIZE→WIKIFY`
-   - as-built (`stages.ts`, handoff, reference): `segment→extract→route→create/patch→reconcile→link→wikify`
-   - canonical target (nightly pipeline): `SEGMENT→BUCKET→RESOLVE→SYNTHESIZE→gates→RECONCILE→LINK→NORMALIZE→EDITORIAL`
-   Rule going forward: **reference/memory.md speaks as-built; dreaming-nightly-pipeline speaks target**; every other doc is history and says so.
-3. **Unbannered middle links of the supersession chain**: the chain is
-   memory-synthesis → bucketing-stage → write-pipeline-entity → master-plan →
-   nightly-pipeline, and only the first and fourth links carry banners.
-   bucketing-stage still presents embeddings as production machinery;
-   write-pipeline-entity still presents the notability checklist.
-4. **Two live handoffs** (the-dreaming-handoff.md and STATUS.md § Dreaming)
-   with diverged facts (cursor 720 vs 900; uncommitted vs merged).
-5. **Four-adapter product story duplicated** (memory-system.md AND
-   reference/memory.md) vs the actual `memory-<stage>`-iff-exists convention.
-6. **CLAUDE.md doc map out of sync**: `dreaming-nightly-pipeline.md`,
-   `generic-model-support.md`, `mlx-lm-tool-parity-plan.md`,
-   `batching-v2-plan.md` are on disk but absent from the doc-map lists.
-
-### A.3 Proposed end-state
-
-No renames, no folder moves, no merges mid-flight (the import is paused
-mid-run and the nightly doc is uncommitted). Organization = **banners +
-one scope-fix + one hub table + reading order**, all cheap and link-stable:
-
-1. **Canonical entry point: `dreaming-nightly-pipeline.md`.** Add a short
-   "Doc family" table at its top covering ALL of: master-plan (task refs),
-   handoff (history), memory-synthesis / bucketing-stage /
-   write-pipeline-entity (history), memory-system (M0 substrate),
-   memory-inference-path (inference seam), reference/memory.md (user-facing),
-   STATUS.md (live state). Today it names only three of these.
-2. **Banner the two unbannered history docs** (bucketing-stage,
-   write-pipeline-entity) with survives/dead maps as in A.1.
-3. **Fix memory-system.md's header + amputate its M1 sketch** (A.1 row).
-4. **Demote the-dreaming-handoff.md to a dated session log** pointing at
-   STATUS.md; add the as-built one-liner to the master plan.
-5. **Rewrite reference/memory.md's roadmap section** to as-built.
-6. **Sync the CLAUDE.md doc map** (A.2 item 6).
-
-**Newcomer reading order** (to be stated in the nightly doc's family table):
-1. `docs/reference/memory.md` — what it is, how to use it
-2. `docs/design/dreaming-nightly-pipeline.md` — the canonical design +
-   decisions-overridden table
-3. `STATUS.md` § THE DREAMING — where it stands, what's next
-4. `docs/design/the-dreaming-master-plan.md` — per-task file/port/schema
-   references (respect the banner)
-5. History, only for archaeology: memory-synthesis → bucketing-stage →
-   write-pipeline-entity → the-dreaming-handoff → memory-inference-path
-
----
-
-## B. The DAG view (docs/dag/training-inference-map.html + parity-tier-dag.md)
-
-> **2026-07-05 annotation:** the Phase-1 deletion pass
-> ([unified-engine-frontier-plan.md §6](../design/unified-engine-frontier-plan.md))
-> deleted the perf-kernel, fused-decode, and fused-swiglu/geglu kernels and
-> removed `--l3` as a product mode (output-changing experiments are Lab items
-> now). The `perfKernelEnabled()` / `fusedDecodeSdpa` / `fusedSwiglu` route
-> predicates referenced in this section (and the map's n92/n95 branches) no
-> longer exist in the code; treat those mentions as the pre-deletion snapshot.
-
-### B.1 What exists today
-
-- **parity-tier-dag.md** — the framework doc. **Already refreshed 2026-07-01**:
-  it carries the corrected lever table (perf-kernel = L3/opt-in, off in bare
-  `--l2`), the f1bf5cc post-mortem, and the two-axes rule. Not stale.
-- **training-inference-map.html** — a hand-authored cytoscape control-flow map,
-  **MiniCPM5-1B only**, two tabs (inference ~150 nodes: generate loop → forward
-  → attention → sdpa dispatch → tiled/unfused kernels → KV bf16/quant →
-  sampler; training ~90 nodes: step loop → segmented/prefix → SFT/DPO/ORPO loss
-  heads incl. flash-CCE → AdamW → metrics). Every node carries a hardcoded
-  `file:line`. Branch edges carry the exact flag/predicate
-  (`perfKernelEnabled()`, `fusedSdpaSupported`, `MLX_BUN_TRAIN_ATTN`, …).
-- **Gap vs its own billing:** PLAN.md and parity-tier-dag.md call it
-  "tier-tagged" — it is **not**. Nodes are colored by *subsystem*; no node
-  carries an L1/L2/L3 tag. The tier story exists only in prose.
-
-### B.2 Staleness after 2026-07-01
-
-| Area | What changed | Map impact |
-|---|---|---|
-| L2 tier contract (commit `381382c`) | `TIERS.l2.perf → false`; bare `--l2` = stock unfused L=1 decode; perf kernel is L3/`--l3` | The `perfKernelEnabled()` branch (n92→n95) still exists, so the *structure* is right — but nothing in the map encodes tier presets, so the map can't show that `--l2` and `--l3` now take different sdpa routes. This is exactly the "for each config, how is it actually running" question the map is supposed to answer. |
-| Sampling processors (2026-07-01) | L1-faithful min_p / XTC / presence+frequency penalties / logit_bias landed end-to-end | Sampler subtree (n177–n194) shows only curve/HLG/topP/topK/temp — the new mlx-lm-parity processor chain is absent. |
-| Training `sft_scope` (d32fe32) | ORPO chosen-NLL default `full` (prompt+response token-mean CE), `response` = legacy | ORPO loss subtree (t46/t55) has no sft_scope branch. |
-| Tier-0 generic models (9bd9f1b) | `UniversalDenseModel`, 11 archs, factory ladder dedicated→generated→generic→reject | **Absent entirely.** The map is titled MiniCPM5-1B; no model-dispatch view exists at all (no gemma4 generated specializations, no Qwen3/3.5, no DiffusionGemma denoising route, no batching lane either). |
-| Line numbers | ~3 weeks of commits incl. today's uncommitted gemma4-base.ts / cli.ts edits | Every `file:line` is drift-suspect; they were the map's credibility feature. |
-
-### B.3 Refresh plan — three deliverables, ordered by value/effort
-
-**B3.1 Minimal manual patch to un-stale the current HTML (~0.5 day).**
-Keep it hand-authored, make it honest:
-1. Header banner: "hand-authored snapshot 2026-06-21, MiniCPM5-1B; line
-   numbers approximate; tier semantics in parity-tier-dag.md".
-2. **Add real tier tags** — a `tier` field per node + border color. Even
-   tagging just the dispatch nodes delivers the promised feature: `n87
-   ops.sdpa` (bf16) = L1 · `n83/n98` quantizedSdpa/tiled = L2 · `n92/n95`
-   perf-kernel/fusedDecodeSdpa = **L3 opt-in, off in bare `--l2` (381382c)**
-   · `n22/n27/n28` compiled-decode = tier-preserving (bit-exact) ·
-   flash-CCE/ORPO/segmented/prefix training nodes = L3.
-3. Sampler: insert one node before the temp/topP chain — "logits processors
-   (mlx-lm L1): repetition/presence/frequency · logit_bias · min_p · XTC".
-4. Training: add the `sft_scope full|response` branch at the ORPO chosen-NLL
-   node.
-5. Add a tiny third tab "model dispatch" (~10 nodes): the `factory.ts`
-   ladder — DiffusionGemma → MiniCPM5 → Qwen3.5 → Qwen3 → gemma4
-   generated/monolith → **UniversalDense (Tier-0, 11 archs, L1-gated)** →
-   reject.
-
-**B3.2 Runtime route explainer (recommended first "derive from code" step,
-~1 day).** Josh's ask is literally "for each model and config, how it is
-actually running" — the cheapest ground-truth answer is not static analysis
-but a CLI verb, e.g. `mlx-bun route <model> [--l1|--l2] [--kv-quant …]`,
-that:
-- runs `applyDecodeRoute()` (cli.ts:723 — the TIERS preset table is already a
-  machine-readable matrix), loads **config only** (no weights),
-- evaluates the actual exported predicates (`NO_FUSED_SDPA`,
-  `CompiledDecode.for` eligibility, kv-quant resolution, factory ladder
-  selection — the old perf-kernel/fused-decode/fused-swiglu predicates were
-  deleted 2026-07-05),
-- prints the resolved route as a tree/JSON: which model class, which sdpa
-  path, which kernels, which tier each hop sits in, and **which flag would
-  change each hop**.
-Correct by construction (it calls the same functions the server calls), zero
-drift, and it answers per-model × per-config today. The HTML map becomes the
-anatomy poster; this verb is the live X-ray.
-
-**B3.3 Derived DAG + CI parity gate (the two open PLAN boxes, ~2–4 days).**
-What "derive the DAG from code" concretely means here:
-- **Roots are curated, extraction is mechanical.** A bun generator script
-  (ts-morph / TS compiler API) walks from a small fixed root list —
-  `generate()`, `createModel()`, the trainer step, `sampleStep`, each model's
-  `quantizedSdpa`/attention dispatch — and records: every branch on a
-  `process.env.MLX_BUN_*` read or an exported `*Enabled()`/`*Supported()`
-  call, plus call edges between the roots' subgraphs. Nodes get
-  `{id, label, file, line}` extracted from the AST (line numbers can never
-  drift again). Output: `docs/dag/dag.json`, one graph per model class
-  (the factory ladder gives the model dimension).
-- **Tier tags live in a checked-in sidecar** (`docs/dag/tiers.json`:
-  `node → {tier, oracleTest}`) merged into the JSON at generation time. The
-  generator fails if a tagged node vanished (renames get caught).
-- **CI gate**: a workflow step asserts every **L1-tagged** node names an
-  `oracleTest` file that exists and passes (`bun test <file>`); an L1 node
-  without a passing bit-exact test fails CI or must be re-tagged no-oracle
-  (Lab-gated). This is
-  PLAN's "the oracle is the gate becomes a check" box — and it composes with
-  STATUS finding #4 (no CI at all): land the `tsc + bun test` gate first,
-  hang the L1-tag check off it.
-- **Rendering**: keep the existing cytoscape HTML shell; replace the
-  hardcoded `INFER`/`TRAIN` consts with the generated JSON (inlined by the
-  generator so the file stays a self-contained artifact).
-- **Deliberate non-goal**: fully deriving the fine-grained *op-level* nodes
-  (the tiled-sdpa online-softmax internals, AdamW math). That's 1–2 weeks of
-  static-analysis plumbing for content that changes rarely. Two-level design
-  instead: derived flag/route/dispatch graph (auto, CI-checked) + the
-  hand-authored op subgraphs kept as leaf expansions, refreshed manually.
-
-**Sequencing:** B3.1 now (un-stale the artifact) → B3.2 (the per-model/config
-truth Josh asked for) → B3.3 (kills the hand-authored map and closes the two
-PLAN checkboxes). The fourth PLAN box (rationalize the flag surface) falls out
-of B3.2+B3.3: once every flag maps to a route edge in the JSON, the
-always-on / knob / parity⇄opt classification in parity-tier-dag.md §"Why this
-matters" can be generated instead of argued.

package/docs/archive/planning/pi-integration-review.md

@@ -1,178 +0,0 @@
-# pi integration review — internal embeds + `harness pi` (2026-07-01)
-
-Read-only audit of the pi surface: `mlx-bun pi` (src/pi-terminal.ts, in-process
-InteractiveMode), the shared provider wiring (src/pi-provider.ts), the web
-embed (src/pi-web.ts), `mlx-bun harness pi` (src/harness-pi.ts), and the docs
-that describe them. Every claim below was verified in the current source
-(post-8ee691d, working tree of 2026-07-01); the localhost/loopback behavior was
-verified empirically with Bun on this machine.
-
-Stale-memory corrections first (priors that are NO LONGER true):
-- `harness pi` does **not** write `~/.pi/agent/models.json` — it generates a
-  self-contained extension at `~/.pi/agent/extensions/mlx-bun-provider.ts`
-  that calls `pi.registerProvider()` with live `/v1/models` discovery.
-- Tool-call parsing is **not** Gemma-only anymore: src/tool-call.ts also parses
-  OpenAI-JSON `<tool_call>`, Qwen `<function=name><parameter=…>`, and MiniCPM5
-  `<function name=…><param name=…>` from decoded text (buffered-text mode).
-- The old `by_bits`/bitsMap and double-BOS issues are fixed and stayed fixed.
-
-## Ranked fix list
-
-### 1. HIGH — Web chat advertises memory tools it filtered out
-`src/pi-web.ts:568` passes `tools: [...WELCOME_TOOLS]` (= `["read","web_search"]`,
-line 68) to `createAgentSessionFromServices`, but `src/pi-web.ts:534` appends
-`surface.memoryHint` to the system prompt and `surface.skillPaths` includes the
-bundled `memory` skill (surface built at :528 with memory auto-detect). pi
-treats the `tools` list as an allowlist, so when a vault exists the prompt and
-skill instruct the model to call `memory_resolve` / `memory_read` /
-`memory_section` — tools pi filtered out of the session. Every such call fails.
-The intent that they be reachable is visible at `src/pi-web.ts:57`
-(`READ_ONLY_TOOLS` already auto-allows `MEMORY_TOOL_NAMES`/`REFERENCE_TOOL_NAMES`,
-imported at :47). The terminal embed does this correctly
-(`src/pi-terminal.ts:157` uses `surface.tools`).
-**Fix (pi-web.ts:568):**
-`tools: [...WELCOME_TOOLS, ...(surface.memoryEnabled ? [...MEMORY_TOOL_NAMES, ...REFERENCE_TOOL_NAMES] : [])]`
-— or, if the 1B welcome assistant must stay two-tool, build the surface with
-`memory: "off"` so the hint and skill disappear too. Add a pi-web test either
-way (tests/pi-web.test.ts has no memory coverage today).
-
-### 2. HIGH — `harness pi` maps EVERY /v1/models row to id `"local"` (duplicate models)
-`/v1/models` now returns the served model FIRST **plus every other servable
-registry model** (src/server.ts:1479–1499). Both consumers still assume the old
-single-entry shape:
-- `src/harness-pi.ts:76–81` (`fetchServerModels`) maps all rows;
-- the generated extension (`renderPiExtension`, src/harness-pi.ts:116–125) and
-  the baked fallback (`modelEntry`, :140–151) register one pi model per row,
-  **all with id `local`** — N duplicate ids, N−1 of which name models the
-  single-model server is not actually serving.
-Side effects: `installPiExtension`'s `bakedModels` and the CLI's
-"server live · …" line print the whole registry; `src/cli.ts:1615`
-("reusing running server at … (…)") lists every downloaded model as if served.
-`tests/harness-pi.test.ts` stubs a single-row /v1/models, so this is untested.
-**Fix:** in `fetchServerModels`, keep only the served entry — the first row is
-the served model and is the only one carrying the capability extras
-(`context_window`, `reasoning`); e.g. `body.data?.[0]` (or filter rows that
-have `context_window`). Same filter inside the generated extension's live
-fetch. Update cli.ts:1615/1668 to label `models[0]` as served. Extend the
-harness test with a multi-row stub.
-
-### 3. HIGH — Tier-0 generics (and plain Qwen3 chat) get Gemma's token sentinels
-`toolStreamMode` (src/server.ts:1175–1183) returns `"gemma-sentinel"` for every
-model that isn't MiniCPM5/Qwen3.5 — including the new universal-dense generics
-(llama, qwen2, qwen3, gemma1/2, phi3, olmo2, glm4, granite, starcoder2,
-smollm3 — src/model/universal/archs.ts, served via src/model/factory.ts:42–45)
-and plain Qwen3. In that mode `ToolAwareStream.push` (src/server.ts:500–509)
-unconditionally interprets token ids 48/49/100/101 as tool/channel sentinels.
-Those ids are Gemma-4 special tokens (src/tool-call.ts:9–23); on any other
-tokenizer they're ordinary low-id vocab entries, so a generic model emitting
-one silently reroutes all subsequent output into a phantom tool segment or
-"reasoning". It also means generics never reach `parseGeneratedToolCalls`
-(buffered-text), so tool calling is broken for them — and pi always sends
-tools, and `mlx-bun pi -q <generic>` is a supported path now.
-**Fix (src/server.ts:1180–1182):** make gemma-sentinel the *family-gated*
-branch, not the default:
-```ts
-if (ctx.model.config.modelType.startsWith("gemma4")) return "gemma-sentinel";
-return tools?.length ? "buffered-text" : "plain";
-```
-(`ctx.template.thinkingFormat === "gemma-channel"` is an alternative key, but
-DiffusionGemma forces it null while still being gemma-family, so prefer
-modelType.) Buffered-text already handles the OpenAI-JSON `<tool_call>` shape
-most generic templates emit; models whose format isn't covered fail soft
-(markup stays in content) instead of corrupting the stream.
-
-### 4. MEDIUM — vision capability never reaches the pi terminal or external pi
-`/v1/models` doesn't advertise vision (src/server.ts:1479–1485: only
-`context_window` + `reasoning`), `RunEmbeddedPiOptions` has no `vision` field
-and `src/cli.ts:1670` passes none, so `mlx-bun pi` on gemma-4-e4b — the
-*default* model, vision-capable — registers `input: ["text"]`
-(src/pi-provider.ts:100) and images are unusable in the TUI. The harness
-extension is hardcoded `input: ["text"]` too (src/harness-pi.ts:121, :146).
-Only pi-web wires it (src/pi-web.ts:491–495, from `ctx.vision || ctx.loadVision`
-via createServer). The `input` flag MUST match the real model (pi-ai
-content-parts vs string serialization — pi-provider.ts:44–49), so this needs
-the real signal, not a default.
-**Fix:** add `vision: !!(ctx.vision || ctx.loadVision)` to the served entry in
-/v1/models; carry it through `ServerModel`/`fetchServerModels`,
-`renderPiExtension`/`modelEntry` (`input: m.vision ? ["text","image"] : ["text"]`),
-`RunEmbeddedPiOptions`, and the cli `pi` case.
-
-### 5. MEDIUM — harness extension drifted from buildPiProvider on compat flags
-The internal provider sets `compat: { supportsDeveloperRole: false, … }`
-(src/pi-provider.ts:89–92); the generated extension sets only `thinkingFormat`
-for reasoning models (src/harness-pi.ts:120, :145). Currently masked because
-the server remaps `developer` → `system` (src/server.ts:743–760), but the two
-paths are documented as "kept aligned" (pi-provider.ts:20–22, harness-pi.ts
-header) and have drifted. **Fix:** emit the same
-`supportsDeveloperRole: false` block in `renderPiExtension`/`modelEntry`.
-
-### 6. MEDIUM — `memory_status` tells the built-in agent synthesis doesn't exist
-`src/memory/tools.ts:571–572` hardcodes
-`"last synthesis: not available yet (M1 synthesis is stubbed)"` and
-`"synthesis: M1 stub (manual/nightly writes are not implemented yet)"`.
-Synthesis is live: `mlx-bun memory synthesize` runs the full DAG
-(src/cli.ts:2508ff) and the nightly launchd job runs it
-(src/memory/schedule.ts:66–72). The pi session will confidently tell the user
-the feature doesn't exist. **Fix:** drop the stub lines; report real state
-(e.g. last synthesis run from the synthesis DB / vault git log, and
-"run: mlx-bun memory synthesize").
-
-### 7. MEDIUM — docs/reference/memory.md contradicts itself
-Line 9: "Synthesis is scaffolded but still a no-op M1 stub" vs line 41
-("**`memory synthesize` writes to your vault.** It runs the full local
-synthesis DAG …") and line 77 ("Synthesis is live today"). Fix line 9 (and the
-line-53 "last-synthesis placeholder" wording once #6 lands).
-
-### 8. LOW — server-api.md pi section omits `harness pi`
-docs/reference/server-api.md:462–477 documents only the manual
-`~/.pi/agent/models.json` route (which also bakes a concrete model id — the
-staleness problem the `local` id exists to solve). Add: the supported
-one-command path is `mlx-bun harness pi` (extension + live discovery +
-`--remove` undo), manual models.json as the fallback.
-
-### 9. LOW — three base-URL spellings for one loopback server
-pi-web uses `http://127.0.0.1:${port}/v1` (src/pi-web.ts:487); the cli `pi`
-probe/provider uses `http://localhost:${port}/v1` (src/cli.ts:1610, also the
-serve preflight at :1215); harness `DEFAULT_BASE_URL` is
-`http://localhost:8080/v1` (src/harness-pi.ts:25). Functionally coherent today
-— verified empirically: Bun's fetch to `localhost` reaches both a
-127.0.0.1-bound and a ::1-bound server — and the port sweep from 8ee691d is
-clean (no live `8090` outside historical artifacts). But the harness extension
-runs under the *user's pi* (node/jiti, not Bun), so standardize on
-`127.0.0.1` (the actual default bind) everywhere to be resolver-proof.
-
-### 10. LOW — `mlx-bun pi` arg edges (flag-strip itself is clean)
-Verified complete: `OURS_VAL`/`OURS_BOOL` (src/cli.ts:1575–1582) cover every
-flag read by `serverRuntimeFlags`/`applyDecodeRoute`/`mountStartupAdapter`/
-`resolveModelAuto` (cross-checked flag-by-flag); `opt()` only supports
-space-separated values repo-wide so there's no `--flag=value` bypass; the
-"ignoring …" notice on server reuse works; `harness pi` passes nothing through
-to pi (no leak path). Two edges remain:
-- `parsePiArgs` (src/pi-terminal.ts:237–242) drops an unknown flag but keeps
-  its **value** as message text: `mlx-bun pi --resume abc123` starts a chat
-  with the message "abc123". Either swallow the next token for unknown
-  `--flags` or warn that the flag was ignored.
-- `RunEmbeddedPiOptions.verbose` (src/pi-terminal.ts:97) is never settable —
-  parsePiArgs doesn't recognize `--verbose`. Wire it or delete it.
-
-## Verified-good (no action)
-- **Compat flags per model**: `buildPiProvider` derives `reasoning` →
-  `thinkingFormat: "qwen-chat-template"` from `ctx.template.supportsThinking`,
-  which is detected generically from the template source (`enable_thinking` +
-  `<think>`/`<|channel>`, src/chat-template.ts:143–159) — covers Gemma,
-  MiniCPM5, Qwen3.5, and Tier-0 generics with think-tag templates alike; the
-  server honors `chat_template_kwargs.enable_thinking` and `reasoning_effort`
-  with one precedence function (src/server.ts:1101–1108).
-- **Wire contract**: pi's OpenAI `tool_calls` shape is produced for both the
-  sentinel and buffered-text parsers (src/server.ts:548–575, 1916–1923,
-  1989–2003), `finish_reason: "tool_calls"` included; `developer` role remapped.
-- **Isolation**: both embeds use in-memory auth/registry (no ~/.pi cross-talk),
-  own agent dirs (`~/.mlx-bun/pi`, `~/.mlx-bun/pi-sessions`), `noExtensions/
-  noSkills/noPromptTemplates/noThemes`, curated skills only.
-- **Server ownership**: `pi`-started servers are `owner: "pi-session"` and the
-  reuse path warns when attaching to another session's server (cli.ts:1624–1631).
-- **Memory read tools vs current vault code**: all imports
-  (vault/query/article/schedule) exist and match; terminal surface exposes them
-  correctly; FIND→READ contract intact. Only the status text (#6) is stale.
-- **contextWindow fallbacks**: missing `max_position_embeddings` degrades to
-  32768 at every consumer (`?? 32768` / `?? DEFAULT_CONTEXT_WINDOW`).

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

@@ -1,57 +0,0 @@
-# mlx-bun v0.0.10 — batching parity, SSD KV cache, sharper serving
-
-## Highlights
-
-**Concurrent serving now matches the fastest MLX batching servers.** With
-`--batch 4`, aggregate throughput at 4 parallel requests is at parity with
-(or ahead of) oMLX on every shared model we benchmarked on an M1 Max —
-MiniCPM5-1B 349 vs 339 tok/s, gemma-4-e4b within 3%, Qwen3.5-4B within 1% —
-with 2–3× better time-to-first-token under load, and per-token SSE
-streaming (no burst batching of your tokens).
-
-- **Qwen3.5 joins the batch lane.** Hybrid gated-DeltaNet (SSM) caches grew
-  the dynamic-batching ops; the batched decode path is verified
-  token-for-token identical against mlx-lm's B=2 batched oracle.
-- **Sampler features batch too.** Repetition/presence/frequency penalties,
-  `logit_bias`, `min_p`, and XTC now run per-row inside the batch instead
-  of forcing requests onto the serial path. (Qwen3.5 ships a default
-  repetition penalty — before this fix it silently serialized every
-  request under `--batch N`.)
-
-**SSD cold tier for the prompt cache** (`--ssd-cache <dir>`). Long-context
-prefix KV now spills to disk on eviction, is snapshotted after requests
-settle, and **survives server restarts**: re-attaching a 13.7k-token
-coding-agent conversation went from a 12.1 s full re-prefill to a 0.24 s
-zero-copy mmap restore in our measurements — with 0% steady-state decode
-overhead (nothing runs on the token loop). Entries are keyed by model
-fingerprint + KV scheme + tokenizer hash + adapter namespace; corrupt or
-incompatible files self-quarantine; the tier is always safe to delete.
-Companion flags: `--ssd-cache-max <GB>` (default 32), `--ssd-cache-verify`.
-
-## Fixes
-
-- `serve`/`benchmark` now honor `--model <path-or-query>` as an explicit
-  override (it was previously accepted but ignored — auto-pick could
-  silently load a different model). A directory containing `config.json`
-  loads directly from that path.
-- The server stays responsive during long serial generations: `/stats`,
-  `/health`, and new connections previously stalled until the generation
-  finished (measured 2.5 s on a 512-token run); they now answer in tens of
-  milliseconds, with no measurable decode cost.
-
-## Internals
-
-- KV persistence format v2: all cache kinds round-trip (bf16, per-layer
-  quantized, sliding-window, quantized sliding-window, SSM), with
-  integrity hashes, invalidation metadata, and atomic writes.
-- Golden `.bin` parity fixtures are no longer tracked in git (they are
-  machine-specific and regenerable); JSON manifests remain.
-- New design docs: `docs/design/omlx-adoption-map.md` (feature adoption
-  scoreboard), `docs/design/batching-perf-path.md`,
-  `docs/design/ssd-kv-cold-tier.md`.
-
-Full details and measured numbers: STATUS.md and the design docs above.
-Credit where due: the SSD-tier and batching comparisons were driven by
-studying [oMLX](https://github.com/jundot/omlx) (Apache 2.0) — a strong
-project whose ideas we benchmarked and adapted where they made mlx-bun
-faster.