mlx-bun 0.5.0 → 1.0.0

package/src/spec/assistant-rows.ts

@@ -1,93 +0,0 @@
-import type { MlxArray } from "../mlx/array";
-import * as ops from "../mlx/ops";
-import { materializeCopy } from "../mlx/materialize";
-import { disposeResources, applyStateChanges } from "../engine/resources";
-import type { PreparedStateChange } from "../contracts/resources";
-import type { AssistantRowsTarget, DraftPrefillGroup, DraftRowGroup, DraftRowCheckpoint, GroupedDraftProvider } from "./source";
-import type { GemmaAssistantDrafter } from "./drafter";
-
-/** The assistant owns only its last true target hidden and coverage. Donor
- * attention stays with target storage; checkpoints contain no duplicate KV. */
-class AssistantRows implements DraftPrefillGroup, DraftRowGroup {
-  readonly prefillMode = "tail-split" as const;
-  readonly tapLayers: readonly number[] = [];
-  #hidden: MlxArray | null = null;
-  #processed: number[] = [];
-  constructor(readonly target: AssistantRowsTarget, readonly drafter: GemmaAssistantDrafter,
-    readonly namespace: string, checkpoints: readonly (DraftRowCheckpoint | null)[]) { this.append(checkpoints); }
-  get rowCount(): number { return this.#processed.length; }
-  append(checkpoints: readonly (DraftRowCheckpoint | null)[]): void {
-    if (checkpoints.length) applyStateChanges([() => this.prepareAppend(checkpoints)]);
-  }
-  prepareAppend(checkpoints: readonly (DraftRowCheckpoint | null)[]): PreparedStateChange {
-    const processed = [...this.#processed, ...checkpoints.map(checkpoint => checkpoint?.processedTokens ?? 0)];
-    const example = this.#hidden ?? checkpoints.find(checkpoint => checkpoint !== null)?.attachment.tensors[0];
-    const held: MlxArray[] = []; let hidden: MlxArray | null = null;
-    try {
-      for (const checkpoint of checkpoints) if (checkpoint && (checkpoint.attachment.schema !== "gemma-assistant-v1" ||
-        checkpoint.attachment.metadata.processedTokens !== checkpoint.processedTokens))
-        throw new Error("invalid assistant checkpoint alignment");
-      if (example) {
-        const zero = (rows: number) => { const value = ops.zeros([rows,1,this.target.hiddenSize],example.dtype); held.push(value); return value; };
-        hidden = ops.concatAxis([...(this.rowCount ? [this.#hidden ?? zero(this.rowCount)] : []),
-          ...checkpoints.map(checkpoint => checkpoint?.attachment.tensors[0] ?? zero(1))],0);
-      }
-    } finally { disposeResources(held); }
-    return { commit: () => { const old = this.#hidden; this.#hidden=hidden; hidden=old; this.#processed=processed; },
-      dispose: () => { hidden?.dispose(); hidden=null; } };
-  }
-  filterRows(keep: readonly number[]): void {
-    if (!keep.length) { this.dispose(); return; }
-    using indices = ops.fromInt32([...keep],[keep.length]);
-    const next = this.#hidden && keep.length ? ops.takeAxis(this.#hidden,indices,0) : null;
-    this.#hidden?.dispose(); this.#hidden=next; this.#processed=keep.map(row=>this.#processed[row]!);
-  }
-  prefill(tokens: MlxArray, context?: MlxArray): void {
-    const [B,N] = tokens.shape as [number,number];
-    using tail = context!.slice([0,N-1,0],[B,N,context!.shape[2]!]);
-    const hidden = materializeCopy(tail);
-    this.#hidden?.dispose(); this.#hidden=hidden; this.#processed=this.#processed.map(count=>count+N);
-  }
-  materialize(): void { this.#hidden?.eval(); }
-  capture(row: number): DraftRowCheckpoint {
-    const processedTokens=this.#processed[row]!;
-    const hidden=this.#hidden!.slice([row,0,0],[row+1,1,this.target.hiddenSize]);
-    return { processedTokens, attachment: { schema:"gemma-assistant-v1",metadata:{processedTokens},tensors:[hidden] } };
-  }
-  draft(pending: readonly number[], depth: number, _steps: readonly number[]): number[][] {
-    if (!depth) return pending.map(()=>[]);
-    const B=pending.length, owned: MlxArray[]=[];
-    const donors=this.target.readDonors();
-    let ids=ops.fromInt32([...pending],[B,1]), hidden=this.#hidden!;
-    const tokens: MlxArray[]=[];
-    try {
-      for(let step=0;step<depth;step++) {
-        using emb=this.target.embed(ids);
-        const positions=donors.positions.map(position=>position+step);
-        const common=positions.every(position=>position===positions[0]);
-        using offsets=common ? null : ops.fromInt32(positions,[B]);
-        const next=this.drafter.forwardRows(emb,hidden,donors,offsets ?? positions[0]!);
-        owned.push(next.nextHidden); tokens.push(next.tokens); hidden=next.nextHidden;
-        ids.dispose(); ids=ops.reshape(next.tokens,[B,1]);
-      }
-      using packed=ops.concatAxis(tokens,0);
-      const values=packed.toIntTokens();
-      return pending.map((_,row)=>Array.from({length:depth},(_,step)=>values[step*B+row]!));
-    } finally { ids.dispose(); donors.dispose(); disposeResources([...owned,...tokens]); }
-  }
-  commit(accepted: readonly number[], context: MlxArray): void {
-    using indices=ops.fromInt32([...accepted],[accepted.length,1,1]);
-    const hidden=ops.takeAlongAxis(context,indices,1);
-    this.#hidden?.dispose(); this.#hidden=hidden;
-    this.#processed=this.#processed.map((count,row)=>count+accepted[row]!+1);
-  }
-  dispose(): void { this.#hidden?.dispose(); this.#hidden=null; this.#processed=[]; }
-}
-
-export function assistantGroups(drafter: GemmaAssistantDrafter, namespace: string): GroupedDraftProvider {
-  return {
-    checkpointNamespace: () => namespace,
-    openPrefill: ({target,checkpoints}) => new AssistantRows(target.assistantRows!,drafter,namespace,checkpoints),
-    open: ({target,checkpoints}) => new AssistantRows(target.assistantRows!,drafter,namespace,checkpoints),
-  };
-}

package/src/spec/assistant-source.ts

@@ -1,126 +0,0 @@
-import * as ops from "../mlx/ops";
-import { artifactIdentity } from "../model/artifact-identity";
-import { assistantGroups } from "./assistant-rows";
-// AssistantSource — the optiq KV-borrowing Gemma "-assistant" drafter
-// (src/spec/drafter.ts) behind the serve-time DraftSource seam. L2 oracle:
-// optiq spec_generate. This is the SAME drafter the standalone specGenerate
-// loop (src/spec/generate.ts) drives; here it plugs into the shared
-// verify/accept executor (src/spec/serve-loop.ts) so it composes with grammar,
-// logits processors, admission accounting, and stats like any other source.
-//
-// KV-borrowing (why the seam carries a TargetView): the drafter has NO cache
-// of its own — each draft step reads the target's donor K/V (last sliding +
-// last full layer, in chronological order) and, for the block's first step,
-// the target's hidden at the anchor position. Both arrive through the seam:
-// donor views from `target.caches`, the anchor hidden from draft()'s
-// `anchorHidden` argument (borrowed — never disposed here). See
-// [[dspark-seam-kv-borrowing]].
-//
-// Drafting is GREEDY (the drafter's own argmax head), independent of the
-// request sampler — drafts are only proposals; the target's verify (which does
-// honor the sampler) decides every emitted token, so correctness holds at any
-// temperature and only the acceptance RATE moves. Matches specGenerate.
-
-import { readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
-import type { MlxArray } from "../mlx/array";
-import { GemmaAssistantDrafter } from "./drafter";
-import type { DraftProvider, DraftSource, TargetView, AssistantRowsTarget } from "./source";
-
-/** Sum of the drafter's on-disk safetensors — admission accounting only. */
-function safetensorsBytes(dir: string): number {
-  let total = 0;
-  for (const f of readdirSync(dir))
-    if (f.endsWith(".safetensors")) total += statSync(join(dir, f)).size;
-  return total;
-}
-
-export class AssistantProvider implements DraftProvider {
-  readonly id: string;
-  readonly weightsBytes: number;
-  readonly grouped: import("./source").GroupedDraftProvider;
-
-  private constructor(
-    private readonly drafter: GemmaAssistantDrafter,
-    id: string,
-    weightsBytes: number, namespace: string,
-  ) {
-    this.id = id;
-    this.weightsBytes = weightsBytes;
-    this.grouped = assistantGroups(drafter,namespace);
-  }
-
-  static async load(modelDir: string): Promise<AssistantProvider> {
-    const drafter = await GemmaAssistantDrafter.load(modelDir);
-    const id = modelDir.split("/").filter(Boolean).at(-1)!;
-    try {
-      const identity = await artifactIdentity(await Bun.file(`${modelDir}/config.json`).text(),
-        readdirSync(modelDir).filter(file => file.endsWith(".safetensors"))
-          .map(name => ({ name, path: join(modelDir, name) })));
-      return new AssistantProvider(drafter, id, safetensorsBytes(modelDir), `gemma-assistant-v1:${identity}`);
-    } catch (error) { drafter.dispose(); throw error; }
-  }
-
-  open(opts: Parameters<DraftProvider["open"]>[0]): DraftSource {
-    return new AssistantSource(this.drafter, opts.target);
-  }
-
-  dispose(): void {
-    this.drafter.dispose();
-  }
-}
-
-export class AssistantSource implements DraftSource {
-  readonly weightsBytes = 0; // provider-owned weights; per-request adds nothing
-  private readonly target: AssistantRowsTarget;
-
-  constructor(private readonly drafter: Pick<GemmaAssistantDrafter, "forwardRows">, target: TargetView) {
-    if (!target.assistantRows)
-      throw new Error("assistant drafter requires a Gemma4 target with donor views");
-    this.target = target.assistantRows;
-  }
-
-  /** No own cache to prime — the drafter reads the target's live state. */
-  prefill(_promptIds: number[], _ctxML?: MlxArray): void {}
-
-  /** Draft n tokens against the target's donor K/V, conditioning the first
-   *  step on the anchor (the last emitted token + its target hidden) and
-   *  chaining the drafter's own post-projected hiddens after that — exactly
-   *  specGenerate's 2a block. anchorHidden is borrowed; never disposed here. */
-  draft(feed: number[], n: number, _stepBase: number, anchorHidden?: MlxArray): number[] {
-    if (!anchorHidden) throw new Error("assistant drafter needs the target anchor hidden");
-    const shared = this.target.readDonors();
-    const position = shared.positions[0]!;
-    const drafts: number[] = [];
-    const ownedHiddens: MlxArray[] = [];
-    let dTok = feed[feed.length - 1]!; // the pending token (anchorHidden's token)
-    let dHid = anchorHidden; // borrowed for k=0
-    let emb: MlxArray | null = null; // hoisted so a mid-loop throw still frees it
-    try {
-      for (let k = 0; k < n; k++) {
-        using ids = ops.fromInt32([dTok], [1, 1]);
-        emb = this.target.embed(ids);
-        const step = this.drafter.forwardRows(emb, dHid, shared, position + k);
-        ownedHiddens.push(step.nextHidden);
-        let token: number;
-        try { token = ops.itemUint32(step.tokens); } finally { step.tokens.dispose(); }
-        emb.dispose();
-        emb = null;
-        drafts.push(token);
-        dTok = token;
-        dHid = step.nextHidden;
-      }
-    } finally {
-      emb?.dispose();
-      for (const a of ownedHiddens) a.dispose();
-      shared.dispose();
-    }
-    return drafts;
-  }
-
-  /** The serve loop already trims the target caches on rejection; the drafter
-   *  borrows them, so it has nothing of its own to roll back. */
-  commit(_n: number, _kAccept: number, _vCtxML?: MlxArray): void {}
-
-  dispose(): void {}
-}

package/src/spec/cache-identity.ts

@@ -1,22 +0,0 @@
-import type { GenerateOptions } from "../generate";
-
-/** Snapshot numerical configuration when the request is bound. Caller-owned
- * arrays must not change the graph or persistence identity after grouping. */
-export function captureSpeculativeOptions(options: GenerateOptions): GenerateOptions {
-  return { ...options,
-    ...(options.kvConfig ? { kvConfig: options.kvConfig.map(({ layerIdx, bits, groupSize }) =>
-      ({ layerIdx, bits, groupSize })).sort((a, b) => a.layerIdx - b.layerIdx) } : {}),
-    ...(options.turboQuant ? { turboQuant: { ...options.turboQuant } } : {}),
-  };
-}
-
-/** Existing namespaces remain byte-identical when no per-layer scheme is
- * supplied. Execution and persistence consume the same captured settings. */
-export function speculativePrefixNamespace(method: string | undefined, adapters: string | string[],
-  options: GenerateOptions): string {
-  return JSON.stringify({ method, adapters, kvBits: options.kvBits ?? null,
-    kvGroupSize: options.kvGroupSize ?? 64, quantizedKvStart: options.quantizedKvStart ?? null,
-    turboQuant: options.turboQuant ?? null,
-    ...(options.kvConfig?.length ? { kvConfig: options.kvConfig } : {}),
-  });
-}

package/src/spec/deepspec-rows.ts

@@ -1,29 +0,0 @@
-import { projectedDraftGroups } from "./projected-draft-rows";
-import type { GroupedDraftProvider, TargetView } from "./source";
-import type { DeepspecDrafter } from "./dspark/deepspec-module";
-
-/** Existing pairing requirements are checked once when the provider opens. */
-export function bindDeepspecTarget(target: TargetView, drafter: Pick<DeepspecDrafter, "cfg">): void {
-  if (!target.gemmaTaps) throw new Error("DeepSpec drafter requires a Gemma4 target");
-  const layers = drafter.cfg.num_target_layers;
-  if (target.gemmaTaps.layerCount !== layers) throw new Error(
-    `DeepSpec drafter was trained for a ${layers}-layer target; ` +
-    `this model has ${target.gemmaTaps.layerCount} layers — wrong (target, drafter) pairing`);
-}
-
-export function deepspecGroups(drafter: DeepspecDrafter, namespace: string): GroupedDraftProvider {
-  return projectedDraftGroups(namespace, target => {
-    bindDeepspecTarget(target, drafter);
-    return {
-      namespace, schema: "deepspec-context-v1",
-      layers: drafter.cfg.num_hidden_layers, tapLayers: drafter.tapLayers,
-      project(hidden, positions) {
-        using projected = drafter.projectContext(hidden);
-        return drafter.projectContextKVRows(projected, positions);
-      },
-      draft(context, pending, positions, depth) {
-        return drafter.draftRows(context, pending, positions).tokens.map(row => row.slice(0, depth));
-      },
-    };
-  });
-}

package/src/spec/deepspec-source.ts

@@ -1,145 +0,0 @@
-// DeepspecSource — DeepSeek's released DSpark drafter checkpoints
-// (Gemma4DSparkModel, e.g. deepseek-ai/dspark_gemma4_12b_block7) behind the
-// serve-time DraftSource seam. The reference implementation is DeepSpec
-// (github.com/deepseek-ai/DeepSpec, MIT); the module port with transcription
-// notes lives in src/spec/dspark/deepspec-module.ts. Oracle: DeepSpec's eval
-// at temperature 0 (RNG-free — verify degenerates to argmax token-match),
-// scripts/oracle/oracle-dspark-deepspec.py → dspark-deepspec-compare.ts (deleted 2026-08-23; git history).
-//
-// Seam mapping (why this fits without serve-loop changes): the reference
-// recycles target hidden states from each verify pass into the drafter's
-// growing context — exactly the tapped ctxML/vCtxML flow the seam carries:
-//   prefill(ids, ctxML)      → project the prompt's tapped hiddens into the
-//                              per-layer context K/V cache (their DynamicCache
-//                              of PROJECTED context rows, positions 0..Lp-1);
-//   draft(feed, n)           → one block forward vs the cache (anchor = feed
-//                              tail at position ctxLen); confidence truncation
-//                              may return 0..n tokens (ℓ=0 = plain step);
-//   commit(d, kAccept, vCtxML)→ project + append ONLY the accepted rows
-//                              [anchor + kAccept drafts] (their crop()
-//                              semantics: rejected rows never enter the
-//                              cache), positions ctxLen..ctxLen+kAccept.
-// Context rows are cached post-norm-post-rope — bit-equivalent to their
-// in-round concat (per-row RMSNorm/RoPE; argued in projectContextKV's doc).
-
-import { artifactIdentity } from "../model/artifact-identity";
-import { deepspecGroups, bindDeepspecTarget } from "./deepspec-rows";
-import { readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
-import type { MlxArray } from "../mlx/array";
-import * as ops from "../mlx/ops";
-import { DeepspecDrafter, type ContextKV } from "./dspark/deepspec-module";
-import type { DraftProvider, DraftSource, TargetView } from "./source";
-
-function safetensorsBytes(dir: string): number {
-  let total = 0;
-  for (const f of readdirSync(dir))
-    if (f.endsWith(".safetensors")) total += statSync(join(dir, f)).size;
-  return total;
-}
-
-export class DeepspecProvider implements DraftProvider {
-  readonly id: string;
-  readonly weightsBytes: number;
-  readonly grouped: import("./source").GroupedDraftProvider;
-  /** Trained block width (config block_size, e.g. 7) — the server pins
-   *  numDraftTokens to this. */
-  readonly gamma: number;
-
-  private constructor(private readonly drafter: DeepspecDrafter, id: string, weightsBytes: number, namespace: string) {
-    this.id = id;
-    this.weightsBytes = weightsBytes;
-    this.gamma = drafter.gamma;
-    this.grouped = deepspecGroups(drafter, namespace);
-  }
-
-  static async load(modelDir: string): Promise<DeepspecProvider> {
-    const drafter = await DeepspecDrafter.load(modelDir);
-    const id = modelDir.split("/").filter(Boolean).at(-1)!;
-    try {
-      const identity = await artifactIdentity(await Bun.file(`${modelDir}/config.json`).text(),
-        readdirSync(modelDir).filter(file => file.endsWith(".safetensors"))
-          .map(name => ({ name, path: join(modelDir, name) })));
-      return new DeepspecProvider(drafter, id, safetensorsBytes(modelDir), `deepspec-context-v1:${identity}`);
-    } catch (error) { drafter.dispose(); throw error; }
-  }
-
-  open(opts: Parameters<DraftProvider["open"]>[0]): DraftSource {
-    return new DeepspecSource(this.drafter, opts.target);
-  }
-
-  dispose(): void {
-    this.drafter.dispose(); // owned MlxArrays (transpose views + mmap'd weights)
-  }
-}
-
-export class DeepspecSource implements DraftSource {
-  readonly weightsBytes = 0; // provider-owned weights
-  readonly tapLayers: number[];
-  private ctxKV: ContextKV[] | null = null; // per-layer projected context rows
-  private ctxLen = 0; // context rows cached == the anchor's absolute position
-
-  constructor(private readonly drafter: Pick<DeepspecDrafter,
-    "cfg" | "tapLayers" | "projectContext" | "projectContextKV" | "draftBlock">, target: TargetView) {
-    bindDeepspecTarget(target, drafter);
-    this.tapLayers = drafter.tapLayers;
-  }
-
-  /** Project the prompt's tapped hiddens into the context cache (ownership of
-   *  ctxML transfers here). */
-  prefill(promptIds: number[], ctxML?: MlxArray): void {
-    if (!ctxML) throw new Error("DeepSpec drafter: prefill missing tapped context");
-    const Lp = ctxML.shape[1]!;
-    const projected = this.drafter.projectContext(ctxML);
-    ctxML.dispose();
-    const positions = Array.from({ length: Lp }, (_, i) => i);
-    this.ctxKV = this.drafter.projectContextKV(projected, positions);
-    projected.dispose();
-    this.ctxLen = Lp;
-  }
-
-  /** One block forward against the cached context. Confidence truncation may
-   *  return 0..n tokens (0 = skip drafting; the serve loop runs a plain
-   *  tapped step and commit still grows the context by the anchor row). */
-  draft(feed: number[], n: number, _stepBase: number, _anchorHidden?: MlxArray): number[] {
-    if (!this.ctxKV) throw new Error("DeepSpec drafter: draft before prefill");
-    const anchorTok = feed[feed.length - 1]!;
-    const block = this.drafter.draftBlock(this.ctxKV, anchorTok, this.ctxLen);
-    block.baseLogits.dispose(); // serve loop runs its own verify lm-head
-    // n < gamma near maxTokens: the block always drafts full γ; hand back
-    // only what the round may verify.
-    return block.tokens.length > n ? block.tokens.slice(0, n) : block.tokens;
-  }
-
-  /** Grow the context cache by the ACCEPTED rows of the verify window —
-   *  [anchor + kAccept drafts] from vCtxML [1,d+1,m*H] (ownership transfers
-   *  here); rejected rows never enter (reference crop() semantics). */
-  commit(_d: number, kAccept: number, vCtxML?: MlxArray): void {
-    if (!vCtxML) throw new Error("DeepSpec drafter: commit missing tapped verify context");
-    if (!this.ctxKV) throw new Error("DeepSpec drafter: commit before prefill");
-    const mH = vCtxML.shape[2]!;
-    const keep = kAccept + 1; // anchor + accepted drafts
-    const rows = vCtxML.slice([0, 0, 0], [1, keep, mH]);
-    vCtxML.dispose();
-    const projected = this.drafter.projectContext(rows);
-    rows.dispose();
-    const positions = Array.from({ length: keep }, (_, i) => this.ctxLen + i);
-    const newKV = this.drafter.projectContextKV(projected, positions);
-    projected.dispose();
-    for (let i = 0; i < this.ctxKV.length; i++) {
-      const old = this.ctxKV[i]!;
-      const add = newKV[i]!;
-      const k = ops.concatAxis([old.k, add.k], 2);
-      const v = ops.concatAxis([old.v, add.v], 2);
-      old.k.dispose(); old.v.dispose();
-      add.k.dispose(); add.v.dispose();
-      this.ctxKV[i] = { k, v };
-    }
-    this.ctxLen += keep;
-  }
-
-  dispose(): void {
-    if (this.ctxKV) for (const { k, v } of this.ctxKV) { k.dispose(); v.dispose(); }
-    this.ctxKV = null;
-  }
-}

package/src/spec/dflash-source.ts

@@ -1,149 +0,0 @@
-// DflashSource — DSpark (faithful DFlash + Markov + confidence,
-// src/spec/dspark/module-dflash.ts) behind the serve-time DraftSource seam.
-// L3 (KL/quality-gated). The DRAFT half of the standalone dflashGenerate loop
-// (src/spec/dspark/generate-dflash.ts) plugged into the shared verify/accept
-// executor (src/spec/serve-loop.ts).
-//
-// H_ctx (why the seam taps): DSpark drafts by attending to a GROWING
-// multi-layer context — the target's tapped hiddens over the accepted stream
-// (paper Eq 2-3). The seam declares `tapLayers`, so the serve loop taps the
-// target's prefill (→ seeds H_ctx here) and every verify forward (→ grown in
-// commit by the accepted window; rejected tips are never appended, mirroring
-// the target-cache trim). See [[dspark-seam-kv-borrowing]].
-//
-// v1 acceptance: the serve loop verifies with TOKEN-MATCH acceptance
-// (mlx-lm/optiq style — lossless at any temperature), NOT the paper's
-// distribution-level rejection-sampling verify. Greedy is identical; temp>0 is
-// still lossless but lower-acceptance. Drafting here is greedy (proposals; the
-// target verify decides). The richer rejection-sampling verify stays in the
-// standalone dflashGenerate for the measure script.
-
-import { artifactIdentity } from "../model/artifact-identity";
-import { projectedDraftGroups } from "./projected-draft-rows";
-import { readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
-import type { MlxArray } from "../mlx/array";
-import * as ops from "../mlx/ops";
-import type { DflashDrafter } from "./dspark/module-dflash";
-import { loadDsparkDrafter } from "./dspark/loader";
-import type { DraftProvider, DraftSource, TargetView, DraftProjection } from "./source";
-import { runtimeValue } from "../runtime-config";
-
-function safetensorsBytes(dir: string): number {
-  let total = 0;
-  for (const f of readdirSync(dir))
-    if (f.endsWith(".safetensors")) total += statSync(join(dir, f)).size;
-  return total;
-}
-
-export class DflashProvider implements DraftProvider {
-  readonly id: string;
-  readonly weightsBytes: number;
-  readonly grouped: import("./source").GroupedDraftProvider;
-  /** The trained block width — the server pins numDraftTokens to this so the
-   *  serve loop never asks for more positions than the block was trained for. */
-  readonly gamma: number;
-
-  private constructor(private readonly drafter: DflashDrafter, id: string, weightsBytes: number, namespace: string) {
-    this.id = id;
-    this.weightsBytes = weightsBytes;
-    this.gamma = drafter.cfg.gamma;
-    this.grouped = projectedDraftGroups(namespace, target => {
-      if (!target.gemmaTaps) throw new Error("DSpark drafter requires a Gemma4 target");
-      const projection = target.gemmaTaps.projection;
-      const minConf = runtimeValue("MLX_BUN_DSPARK_MINCONF");
-      return {
-        namespace, schema: "dflash-context-v1",
-        layers: drafter.cfg.nLayers, tapLayers: drafter.cfg.tapLayers,
-        project: hidden => drafter.projectContextRows(hidden),
-        draft(context, pending, _positions, depth) {
-          return drafter.forwardRows(projection, null, pending, depth, {
-            collectLogits: false, collectConfidence: false,
-            thresholds: drafter.cfg.sts?.thresholds,
-            ...(minConf ? { minConf: Number(minConf) } : {}),
-          }, context).tokens;
-        },
-      };
-    });
-  }
-
-  static async load(modelDir: string): Promise<DflashProvider> {
-    const drafter = loadDsparkDrafter(modelDir); // variant dispatch (dspark|legacy dflash)
-    const id = modelDir.split("/").filter(Boolean).at(-1)!;
-    try {
-      const identity = await artifactIdentity(await Bun.file(`${modelDir}/dspark.json`).text(),
-        readdirSync(modelDir).filter(file => file.endsWith(".safetensors"))
-          .map(name => ({ name, path: join(modelDir, name) })));
-      return new DflashProvider(drafter, id, safetensorsBytes(modelDir), `dflash-context-v1:${identity}`);
-    } catch (error) { drafter.dispose(); throw error; }
-  }
-
-  open(opts: Parameters<DraftProvider["open"]>[0]): DraftSource {
-    return new DflashSource(this.drafter, opts.target);
-  }
-
-  dispose(): void {
-    // Provider-owned weights are released when the mounted draft is closed.
-    this.drafter.dispose();
-  }
-}
-
-export class DflashSource implements DraftSource {
-  readonly weightsBytes = 0; // provider-owned weights
-  readonly tapLayers: number[];
-  private readonly model: DraftProjection;
-  private readonly minConf = runtimeValue("MLX_BUN_DSPARK_MINCONF");
-  private hCtx: MlxArray | null = null; // [1, L, m*H] — grows with the accepted stream
-
-  constructor(private readonly drafter: Pick<DflashDrafter, "cfg" | "forwardInfer">, target: TargetView) {
-    if (!target.gemmaTaps)
-      throw new Error("DSpark drafter requires a Gemma4 target");
-    this.model = target.gemmaTaps.projection;
-    this.tapLayers = drafter.cfg.tapLayers;
-  }
-
-  /** Seed H_ctx from the tapped prompt context (ownership transfers here). */
-  prefill(_promptIds: number[], ctxML?: MlxArray): void {
-    if (!ctxML) throw new Error("DSpark drafter: prefill missing tapped context");
-    this.hCtx = ctxML;
-  }
-
-  /** Draft up to n tokens against the current H_ctx, conditioned on the anchor
-   *  token (the last emitted token = feed's tail). Greedy — the target verify
-   *  decides. anchorHidden is unused (DSpark reads H_ctx, not the target
-   *  hidden). Confidence-scheduled pruning (Alg 1) may return FEWER than n:
-   *  active when the checkpoint carries STS thresholds (cfg.sts, §3.2.1) or
-   *  via the MLX_BUN_DSPARK_MINCONF env override; uncalibrated checkpoints
-   *  draft fixed-length exactly as before. The server pins n ≤ cfg.gamma. */
-  draft(feed: number[], n: number, _stepBase: number, _anchorHidden?: MlxArray): number[] {
-    if (!this.hCtx) throw new Error("DSpark drafter: draft before prefill");
-    const anchorTok = feed[feed.length - 1]!;
-    const envMin = this.minConf;
-    const block = this.drafter.forwardInfer(this.model, this.hCtx, anchorTok, n, {
-      thresholds: this.drafter.cfg.sts?.thresholds,
-      collectLogits: false, // serve loop runs its own verify lm-head, never reads this
-      ...(envMin ? { minConf: Number(envMin) } : {}),
-    });
-    return block.tokens;
-  }
-
-  /** Grow H_ctx by the accepted window [anchor + kAccept drafts] from the
-   *  verified positions' tapped context [1,d+1,m*H]; drop the rejected tips
-   *  (ownership of vCtxML transfers here). */
-  commit(_d: number, kAccept: number, vCtxML?: MlxArray): void {
-    if (!vCtxML) throw new Error("DSpark drafter: commit missing tapped verify context");
-    if (!this.hCtx) throw new Error("DSpark drafter: commit before prefill");
-    const mH = vCtxML.shape[2]!;
-    const add = vCtxML.slice([0, 0, 0], [1, kAccept + 1, mH]); // anchor + accepted
-    const grown = ops.concatAxis([this.hCtx, add], 1);
-    this.hCtx.dispose();
-    add.dispose();
-    vCtxML.dispose();
-    this.hCtx = grown;
-  }
-
-  dispose(): void {
-    this.hCtx?.dispose();
-    this.hCtx = null;
-  }
-}