mlx-bun 0.2.0 → 0.3.0

package/src/vision/qwen3vl-tower.ts

@@ -115,9 +115,42 @@ export class Qwen3VLVisionTower {
     return names;
   }
 
+  /** Checkpoint-generation naming for the tower. Pre-5.8 artifacts store
+   *  `vision_tower.*`; the transformers-5.8 export stores `model.visual.*`
+   *  (mlx-lm's text-only qwen3_5 drops BOTH prefixes in `Model.sanitize`, so
+   *  the mapping between them is ours). Verified 2026-09-01 across
+   *  Qwen3.8-27B-tqalloc-norot vs the staged pre-5.8 artifact: 331/333
+   *  tensors byte-identical under the rename, patch_embed.proj.weight
+   *  identical under the layout permutation below, and merger.linear_fc2
+   *  differs only because the staged artifact is rotation-folded. */
+  static #sourceName(canonical: string, prefix: string): string {
+    return prefix + canonical.slice("vision_tower.".length);
+  }
+
+  /** HF stores the Conv3d patch embed as (out, in, kT, kH, kW); MLX (and this
+   *  tower) want (out, kT, kH, kW, in). Proven a pure permutation on the
+   *  artifacts above — transpose(0,2,3,4,1) of the 5.8 tensor is bit-equal to
+   *  the pre-5.8 one. */
+  static #fixPatchEmbed(w: Map<string, MlxArray>): void {
+    const key = "vision_tower.patch_embed.proj.weight";
+    const a = w.get(key);
+    if (!a || a.shape.length !== 5) return;
+    if (a.shape[4] === 3) return; // already MLX layout
+    const t = ops.transposeAxes(a, [0, 2, 3, 4, 1]);
+    const c = ops.contiguous(t);
+    t.dispose();
+    a.dispose();
+    w.set(key, c);
+  }
+
   /** Load one safetensors file's map and move `wanted` tensors into `out`
-   *  (missing names are skipped; the map is always freed). */
-  static #takeFromFile(path: string, wanted: string[], out: Map<string, MlxArray>): void {
+   *  under their CANONICAL (`vision_tower.*`) names; `source` maps each
+   *  canonical name to the stored one. Missing names are skipped; the map is
+   *  always freed. */
+  static #takeFromFile(
+    path: string, wanted: string[], out: Map<string, MlxArray>,
+    source: (canonical: string) => string = (n) => n,
+  ): void {
     const arrMap = new BigUint64Array([C.mlx_map_string_to_array_new()]);
     const metaMap = new BigUint64Array([C.mlx_map_string_to_string_new()]);
     const arrMapPtr = ptr(arrMap);
@@ -136,7 +169,7 @@ export class Qwen3VLVisionTower {
         if (out.has(name)) continue;
         const slot = new BigUint64Array([C.mlx_array_new()]);
         const slotPtr = ptr(slot);
-        if (C.mlx_map_string_to_array_get(slotPtr, handle, ptr(cstr(name))) !== 0) {
+        if (C.mlx_map_string_to_array_get(slotPtr, handle, ptr(cstr(source(name)))) !== 0) {
           C.mlx_array_free(read.u64(slotPtr, 0));
           continue;
         }
@@ -156,28 +189,37 @@ export class Qwen3VLVisionTower {
         // OptiQ-convention sidecar (their artifacts + ours pre-2026-08-18).
         Qwen3VLVisionTower.#takeFromFile(sidecar, names, weights);
       } else {
-        // In-main fallback: the bf16 vision_tower.* tensors live in the main
+        // In-main fallback: the bf16 tower tensors live in the main
         // safetensors shards (the mlx-vlm convention — one copy serves both
-        // ecosystems; sidecar duplication retired 2026-08-18).
+        // ecosystems; sidecar duplication retired 2026-08-18). The 5.8-family
+        // export names them `model.visual.*` instead of `vision_tower.*`.
         const idxPath = `${modelDir}/model.safetensors.index.json`;
         let files: string[];
+        let prefixes = ["vision_tower.", "model.visual."];
         if (existsSync(idxPath)) {
           const idx = JSON.parse(readFileSync(idxPath, "utf8")) as
             { weight_map: Record<string, string> };
-          files = [...new Set(
-            names.map((n) => idx.weight_map[n]).filter((f): f is string => !!f),
-          )];
+          prefixes = prefixes.filter((p) =>
+            Qwen3VLVisionTower.#sourceName(names[0]!, p) in idx.weight_map);
+          files = [...new Set(prefixes.flatMap((p) => names
+            .map((n) => idx.weight_map[Qwen3VLVisionTower.#sourceName(n, p)])
+            .filter((f): f is string => !!f)))];
           if (files.length === 0)
-            throw new Error(`no vision_tower tensors in ${modelDir} (index has none)`);
+            throw new Error(`no vision tower tensors in ${modelDir} (index has none)`);
         } else {
           files = ["model.safetensors"];
         }
         for (const f of files)
-          Qwen3VLVisionTower.#takeFromFile(`${modelDir}/${f}`, names, weights);
+          for (const p of prefixes)
+            Qwen3VLVisionTower.#takeFromFile(
+              `${modelDir}/${f}`, names, weights,
+              (n) => Qwen3VLVisionTower.#sourceName(n, p),
+            );
       }
       for (const name of names)
         if (!weights.has(name))
           throw new Error(`qwen vision weights missing tensor ${name} (sidecar or in-main)`);
+      Qwen3VLVisionTower.#fixPatchEmbed(weights);
     } catch (e) {
       for (const [, a] of weights) a.dispose();
       throw e;

package/src/web/app.html

@@ -1216,7 +1216,7 @@
 <!-- PWA installability (plan §9 Phase 3, beat-matrix Axis 10): manifest +
      inline SVG icon (src/web/manifest.webmanifest, src/web/icon.svg — no
      binary PNGs, per the hygiene gate; some browsers won't render an SVG
-     app icon and that's an accepted tradeoff, see features-matrix.md).
+     app icon and that's an accepted tradeoff, see docs/reference/server-config.md).
      theme-color matches the app's --bg token so the OS chrome doesn't
      flash a mismatched color on launch. -->
 <link rel="manifest" href="/manifest.webmanifest">

package/src/web/app.js

@@ -1,7 +1,7 @@
 // GENERATED — do not edit by hand.
 // Source: src/web/src/*.ts (entrypoint main.ts). To regenerate:
 //   bun scripts/build-web.ts
-// tests/web-build.test.ts enforces that this file matches the source.
+// tests/using/web-build.test.ts enforces that this file matches the source.
 // src/web/src/api.ts
 async function api(path, opts) {
   const { body, ...rest } = opts || {};
@@ -2892,11 +2892,13 @@ function initMemoryPanel() {
   maybeShowConsentCard();
 }
 
+// src/contracts/pi.ts
+var APP_ROUTE_IDS = ["chat", "quantize", "finetune", "dataset", "status"];
+
 // src/web/src/ui-catalog.ts
-var ROUTE_IDS = ["chat", "quantize", "finetune", "dataset", "status"];
 var VIEW_IDS = ["memory-panel", "hub-panel", "settings", "adapters-panel"];
 function isRouteId(v) {
-  return ROUTE_IDS.includes(v);
+  return APP_ROUTE_IDS.includes(v);
 }
 function isViewId(v) {
   return VIEW_IDS.includes(v);

package/src/web/src/adapters-panel.ts

@@ -9,9 +9,9 @@
 // docs/reference/server-api.md), with compatible-graying and a why-not
 // tooltip. Actions: mount, select, unselect, and stack two compatible
 // adapters as "a+b" — resolveSpec/injectAdapter already support composite
-// ids end to end (proved in tests/pi-web.test.ts's stacking test; the
+// ids end to end (proved in tests/research/pi-web.test.ts's stacking test; the
 // shape-validated mount is proved against real weights in the
-// MLX_BUN_TEST_LORA=1-gated tests/lora.test.ts).
+// MLX_BUN_TEST_LORA=1-gated tests/parity/lora.test.ts).
 //
 // Single source of SELECTION state, not a single fetch: composer.ts's quick
 // <select> and this table each hit /v1/adapters(+/available) independently
@@ -158,7 +158,7 @@ export function renderAdapterRow(
 }
 
 /** Full table body: a stack-mode toggle + composed-spec bar (when picks
- *  exist), then one section of rows. Exported so tests/web-app.test.ts can
+ *  exist), then one section of rows. Exported so tests/using/web-app.test.ts can
  *  exercise esc() discipline without a live DOM/network. */
 export function renderAdaptersBodyHtml(state: AdaptersPanelState): string {
   if (!state.available.length) {

package/src/web/src/assistant.ts

@@ -1,3 +1,5 @@
+import type { UiSnapshotElement, UiSnapshot, WizardStep } from "../../contracts/pi";
+export type { UiSnapshotElement, UiSnapshot, WizardStep } from "../../contracts/pi";
 // GENERATED-ADJACENT source module — part of the src/web/src/* split (plan
 // §6.6 "the app-aware assistant", §9 Phase 3, beat matrix Axis 12). Built
 // into src/web/app.js by scripts/build-web.ts.
@@ -26,42 +28,6 @@
 
 import { getSpotlightTarget, isViewId, ROUTE_LABELS, type RouteId, type ViewId } from "./ui-catalog";
 
-/* ────────────────────────────────────────────────────────────────────
-   1. SEE — the structured DOM snapshot
-   ──────────────────────────────────────────────────────────────────── */
-
-export interface UiSnapshotElement {
-  ref: string;
-  tag: string;
-  label: string;
-  kind: "interactive" | "region";
-  role?: string;
-  selector: string;
-  spotlightId?: string;
-}
-
-export interface UiSnapshot {
-  route: string;
-  capturedAt: string;
-  elements: UiSnapshotElement[];
-}
-
-/** Process-state fields layered onto the snapshot (§6.6 "the snapshot
- *  carries process state, not just elements") — wizard step for the
- *  quantize/finetune/dataset wizards, when the current route has one.
- *  Derived by reading the DOM the step indicator already renders
- *  (markdown.ts's renderSteps into #q-steps/#f-steps/#d-steps + the
- *  [data-qstep]/[data-fstep]/[data-dstep] visibility toggle quantize.ts/
- *  finetune.ts/dataset.ts already do) rather than adding a callback hook to
- *  those three controllers — zero behavior change to files outside this
- *  wave's scope, and the DOM IS the source of truth those controllers
- *  already write to. */
-export interface WizardStep {
-  index: number;
-  count: number;
-  label: string;
-}
-
 const STEP_CONTAINER_BY_ROUTE: Partial<Record<RouteId, string>> = {
   quantize: "q-steps",
   finetune: "f-steps",

package/src/web/src/chat.ts

@@ -10,15 +10,15 @@
 // typed, checkable seams between these concerns).
 //
 // Typed WS contract (plan §9 Phase 2 item 2): ClientMessage/ServerMessage
-// and the history/session shapes are imported TYPE-ONLY from ../../pi-web
+// and the history/session shapes are imported TYPE-ONLY from ../../contracts/pi
 // so this module (and the whole bundle) contains zero server code — the
 // bundler errors on bun:ffi if a value import ever sneaks in here, which is
 // the intended guard (see scripts/build-web.ts).
 
 import type {
   ClientMessage, HistoryItem, ReadyGenDefaults, ServerMessage, SessionListItem,
-} from "../../pi-web";
-import type { Lane } from "../../serve/lane-registry";
+} from "../../contracts/pi";
+import type { Lane } from "../../contracts/pi";
 import {
   $, el, toast, currentRoute, closeDrawer,
   storedCodingToolsPreference, renderCodingToolsState, renderToolApprovals,
@@ -44,7 +44,7 @@ import { isRouteId } from "./ui-catalog";
 
 /* ────────────────────────────────────────────────────────────────────
    Chat-with-files RAG v1 — Sources panel (plan §9 Phase 3, beat matrix
-   Axis 5). Pure HTML builder so tests/web-app.test.ts can exercise the
+   Axis 5). Pure HTML builder so tests/using/web-app.test.ts can exercise the
    esc() discipline directly, same reasoning as renderAdapterOptionsHtml
    etc. in composer.ts.
    ──────────────────────────────────────────────────────────────────── */

package/src/web/src/composer.ts

@@ -10,8 +10,8 @@
 // the original single IIFE), but every WS send goes through a callback
 // passed in from chat.ts, which owns the actual WebSocket.
 
-import type { ReadyGenDefaults, SamplingOverrides } from "../../pi-web";
-import type { Lane } from "../../serve/lane-registry";
+import type { ReadyGenDefaults, SamplingOverrides } from "../../contracts/pi";
+import type { Lane } from "../../contracts/pi";
 import { api } from "./api";
 import type { ApiEnvelope } from "./protocol";
 import {
@@ -200,7 +200,7 @@ function escHtml(s: unknown): string {
 
 /** Pure: builds the <option> markup for the adapter <select> from the
  *  /v1/adapters/available list. Split out from refreshAdapters() (which
- *  does the fetch + DOM write) so tests/web-app.test.ts can exercise the
+ *  does the fetch + DOM write) so tests/using/web-app.test.ts can exercise the
  *  esc() discipline on this template directly without a DOM or network —
  *  every interpolated field (id, rank, path, base_model) must be escaped,
  *  since adapter ids/paths are user-controlled (on-disk directory names). */
@@ -719,7 +719,7 @@ export function renderLane(lane: Lane | undefined): void {
    already resolves, so the agent's memory tools pick it up naturally, same
    as in the vault's own prose). No vault -> files-only picker. Pure
    query-detection/insertion helpers below are unit-tested directly
-   (tests/web-app.test.ts); DOM wiring (initMentionPicker) owns the
+   (tests/using/web-app.test.ts); DOM wiring (initMentionPicker) owns the
    picker's open/close/keyboard-nav state.
    ──────────────────────────────────────────────────────────────────── */
 

package/src/web/src/hub.ts

@@ -119,7 +119,7 @@ function localRowHtml(m: HubLocalRow): string {
 }
 
 /** Pure render, exported for esc()-discipline + empty-state tests
- *  (tests/web-app.test.ts, mirroring renderModelPopBodyHtml's pattern). */
+ *  (tests/using/web-app.test.ts, mirroring renderModelPopBodyHtml's pattern). */
 export function renderHubLocalHtml(models: HubLocalRow[]): string {
   if (!models.length) {
     return '<div class="hub-empty">No models downloaded yet — search Hugging Face below to get one.</div>';

package/src/web/src/memory-panel.ts

@@ -394,7 +394,7 @@ export async function refreshSidebarEntry(): Promise<void> {
 // by a literal list rather than an import: this module must stay
 // server-code-free (bundler-enforced, see chat.ts's header comment), so it
 // can't import a value from src/memory/tools.ts even though the identifiers
-// are the same. tests/web-app.test.ts cross-checks this list against the
+// are the same. tests/using/web-app.test.ts cross-checks this list against the
 // real export so drift is caught at test time instead of silently.
 export const MEMORY_CHIP_TOOL_NAMES = [
   "memory_resolve", "memory_category", "memory_read", "memory_section",

package/src/web/src/model-picker.ts

@@ -85,7 +85,7 @@ function renderRow(m: LibraryRow): string {
 }
 
 /** Pure render of the popover body from a /library response. Exported for
- *  tests/web-app.test.ts's esc() discipline check (repo ids are
+ *  tests/using/web-app.test.ts's esc() discipline check (repo ids are
  *  user-controlled HF strings — the same class of interpolation hazard
  *  finding #15 flagged for the adapter dropdown). */
 export function renderModelPopBodyHtml(models: LibraryRow[]): string {

package/src/web/src/palette.ts

@@ -39,7 +39,7 @@ interface PaletteAction {
 }
 
 /** Pure: the static action list, independent of any live session data —
- *  independently testable (tests/web-app.test.ts asserts labels/ids without
+ *  independently testable (tests/using/web-app.test.ts asserts labels/ids without
  *  needing a DOM). Session rows and message-search hits are appended
  *  dynamically in refreshResults() below, not part of this list. */
 export function staticActions(): PaletteAction[] {

package/src/web/src/protocol.ts

@@ -1,47 +1,11 @@
-// Shared frontend-only protocol shapes that don't already live on the
-// server side as exported types. The WS contract itself (ClientMessage /
-// ServerMessage / HistoryItem / SessionListItem / ReadyGenDefaults) is
-// imported type-only from ../../pi-web — see chat.ts. This file only holds
-// shapes with no server-side export to anchor to (e.g. the SSE job-stream
-// events, which live as a doc-comment in app.html today, not a type).
-//
-// Pointer comment for the server side: src/web/src/protocol.ts mirrors the
-// SSE line protocol documented at the jobStream() call site (api.ts) —
-// keep the two adjacent if the job event shape changes server-side
-// (scripts/ that emit `data:` lines for /api/jobs/:id/stream).
-
-/** One line of the /api/jobs/:id/stream SSE protocol (JSON per `data:` line). */
-export type JobEvent =
-  | { type: "log"; line: string }
-  | {
-      type: "stage";
-      stage: string;
-      progress?: number;
-      message?: string;
-      output_dir?: string;
-      adapter_path?: string;
-      // Dataset-generation-specific row counts (present on the dataset
-      // builder's job stream only; absent/ignored for quantize/finetune).
-      n_train?: number;
-      n_valid?: number;
-    }
-  | {
-      type: "metric";
-      kind: "train" | "val";
-      step: number;
-      loss: number;
-      learning_rate?: number;
-      tokens_per_sec?: number;
-      progress?: number;
-      message?: string;
-    }
-  | { type: "done"; n_train?: number; n_valid?: number }
-  | { type: "failed"; error?: string };
+import type { JobEvent } from "../../contracts/jobs";
+export type { JobEvent } from "../../contracts/jobs";
 
 /** Handlers passed to jobStream(); each key is an optional callback for the
  *  matching JobEvent variant, plus an `error` callback for the EventSource's
  *  own onerror (transport failure, not a `failed` protocol event). */
 export interface JobStreamHandlers {
+  started?: (e: Extract<JobEvent, { type: "started" }>) => void;
   log?: (e: Extract<JobEvent, { type: "log" }>) => void;
   stage?: (e: Extract<JobEvent, { type: "stage" }>) => void;
   metric?: (e: Extract<JobEvent, { type: "metric" }>) => void;

package/src/web/src/sessions.ts

@@ -20,7 +20,7 @@
 // wires each rendered `.sess` row's click to `onOpen` below — this just
 // finds and clicks the right row instead of duplicating that send()).
 
-import type { SessionListItem } from "../../pi-web";
+import type { SessionListItem } from "../../contracts/pi";
 import { $, el, injectStyles } from "./shell";
 import { api } from "./api";
 

package/src/web/src/ui-catalog.ts

@@ -2,28 +2,14 @@
 // §7/§9 Phase 3, §6.6 "app-aware assistant"). Built into src/web/app.js by
 // scripts/build-web.ts.
 //
-// The frontend half of the app-aware assistant's route/spotlight catalog.
-// Mirrors PortfolioManager's ui-catalog.json pattern (client/src/lib/
-// ui-catalog.ts + server/src/agent/ui-catalog.ts, read together with
-// server/src/agent/portfolio-tools.ts as the reference implementation) but
-// inlined as a TS module (not a shared JSON file) since mlx-bun's server and
-// browser bundles are separate build outputs (scripts/build-web.ts vs bun's
-// own TS execution) with no shared-JSON-import convention today — pi-web.ts
-// mirrors ROUTE_IDS/SPOTLIGHT_TARGETS as plain string arrays for its own
-// server-side validation (navigate_app/spotlight_ui reject anything not in
-// that list BEFORE touching the browser) so route validity is checked at
-// both ends without a build-time shared asset.
-//
-// Keep this list's ROUTE_IDS in sync with shell.ts's ROUTES tuple (chat,
-// quantize, finetune, dataset, status) plus the Developer-only overlays that
-// aren't hash-routes (memory panel, hub panel, settings) — those are
-// `view`s, not `route`s (see UiContext.view below), reached by opening an
-// overlay rather than changing the URL hash.
+// Shared route IDs keep browser navigation and server validation in agreement.
+// Spotlight selectors and overlay IDs belong to the browser.
 
 /** A hash-routed page (shell.ts's Route union, minus "routes" — the DAG
  *  diagram tab isn't a useful assistant destination and is itself
  *  feature-detected/hidden when unavailable). */
-export const ROUTE_IDS = ["chat", "quantize", "finetune", "dataset", "status"] as const;
+import { APP_ROUTE_IDS as ROUTE_IDS } from "../../contracts/pi";
+export { ROUTE_IDS };
 export type RouteId = (typeof ROUTE_IDS)[number];
 
 /** A non-route overlay/panel the assistant can navigate to or spotlight

package/src/web-assets.ts

@@ -0,0 +1,47 @@
+// Embedded web app — the unified SPA (chat / quantize / finetune /
+// dataset / status). `with { type: "text" }` inlines the file in both
+// `bun run` and the compiled single binary. bun-types types *.html
+// imports as HTMLBundle (the html loader), but the text attribute makes
+// the runtime value a string — hence the double cast.
+import appHtml from "./web/app.html" with { type: "text" };
+import curveDesignerHtml from "./lab/curve/curve-designer.html" with { type: "text" };
+// Vendored, no-CDN static assets referenced by app.html (convention: any
+// self-contained JS/CSS too big to inline gets `with { type: "text" }`
+// imported here and served under /assets/<name>; see src/web/vendor/README
+// for how hljs.js was built). Add new vendored assets the same way.
+import hljsJs from "./web/vendor/hljs.js" with { type: "text" };
+import hljsCss from "./web/vendor/hljs-theme.css" with { type: "text" };
+// The frontend bundle (plan §7/§9 Phase 2 module split): GENERATED from
+// src/web/src/*.ts by `bun scripts/build-web.ts` — see that file's header
+// and tests/using/web-build.test.ts (the freshness gate). Same
+// with { type: "text" } + /assets/<name> pattern as the vendored assets
+// above; app.html's <script defer src="/assets/app.js"> loads it.
+import appJs from "./web/app.js" with { type: "text" };
+// PWA installability (plan §9 Phase 3, beat-matrix Axis 10): a manifest +
+// a single inline SVG icon (no binary PNGs — the hygiene gate forbids
+// tracked binary files; some browsers won't show an SVG app icon, which is
+// an accepted tradeoff, see docs/reference/server-config.md) + a shell-
+// only service worker. Same with { type: "text" } + /assets/<name>-shaped
+// pattern as the vendored assets above; see src/web/sw.js's header for why
+// it deliberately does NOT cache API/WS traffic.
+import manifestWebmanifest from "./web/manifest.webmanifest" with { type: "text" };
+import iconSvg from "./web/icon.svg" with { type: "text" };
+import swJs from "./web/sw.js" with { type: "text" };
+const APP_PAGE = appHtml as unknown as string;
+const HLJS_JS = hljsJs as unknown as string;
+const HLJS_CSS = hljsCss as unknown as string;
+const APP_JS = appJs as unknown as string;
+const MANIFEST_WEBMANIFEST = manifestWebmanifest as unknown as string;
+const ICON_SVG = iconSvg as unknown as string;
+const SW_JS = swJs as unknown as string;
+const CURVE_PAGE = curveDesignerHtml as unknown as string;
+export const STATIC_ROUTE_ASSETS = {
+  appPage: APP_PAGE,
+  appJs: APP_JS,
+  hljsJs: HLJS_JS,
+  hljsCss: HLJS_CSS,
+  manifest: MANIFEST_WEBMANIFEST,
+  iconSvg: ICON_SVG,
+  serviceWorker: SW_JS,
+  curvePage: CURVE_PAGE,
+};

package/src/weights.ts

@@ -59,12 +59,30 @@ const NATIVE_WEIGHTS: WeightsNativeBindings = {
     ),
 };
 
+/**
+ * Checkpoint-generation normalization, installed once at load.
+ *
+ * `names` maps the GRAPH's canonical tensor name onto the name the artifact
+ * actually stores; a canonical name absent from the map does not exist (the
+ * same way a reference `sanitize()` drops a tensor). `fixup` is an optional
+ * lazy value repair applied to the loaded array — return null to keep it.
+ *
+ * Weights only APPLIES a view; the rules belong to the architecture that owns
+ * the naming (see `qwen35WeightsView` in model/qwen3_5-checkpoint.ts).
+ */
+export interface WeightsView {
+  readonly names: ReadonlyMap<string, string>;
+  fixup?(canonical: string, arr: MlxArray): MlxArray | null;
+}
+
 export class Weights {
   readonly shards: ShardedSafetensors;
   /** shard filename → native mlx map handle (string → lazy array). */
   readonly #maps = new Map<string, bigint>();
+  /** Cached arrays, keyed by CANONICAL name (post-view). */
   readonly #arrays = new Map<string, MlxArray>();
   readonly #native: WeightsNativeBindings;
+  #view: WeightsView | null = null;
 
   private constructor(
     shards: ShardedSafetensors,
@@ -120,6 +138,19 @@ export class Weights {
     }
   }
 
+  /** Install the checkpoint normalization. Must precede the first tensor()
+   *  call: the array cache and every shard lookup below are keyed through it. */
+  setView(view: WeightsView): void {
+    if (this.#arrays.size > 0)
+      throw new Error("Weights.setView after tensors were materialized");
+    this.#view = view;
+  }
+
+  /** Canonical name → the stored name (identity when no view is installed). */
+  #source(name: string): string {
+    return this.#view ? this.#view.names.get(name) ?? name : name;
+  }
+
   /** Free one shard's native map AND every cached tensor from it, releasing
    *  all bytes materialized while consuming that shard. The shard transparently
    *  re-opens on the next tensor() touching it (header parse only — lazy).
@@ -130,7 +161,7 @@ export class Weights {
     const sf = this.shards.files.get(file);
     if (!sf) return;
     for (const [name, arr] of this.#arrays) {
-      if (this.shards.tensorToFile.get(name) === sf) {
+      if (this.shards.tensorToFile.get(this.#source(name)) === sf) {
         arr.dispose();
         this.#arrays.delete(name);
       }
@@ -144,29 +175,36 @@ export class Weights {
 
   /** The shard filename holding `name` (for releaseShard scheduling). */
   fileOf(name: string): string | undefined {
-    const sf = this.shards.tensorToFile.get(name);
+    const sf = this.shards.tensorToFile.get(this.#source(name));
     if (!sf) return undefined;
     for (const [file, cand] of this.shards.files) if (cand === sf) return file;
     return undefined;
   }
 
+  /** Canonical names — with a view installed, exactly the tensors the graph
+   *  can ask for (renamed, drops excluded). */
   get tensorNames(): string[] {
-    return this.shards.tensorNames;
+    return this.#view ? [...this.#view.names.keys()] : this.shards.tensorNames;
   }
 
   info(name: string): TensorInfo {
-    return this.shards.info(name);
+    return this.shards.info(this.#source(name));
   }
 
   has(name: string): boolean {
-    return this.shards.tensorToFile.has(name);
+    return this.#view
+      ? this.#view.names.has(name)
+      : this.shards.tensorToFile.has(name);
   }
 
-  /** Lazy mlx array for a tensor; cached per name. */
+  /** Lazy mlx array for a tensor; cached per canonical name. */
   tensor(name: string): MlxArray {
     let arr = this.#arrays.get(name);
     if (!arr) {
-      const sf = this.shards.tensorToFile.get(name);
+      if (this.#view && !this.#view.names.has(name))
+        throw new Error(`no tensor named ${name}`);
+      const source = this.#source(name);
+      const sf = this.shards.tensorToFile.get(source);
       if (!sf) throw new Error(`no tensor named ${name}`);
       let entry = [...this.#maps.entries()]
         .find(([file]) => this.shards.files.get(file) === sf);
@@ -179,9 +217,17 @@ export class Weights {
       const mapHandle = entry[1];
       const slot = new BigUint64Array([C.mlx_array_new()]);
       const slotPtr = ptr(slot);
-      if (C.mlx_map_string_to_array_get(slotPtr, mapHandle, ptr(cstr(name))) !== 0)
-        throw new Error(`tensor ${name} missing from native map`);
+      if (C.mlx_map_string_to_array_get(slotPtr, mapHandle, ptr(cstr(source))) !== 0)
+        throw new Error(`tensor ${source} missing from native map`);
       arr = new MlxArray(read.u64(slotPtr, 0));
+      // Value repair (γ−1 → γ, conv layout): the fixed array is a lazy graph
+      // node over the source, so the raw handle is released immediately — the
+      // node keeps its own reference to the underlying data.
+      const fixed = this.#view?.fixup?.(name, arr) ?? null;
+      if (fixed) {
+        arr.dispose();
+        arr = fixed;
+      }
       this.#arrays.set(name, arr);
     }
     return arr;