mlx-bun 0.5.0 → 1.0.0

package/src/engine/engine.ts

@@ -1,56 +0,0 @@
-import type { ExecutionPlanner, GenerationSession, InferenceEngine, RunControl, Timer } from "../contracts/generation";
-import { EngineSession, type SessionResources } from "./session";
-
-export interface EngineOptions {
-  readonly timer: Timer;
-  /** Deadline for an unread stream or a producer blocked by an idle consumer. */
-  readonly idleTimeoutMs?: number;
-  readonly maxQueuedEvents?: number;
-  readonly maxQueuedTokens?: number;
-  readonly maxTopLogprobs?: number;
-  /** Aggregate output buffers for active collecting sessions, in tokens (4 bytes each).
-   * Once terminal, output storage belongs to the caller. */
-  readonly maxCollectTokens?: number;
-}
-
-export function createInferenceEngine<Request, Metrics>(
-  planner: ExecutionPlanner<Request, Metrics>, options: EngineOptions,
-): InferenceEngine<Request, Metrics> {
-  const idleTimeoutMs = options.idleTimeoutMs ?? 30_000;
-  const maxQueuedEvents = options.maxQueuedEvents ?? 32;
-  const maxQueuedTokens = options.maxQueuedTokens ?? 256;
-  const maxCollectTokens = options.maxCollectTokens ?? 65_536;
-  const maxTopLogprobs = options.maxTopLogprobs ?? 20;
-  for (const [name, value] of Object.entries({ idleTimeoutMs, maxQueuedEvents, maxQueuedTokens, maxCollectTokens, maxTopLogprobs }))
-    if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${name} must be a positive safe integer`);
-  const sessions = new Set<GenerationSession<Metrics>>();
-  let closed = false;
-  let closing: Promise<void> | undefined;
-  let nextId = 0;
-  let reserved = 0;
-  const resources: SessionResources = {
-    timer: options.timer, idleTimeoutMs, maxQueuedEvents, maxQueuedTokens, maxTopLogprobs,
-    reserveOutput(tokens) {
-      if (tokens > maxCollectTokens - reserved) throw new Error("collection output capacity exceeded");
-      const buffer = new Uint32Array(tokens);
-      reserved += tokens;
-      let released = false;
-      return { buffer, release() { if (!released) { released = true; reserved -= tokens; } } };
-    },
-  };
-  return {
-    async open(request: Request, control: RunControl) {
-      if (closed) throw new Error("inference engine is closed");
-      let session: EngineSession<Metrics> | undefined;
-      session = new EngineSession(String(++nextId), (cancellation) => planner.plan(request, cancellation),
-        { ...control }, resources,
-        () => { if (session) sessions.delete(session); });
-      if (session.state !== "terminal") sessions.add(session);
-      return session;
-    },
-    close() {
-      closed = true;
-      return closing ??= Promise.all([...sessions].map((session) => session.cancel("engine_closed"))).then(() => {});
-    },
-  };
-}

package/src/engine/execution-coordinator.ts

@@ -1,70 +0,0 @@
-import type { Cancellation } from "../contracts/generation";
-import type { DisposableResource } from "../contracts/resources";
-import { AdmissionRejected } from "./admission";
-import { throwIfCancelled } from "./cancellation";
-
-type Mode = "shared" | "exclusive";
-interface Waiter {
-  mode: Mode;
-  resolve(lease: DisposableResource): void;
-  reject(error: unknown): void;
-  unsubscribe(): void;
-}
-
-/** Shared worker activity; exclusive managed jobs. FIFO writers cannot starve
- * behind newly arriving inference. This coordinates execution, not memory size. */
-export class ExecutionCoordinator {
-  #readers = 0;
-  #writer = false;
-  #closed = false;
-  #queue: Waiter[] = [];
-  constructor(readonly maxQueued = 64) {
-    if (!Number.isSafeInteger(maxQueued) || maxQueued < 0) throw new Error("invalid coordination queue bound");
-  }
-  acquire(mode: Mode, cancellation?: Cancellation): Promise<DisposableResource> {
-    if (this.#closed) return Promise.reject(new Error("execution coordinator is closed"));
-    try { if (cancellation) throwIfCancelled(cancellation); }
-    catch (error) { return Promise.reject(error); }
-    if (!this.#queue.length && !this.#writer && (mode === "shared" || this.#readers === 0))
-      return Promise.resolve(this.#lease(mode));
-    if (this.#queue.length >= this.maxQueued) return Promise.reject(new AdmissionRejected());
-    return new Promise((resolve, reject) => {
-      const waiter: Waiter = { mode, resolve, reject, unsubscribe() {} };
-      this.#queue.push(waiter);
-      waiter.unsubscribe = cancellation?.subscribe((reason) => {
-        const index = this.#queue.indexOf(waiter);
-        if (index < 0) return;
-        this.#queue.splice(index, 1);
-        waiter.unsubscribe();
-        reject(new Error(`execution admission cancelled: ${reason}`));
-        this.#drain();
-      }) ?? (() => {});
-      if (!this.#queue.includes(waiter)) waiter.unsubscribe();
-    });
-  }
-  #lease(mode: Mode): DisposableResource {
-    if (mode === "shared") this.#readers++;
-    else this.#writer = true;
-    let disposed = false;
-    return { dispose: () => {
-      if (disposed) return;
-      disposed = true;
-      if (mode === "shared") this.#readers--;
-      else this.#writer = false;
-      this.#drain();
-    } };
-  }
-  #drain(): void {
-    while (!this.#writer && this.#queue.length) {
-      const next = this.#queue[0]!;
-      if (next.mode === "exclusive" && this.#readers > 0) return;
-      this.#queue.shift(); next.unsubscribe(); next.resolve(this.#lease(next.mode));
-    }
-  }
-  close(): void {
-    this.#closed = true;
-    for (const next of this.#queue.splice(0)) {
-      next.unsubscribe(); next.reject(new Error("execution coordinator is closed"));
-    }
-  }
-}

package/src/engine/execution-plan.ts

@@ -1,64 +0,0 @@
-import type { ExecutionCapabilities, ExecutionFeatures, ExecutionRequirements, ResolvedExecution } from "../contracts/execution";
-
-/** Select the request method, then place it using executor capabilities. */
-export function resolveExecution(
-  request: ExecutionRequirements, capabilities: ExecutionCapabilities,
-  features: ExecutionFeatures = { pagedKv: false, fill: false },
-): ResolvedExecution {
-  const reasons: string[] = [];
-  const sharedRequestExclusions = [
-    [!capabilities.continuous, "continuous-unavailable"],
-    [request.hasVision && !capabilities.mediaBatch, "media-requires-serial"],
-    [request.hasAdapters && !capabilities.adapterBatch, "adapters-require-serial"],
-    [request.kvQuant && !capabilities.quantizedBatch, "kv-scheme-requires-serial"],
-    [request.turboQuant && !capabilities.turboQuantBatch, "turbo-kv-requires-serial"],
-    [request.hasGrammar && !capabilities.grammarBatch, "grammar-batching-disabled"],
-    [features.pagedKv && !capabilities.pagedBatch, "paged-kv-requires-serial"],
-  ] as const;
-  const sharedAdapterMethod = capabilities.sharedSpeculativeAdapters === true &&
-    !sharedRequestExclusions.some(([excluded]) => excluded) &&
-    capabilities.groupedMethods?.includes("speculative") === true;
-  const grammarProposals = features.grammarJump === true && request.hasGrammar && !request.hasDraft && !request.hasVision &&
-    (!request.wantsLogprobs || capabilities.speculativeLogprobs === true) && !features.pagedKv && capabilities.method === "autoregressive" &&
-    capabilities.sharedGrammarProposals === true && capabilities.groupedMethods?.includes("speculative") === true &&
-    (!request.hasAdapters || sharedAdapterMethod) && (!request.kvQuant || capabilities.speculativeKvQuant === true) &&
-    (!request.turboQuant || capabilities.speculativeTurboQuant === true) &&
-    !sharedRequestExclusions.some(([excluded]) => excluded);
-  const speculative = grammarProposals || (capabilities.method === "autoregressive" && request.hasDraft &&
-    !request.hasVision && (!request.hasAdapters || sharedAdapterMethod) && (!request.wantsLogprobs || capabilities.speculativeLogprobs === true) &&
-    (!request.kvQuant || capabilities.speculativeKvQuant === true) &&
-    (!request.turboQuant || capabilities.speculativeTurboQuant === true) && !features.pagedKv);
-  const method = speculative ? "speculative" : capabilities.method;
-  const continuousExclusions = [sharedRequestExclusions[0],
-    [!(capabilities.groupedMethods ?? ["autoregressive"]).includes(method), "method-requires-serial"],
-    ...sharedRequestExclusions.slice(1),
-  ] as const;
-  for (const [excluded, reason] of continuousExclusions) if (excluded) reasons.push(reason);
-  const mechanism = reasons.length ? "serial" : "continuous";
-  if (request.hasDraft && !speculative) reasons.push("draft-incompatible-with-request");
-  const pagedKv = features.pagedKv && !request.hasVision && !request.hasAdapters;
-  if (features.pagedKv && !pagedKv) reasons.push("paged-kv-bypassed-for-media-or-adapters");
-  const promptCache = method !== "speculative" && (!request.hasVision ||
-    (mechanism === "continuous" && request.hasPreparedPrefixIdentity === true && capabilities.mediaPrefixCache === true));
-  const sharedFill = mechanism === "continuous" && capabilities.sharedFill === true && !pagedKv;
-  const speculativeEcho = method === "speculative" && mechanism === "continuous" &&
-    capabilities.sharedSpeculativeEcho === true;
-  const fill = features.fill && !request.hasVision && !request.hasGrammar && !request.wantsLogprobs &&
-    (speculativeEcho || (method === "autoregressive" && (mechanism === "serial" || sharedFill) &&
-      !request.hasDraft && (!request.userSeed || sharedFill)));
-  // Cache-format eligibility belongs to the method's append binding.
-  if (features.fill && !fill) reasons.push("fill-incompatible-with-request");
-  const checkpoint = capabilities.checkpoints && method === "autoregressive" && !request.hasVision &&
-    (mechanism === "serial" || capabilities.sharedCheckpoints === true) && promptCache && !pagedKv && !request.hasGrammar &&
-    !features.fill && !request.wantsLogprobs;
-  const compiledDecode = features.compiledDecode === true && capabilities.compiledDecode === true &&
-    method === "autoregressive" && !request.hasAdapters && !pagedKv && !(sharedFill && fill);
-  if (features.compiledDecode && !compiledDecode) reasons.push("compiled-decode-unavailable-for-request");
-  const grammarJump = grammarProposals || (features.grammarJump === true && request.hasGrammar &&
-    method === "autoregressive" && mechanism === "serial" && !request.wantsLogprobs);
-  if (features.grammarJump && request.hasGrammar && !grammarJump)
-    reasons.push("grammar-jump-incompatible-with-request");
-  return Object.freeze({ method, mechanism, pagedKv, promptCache, checkpoint, fill,
-    compiledDecode, grammarJump,
-    reasons: Object.freeze(reasons) });
-}

package/src/engine/execution-tasks.ts

@@ -1,44 +0,0 @@
-interface Task {
-  run(): Promise<void>;
-  reject(error: unknown): void;
-}
-
-/** Work whose owner requires an execution boundary, without owning a decode
- * row. The driver supplies the lease; this queue owns waiting and cancellation.
- * Once started, work settles before its caller can release native resources. */
-export class ExecutionTasks {
-  #pending: Task[] = [];
-  get pending(): number { return this.#pending.length; }
-
-  enqueue<T>(work: () => Promise<T>, cancellation?: Cancellation): Promise<T> {
-    if (cancellation?.reason !== undefined) return Promise.reject(new GenerationCancelled(cancellation.reason));
-    return new Promise<T>((resolve, reject) => {
-      let unsubscribe = () => {};
-      const cleanup = () => unsubscribe();
-      const task: Task = {
-        async run() {
-          cleanup();
-          try { resolve(await work()); } catch (error) { reject(error); }
-        },
-        reject(error) { cleanup(); reject(error); },
-      };
-      this.#pending.push(task);
-      unsubscribe = cancellation?.subscribe(reason => {
-        const index = this.#pending.indexOf(task);
-        if (index < 0) return;
-        this.#pending.splice(index, 1);
-        task.reject(new GenerationCancelled(reason));
-      }) ?? (() => {});
-      if (!this.#pending.includes(task)) unsubscribe();
-    });
-  }
-
-  async advance(): Promise<void> { await this.#pending.shift()?.run(); }
-
-  rejectAll(error: unknown): void {
-    const tasks = this.#pending; this.#pending = [];
-    for (const task of tasks) task.reject(error);
-  }
-}
-import type { Cancellation } from "../contracts/generation";
-import { GenerationCancelled } from "./cancellation";

package/src/engine/namespaced-cache.ts

@@ -1,13 +0,0 @@
-import type { PrefixCache } from "../contracts/prefix-cache";
-
-/** Compose numerical identity with a cache without exposing its storage tiers. */
-export function namespacedCache<State, Attachment>(cache: PrefixCache<State, Attachment>,
-  namespace: (base: string) => string): PrefixCache<State, Attachment> {
-  return {
-    closeSession: id => cache.closeSession?.(id),
-    reclaim: () => cache.reclaim?.(),
-    ...(cache.prefetch ? { prefetch: (tokens: number[], ns = "", sessionId?: string) => cache.prefetch!(tokens, namespace(ns), sessionId) } : {}),
-    take: (tokens, ns = "", sessionId) => cache.take(tokens, namespace(ns), sessionId),
-    put: (tokens, state, ns = "", retain, attachments, sessionId) => cache.put(tokens, state, namespace(ns), retain, attachments, sessionId),
-  };
-}

package/src/engine/resources.ts

@@ -1,53 +0,0 @@
-import type { DisposableResource, PreparedStateChange, ResourceOwner } from "../contracts/resources";
-
-export function ownResource<T>(value: T, release: (value: T) => void): ResourceOwner<T> {
-  let held: { value: T } | undefined = { value };
-  const borrow = () => {
-    if (!held) throw new Error("resource ownership has ended");
-    return held.value;
-  };
-  return {
-    borrow,
-    transfer() { const result = borrow(); held = undefined; return result; },
-    close() {
-      if (!held) return;
-      const result = held.value;
-      held = undefined;
-      release(result);
-    },
-  };
-}
-
-/** Attempt every release once. One failed destructor must not leak siblings. */
-export function disposeResources(resources: Iterable<DisposableResource>): void {
-  const errors: unknown[] = [];
-  for (const resource of new Set(resources)) {
-    try { resource.dispose(); } catch (error) { errors.push(error); }
-  }
-  if (errors.length === 1) throw errors[0];
-  if (errors.length) throw new AggregateError(errors, "resource cleanup failed");
-}
-
-/** Used at failure boundaries to retain the execution error as well as cleanup. */
-export function cleanupFailure(error: unknown, cleanup: () => void): never {
-  try { cleanup(); }
-  catch (cleanupError) { throw new AggregateError([error, cleanupError], "execution and cleanup failed"); }
-  throw error;
-}
-
-/** Complete every preparation before publishing any owner's replacement.
- * Old state is released only after all owners have committed. */
-export function applyStateChanges(prepare: readonly (() => PreparedStateChange)[]): void {
-  const changes: PreparedStateChange[] = [];
-  try {
-    for (const build of prepare) changes.push(build());
-    for (const change of changes) change.commit();
-  } catch (error) { return cleanupFailure(error, () => disposeResources(changes.splice(0))); }
-  disposeResources(changes);
-}
-
-export function withResource<T, R>(owner: Pick<ResourceOwner<T>, "borrow" | "close">, use: (value: T) => R): R {
-  try { return use(owner.borrow()); }
-  catch (error) { cleanupFailure(error, () => owner.close()); }
-  finally { owner.close(); }
-}

package/src/engine/scheduler.ts

@@ -1,92 +0,0 @@
-import type { ExecutionGroup, SchedulingClock } from "../contracts/scheduling";
-import { disposeResources } from "./resources";
-
-/** Continuous scheduling policy. Each advance is a backend-defined safe unit;
- * this driver neither handles native state nor forces pending work to evaluate. */
-export async function driveExecutionGroup(
-  group: ExecutionGroup, clock: SchedulingClock, yieldAfterPreparation = false,
-): Promise<void> {
-  let execution: (() => void) | undefined;
-  let residency: (() => void) | undefined;
-  let lastYield = 0;
-  let terminalError: unknown = new Error("scheduler closed");
-  const release = () => {
-    const releases = [execution, residency];
-    execution = residency = undefined;
-    disposeResources(releases.filter((fn): fn is () => void => !!fn).map((dispose) => ({ dispose })));
-  };
-  try {
-    while (!group.closed) {
-      group.pruneCancelled();
-      let held = group.admissionHeld;
-      if (!group.active && !group.preparing && (held || (!group.queued && !group.pendingTasks))) {
-        release();
-        await group.waitForWork();
-        continue;
-      }
-      residency ??= group.reserveResidency();
-      if (!execution && group.acquireExecution) execution = await group.acquireExecution();
-      if (group.closed) break;
-
-      // One preparation task per iteration. An exclusive model mutation
-      // keeps its existing drain priority; preparation cannot prolong it.
-      if (!held && group.pendingTasks && group.advanceTask) {
-        await group.advanceTask();
-        if (group.closed) break;
-        group.pruneCancelled();
-        held = group.admissionHeld;
-      }
-
-      if (!group.preparing && !held && group.queued && group.active < group.maxActive)
-        group.admitNext();
-      while (group.preparing && group.canPrepareMore && !held && group.queued &&
-          group.active + (group.preparingRows ?? 1) < group.maxActive && group.canBurst() &&
-          (group.preparingTokens ?? 0) + (group.nextPreparationTokens ?? 0) <= (group.maxPreparationTokens ?? Infinity)) {
-        if (!group.admitNext()) break;
-      }
-      const mixed = group.preparing && group.active ? group.mixedPreparation : undefined;
-      if (mixed && group.advanceMixed) {
-        // Reserve the method's running-token demand first; prompt work fills
-        // the rest. A budget smaller than one token per row still progresses.
-        const budget = Math.max(group.maxIterationTokens ?? Infinity,
-          mixed.runningTokens + mixed.minimumPreparationTokens);
-        await group.advanceMixed(budget);
-        lastYield = clock.now();
-        await clock.yield();
-        continue;
-      }
-      if (group.preparing) {
-        const activeBefore = group.active;
-        await group.advancePreparation();
-        // A bounded preparation may publish output before its state work ends.
-        // Flush it before the next work unit; queued short admissions still
-        // form a group across yields. Re-enter policy to observe new work,
-        // cancellation, admission holds and shutdown.
-        if (group.preparationPublishedOutput ||
-            (yieldAfterPreparation && !activeBefore && !group.preparing && group.active === 1 && !group.queued)) {
-          lastYield = clock.now();
-          await clock.yield();
-          continue;
-        }
-      }
-
-      // Finish short admissions before decode; long preparation interleaves
-      // with active work because the group still reports preparing=true.
-      if (!group.preparing && !held && group.queued && group.active < group.maxActive && group.canBurst())
-        continue;
-      if (group.active) {
-        try { await group.advance(); }
-        catch (error) { group.failActive(error); }
-      }
-      // Preserve the serial responsiveness budget for the single active run.
-      if (group.active === 1 && !group.queued && !group.preparing &&
-          !group.admissionHeld && clock.now() - lastYield < 25) continue;
-      lastYield = clock.now();
-      await clock.yield();
-    }
-  } catch (error) {
-    terminalError = error;
-  } finally {
-    disposeResources([{ dispose: () => group.failAll(terminalError) }, { dispose: release }]);
-  }
-}

package/src/engine/session.ts

@@ -1,247 +0,0 @@
-import type {
-  Cancellation, CancelReason, ExecutionPlan, GenerationEvent, GenerationOutcome,
-  GenerationOutput, GenerationSession, MethodResult, MethodRun, RunControl,
-  SessionState, Timer, TokenLogprobs,
-} from "../contracts/generation";
-import { CancellationSource, throwIfCancelled } from "./cancellation";
-
-export interface SessionResources {
-  readonly timer: Timer;
-  readonly idleTimeoutMs: number;
-  readonly maxQueuedEvents: number;
-  readonly maxQueuedTokens: number;
-  readonly maxTopLogprobs: number;
-  reserveOutput(tokens: number): { buffer: Uint32Array; release(): void };
-}
-
-/** Lifecycle and bounded delivery only. No graph, cache, sampler, or method branches. */
-export class EngineSession<Metrics> implements GenerationSession<Metrics> {
-  readonly result: Promise<GenerationOutcome<Metrics>>;
-  readonly events: AsyncIterable<GenerationEvent>;
-  #state: SessionState = "created";
-  #cancel = new CancellationSource();
-  #settle!: (outcome: GenerationOutcome<Metrics>) => void;
-  #started = false;
-  #readerClaimed = false;
-  #reading = false;
-  #publishing = false;
-  #queue: GenerationEvent[] = [];
-  #queuedTokens = 0;
-  #committed = 0;
-  #sequence = 0;
-  #wakeReader: (() => void) | undefined;
-  #wakeProducer: (() => void) | undefined;
-  #stopTimer: (() => void) | undefined;
-  #unsubscribe: (() => void) | undefined;
-  #buffer: Uint32Array | undefined;
-  #limit = 0;
-  #outputStopped = false;
-
-  constructor(
-    readonly id: string,
-    private readonly prepare: (cancellation: Cancellation) => Promise<ExecutionPlan<Metrics>>,
-    private readonly control: RunControl,
-    private readonly resources: SessionResources,
-    private readonly onTerminal: () => void,
-  ) {
-    this.result = new Promise((resolve) => { this.#settle = resolve; });
-    this.events = { [Symbol.asyncIterator]: () => this.#iterator() };
-    const unsubscribe = control.cancellation?.subscribe((reason) => { void this.cancel(reason); });
-    if (this.#state === "terminal") unsubscribe?.();
-    else this.#unsubscribe = unsubscribe;
-    if (this.#state !== "terminal") {
-      if (control.output !== "stream") this.#start();
-      else this.#armIdle();
-    }
-  }
-
-  get state(): SessionState { return this.#state; }
-
-  async cancel(reason: CancelReason = "requested"): Promise<void> {
-    if (this.#state !== "terminal") {
-      this.#cancel.cancel(reason);
-      this.#queue = [];
-      this.#queuedTokens = 0;
-      this.#wakeReader?.();
-      this.#wakeProducer?.();
-      this.#stopTimer?.();
-      if (!this.#started) this.#finish({ status: "cancelled", reason, committedTokens: 0 });
-    }
-    await this.result;
-  }
-
-  close(): Promise<void> { return this.cancel("consumer_closed"); }
-
-  #armIdle(): void {
-    this.#stopTimer?.();
-    this.#stopTimer = this.resources.timer.after(this.resources.idleTimeoutMs,
-      () => { void this.cancel("consumer_idle"); });
-  }
-
-  #iterator(): AsyncIterator<GenerationEvent> {
-    if (this.control.output !== "stream") throw new Error("collect sessions return output through result");
-    if (this.#readerClaimed) throw new Error("generation events have one consumer");
-    this.#readerClaimed = true;
-    return {
-      next: async () => {
-        if (this.#reading) throw new Error("concurrent next() is not supported");
-        this.#reading = true;
-        this.#stopTimer?.();
-        try {
-          this.#start();
-          while (!this.#queue.length && this.#state !== "terminal") {
-            await new Promise<void>((resolve) => { this.#wakeReader = resolve; });
-            this.#wakeReader = undefined;
-          }
-          const event = this.#queue.shift();
-          if (!event) return { done: true, value: undefined };
-          if (event.type === "committed") this.#queuedTokens -= event.tokenIds.length;
-          this.#wakeProducer?.();
-          if (this.#state !== "terminal") this.#armIdle();
-          return { done: false, value: event };
-        } finally { this.#reading = false; }
-      },
-      return: async () => { await this.close(); return { done: true, value: undefined }; },
-      throw: async (error) => { await this.close(); throw error; },
-    };
-  }
-
-  #start(): void {
-    if (this.#started || this.#state === "terminal") return;
-    this.#started = true;
-    void this.#execute();
-  }
-
-  async #execute(): Promise<void> {
-    let run: MethodRun<Metrics> | undefined;
-    let reservation: ReturnType<SessionResources["reserveOutput"]> | undefined;
-    let result: MethodResult<Metrics> | undefined;
-    let failure: unknown;
-    let failed = false;
-    try {
-      this.#state = "preparing";
-      throwIfCancelled(this.#cancel);
-      const plan = await this.prepare(this.#cancel);
-      throwIfCancelled(this.#cancel);
-      if (!Number.isSafeInteger(plan.outputTokenLimit) || plan.outputTokenLimit < 0)
-        throw new Error("invalid planned output token limit");
-      this.#limit = plan.outputTokenLimit;
-      if (this.control.output === "collect") {
-        reservation = this.resources.reserveOutput(this.#limit);
-        this.#buffer = reservation.buffer;
-      }
-      run = await plan.method.createRun(this.#cancel);
-      throwIfCancelled(this.#cancel);
-      this.#state = "running";
-      const output: GenerationOutput = {
-        commit: (ids, logprobs) => this.#publish(ids, logprobs),
-        progress: (completed, total) => this.#progress(completed, total),
-      };
-      result = await run.execute(output, this.#cancel);
-    } catch (error) { failure = error; failed = true; }
-    this.#state = "settling";
-    // Terminal means resources are safe to release, not merely that JS stopped reading.
-    let cleanupFailed = false;
-    let cleanupError: string | undefined;
-    try { await run?.close(); }
-    catch (error) {
-      cleanupError = error instanceof Error ? error.message : String(error);
-      if (!failed) failure = error;
-      failed = true;
-      cleanupFailed = true;
-    }
-    reservation?.release(); // Completed output ownership transfers to the caller.
-    const common = { committedTokens: this.#committed,
-      ...(this.#buffer ? { output: this.#buffer.subarray(0, this.#committed) } : {}) };
-    if (this.#cancel.reason && !cleanupFailed) {
-      this.#finish({ status: "cancelled", reason: this.#cancel.reason, ...common });
-    } else if (failed) {
-      this.#finish({ status: "failed", error: { code: cleanupFailed ? "cleanup_failed" : "execution_failed",
-        message: failure instanceof Error ? failure.message : String(failure),
-        ...(cleanupError === undefined ? {} : { cleanupError }) }, ...common });
-    } else {
-      this.#finish({ status: "completed", result: result!, ...common });
-    }
-  }
-
-  async #publish(ids: readonly number[], logprobs?: readonly (TokenLogprobs | undefined)[]): Promise<void | false> {
-    if (this.#publishing) throw new Error("method must await each publication");
-    this.#publishing = true;
-    try {
-      throwIfCancelled(this.#cancel);
-      if (this.#state !== "running") throw new Error("publication outside method execution");
-      if (this.#outputStopped) throw new Error("method published after the consumer requested a stop");
-      if (ids.length > this.#limit - this.#committed) throw new Error("method exceeded planned output limit");
-      if (logprobs && logprobs.length !== ids.length) throw new Error("logprobs must align with committed tokens");
-      if (logprobs?.some((item) => (item?.top?.length ?? 0) > this.resources.maxTopLogprobs))
-        throw new Error("top logprobs exceed session delivery capacity");
-      for (const id of ids)
-        if (!Number.isInteger(id) || id < 0 || id > 0xffffffff) throw new Error("invalid committed token id");
-      if (this.control.output === "callback") {
-        this.#committed += ids.length;
-        const result = await this.control.onTokens(ids, logprobs);
-        if (result === false) this.#outputStopped = true;
-        return result;
-      }
-      if (this.#buffer) {
-        if (logprobs) throw new Error("token logprobs require stream consumption");
-        this.#buffer.set(ids, this.#committed);
-        this.#committed += ids.length;
-        return;
-      }
-      for (let offset = 0; offset < ids.length;) {
-        const length = Math.min(ids.length - offset, this.resources.maxQueuedTokens);
-        await this.#space(length);
-        // Snapshot producer-owned arrays; later scratch-buffer reuse cannot alter events.
-        const event: GenerationEvent = { type: "committed", sequence: this.#sequence++,
-          tokenIds: ids.slice(offset, offset + length),
-          ...(logprobs ? { logprobs: logprobs.slice(offset, offset + length).map((item) => item && ({
-            ...(item.logprob === undefined ? {} : { logprob: item.logprob }),
-            ...(item.top ? { top: item.top.map((entry) => ({ id: entry.id, logprob: entry.logprob })) } : {}),
-          })) } : {}) };
-        this.#queue.push(event);
-        this.#queuedTokens += length;
-        this.#committed += length;
-        offset += length;
-        this.#wakeReader?.();
-      }
-    } finally { this.#publishing = false; }
-  }
-
-  async #progress(completed: number, total?: number): Promise<void> {
-    if (this.#publishing) throw new Error("method must await each publication");
-    this.#publishing = true;
-    try {
-      throwIfCancelled(this.#cancel);
-      if (this.#state !== "running") throw new Error("publication outside method execution");
-      if (!Number.isFinite(completed) || completed < 0 ||
-          (total !== undefined && (!Number.isFinite(total) || total < completed)))
-        throw new Error("invalid progress");
-      if (this.control.output !== "stream") return;
-      await this.#space(0);
-      this.#queue.push({ type: "progress", completed, ...(total === undefined ? {} : { total }) });
-      this.#wakeReader?.();
-    } finally { this.#publishing = false; }
-  }
-
-  async #space(tokens: number): Promise<void> {
-    while (this.#queue.length >= this.resources.maxQueuedEvents ||
-           this.#queuedTokens + tokens > this.resources.maxQueuedTokens) {
-      throwIfCancelled(this.#cancel);
-      this.#armIdle();
-      await new Promise<void>((resolve) => { this.#wakeProducer = resolve; });
-      this.#wakeProducer = undefined;
-    }
-    throwIfCancelled(this.#cancel);
-  }
-
-  #finish(outcome: GenerationOutcome<Metrics>): void {
-    if (this.#state === "terminal") return;
-    this.#state = "terminal";
-    this.#stopTimer?.();
-    this.#unsubscribe?.();
-    this.#settle(outcome);
-    this.#wakeReader?.();
-    this.onTerminal();
-  }
-}