mlx-bun 0.4.0 → 1.0.0

package/src/download.ts

@@ -1,505 +0,0 @@
-// Resumable HF downloads with checksum verification (Phase 5).
-//
-// The Python downloader failure modes this replaces (PLAN "Context /
-// lore"): Xet stalls (we speak plain HTTPS resolve/CDN), no resume on
-// flaky links (we Range-resume partial blobs), and silent corruption
-// (every blob is verified — sha256 for LFS files against the API's
-// normalized LFS digest, git-blob sha1 for small files against blobId).
-//
-// Writes the exact huggingface_hub cache layout so the registry and
-// loaders find the result with zero changes:
-//   <hub>/models--{org}--{name}/blobs/<sha>            (verified bytes)
-//   <hub>/models--{org}--{name}/snapshots/<commit>/<file> → ../../blobs/<sha>
-//   <hub>/models--{org}--{name}/refs/<revision>        (commit sha)
-//
-// Files download sequentially (decode is bandwidth-bound, the network
-// rarely is; resumability matters more than parallelism here).
-
-import {
-  mkdirSync, existsSync, statSync, createWriteStream, renameSync, rmSync,
-  symlinkSync, readFileSync, openSync, closeSync, readSync, writeSync,
-  statfsSync,
-} from "node:fs";
-import { dirname, join } from "node:path";
-import { DEFAULT_HUB } from "./registry";
-
-const ENDPOINT = "https://huggingface.co";
-
-export interface RepoFile {
-  rfilename: string;
-  size: number;
-  /** git blob sha1 (non-LFS identity, and the blob filename for non-LFS). */
-  blobId: string;
-  /** LFS sha256 + size; present for large files. sha256 is the blob filename. */
-  lfs?: { sha256: string; size: number };
-}
-
-export interface RepoListing {
-  /** Commit sha the revision resolves to (snapshot dir name). */
-  sha: string;
-  files: RepoFile[];
-}
-
-export interface DownloadOptions {
-  revision?: string;
-  cacheDir?: string;
-  endpoint?: string;
-  token?: string | null;
-  onProgress?: (file: string, received: number, total: number) => void;
-}
-
-export interface DownloadSpacePlan {
-  /** Bytes still absent after crediting verified blobs and resumable prefixes. */
-  remainingBytes: number;
-  /** Files that still need at least one byte. */
-  remainingFiles: number;
-  /** Files already complete in the shared HF blob store. */
-  completeFiles: number;
-  /** Existing `.incomplete` bytes that will be rehashed and resumed. */
-  resumableBytes: number;
-}
-
-/** One GiB for filesystem metadata, the final refs write, and normal host
- * operation. The artifact bytes themselves are exact; this is deliberately a
- * small fixed guard rather than a percentage that would add tens of GiB to a
- * Colibri download. */
-export const DOWNLOAD_DISK_RESERVE_BYTES = 2 ** 30;
-
-/** Compute the exact remaining payload without opening or hashing any blob.
- * A valid-size final blob is already complete; an in-range `.incomplete`
- * prefix is credited because downloadOneLocked resumes it in place. */
-export function planDownloadSpace(
-  files: readonly RepoFile[],
-  blobsDir: string,
-): DownloadSpacePlan {
-  let remainingBytes = 0;
-  let remainingFiles = 0;
-  let completeFiles = 0;
-  let resumableBytes = 0;
-  for (const file of files) {
-    const blobId = file.lfs?.sha256 ?? file.blobId;
-    if (!blobId) throw new Error(`no blob id for ${file.rfilename}`);
-    const blobPath = join(blobsDir, blobId);
-    if (existsSync(blobPath) && statSync(blobPath).size === file.size) {
-      completeFiles++;
-      continue;
-    }
-    const partPath = `${blobPath}.incomplete`;
-    const partBytes = existsSync(partPath) ? statSync(partPath).size : 0;
-    const credited = partBytes >= 0 && partBytes <= file.size ? partBytes : 0;
-    resumableBytes += credited;
-    remainingBytes += file.size - credited;
-    remainingFiles++;
-  }
-  return { remainingBytes, remainingFiles, completeFiles, resumableBytes };
-}
-
-function formatGib(bytes: number): string {
-  return `${(bytes / 2 ** 30).toFixed(2)} GiB`;
-}
-
-/** HF auth: explicit > env > the file `hf auth login` writes. */
-export function hfToken(): string | null {
-  if (process.env.HF_TOKEN) return process.env.HF_TOKEN;
-  try {
-    return readFileSync(`${process.env.HOME}/.cache/huggingface/token`, "utf8").trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-/** 401/403 almost always means a gated/private repo, not a broken network —
- *  say so instead of leaving the user staring at a bare status code. */
-function authHint(status: number): string {
-  return status === 401 || status === 403
-    ? " — gated repo? run `hf auth login` or set HF_TOKEN"
-    : "";
-}
-
-// --- download lockfile -----------------------------------------------------
-// Two writers on one blob (a foreground `mlx-bun get` racing the server's
-// background auto-download) both append to the same .incomplete file and
-// corrupt it. An O_EXCL .lock beside the .incomplete serializes them; a lock
-// older than LOCK_STALE_MS (crashed owner) or whose pid is gone is stolen.
-
-const LOCK_STALE_MS = 60 * 60 * 1000; // ~1 h: longer than any sane blob fetch
-
-function lockIsStale(lockPath: string): boolean {
-  try {
-    const st = statSync(lockPath);
-    if (Date.now() - st.mtimeMs > LOCK_STALE_MS) return true;
-    const pid = Number(readFileSync(lockPath, "utf8").split("\n")[0]);
-    if (Number.isFinite(pid) && pid > 0) {
-      try { process.kill(pid, 0); } catch { return true; } // owner is gone
-    }
-    return false;
-  } catch {
-    return true; // unreadable/vanished — treat as stale, O_EXCL still arbitrates
-  }
-}
-
-/** Take `<blobPath>.lock` (O_EXCL). Returns a release fn, or throws the
- *  friendly "another download in progress" error when live-held. */
-function acquireLock(blobPath: string, name: string): () => void {
-  const lockPath = `${blobPath}.lock`;
-  for (let attempt = 0; attempt < 2; attempt++) {
-    try {
-      const fd = openSync(lockPath, "wx");
-      writeSync(fd, `${process.pid}\n${new Date().toISOString()}\n`);
-      closeSync(fd);
-      return () => { try { rmSync(lockPath, { force: true }); } catch {} };
-    } catch (e) {
-      if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
-      if (lockIsStale(lockPath)) {
-        try { rmSync(lockPath, { force: true }); } catch {}
-        continue; // one retry after stealing
-      }
-      let holder = "";
-      try { holder = ` (pid ${readFileSync(lockPath, "utf8").split("\n")[0]})`; } catch {}
-      throw new Error(
-        `another download of ${name} is in progress${holder} — ` +
-        `wait for it to finish, or delete ${lockPath} if you're sure it isn't`,
-      );
-    }
-  }
-  throw new Error(`could not acquire ${lockPath}`);
-}
-
-/** Reject a repo file path that could escape the snapshot directory once
- *  joined onto it. `rfilename` comes verbatim from the remote HF API's
- *  `siblings[].rfilename` (listRepoFiles) — for a repo the caller doesn't
- *  control (attacker-owned/attacker-referenced), that string is untrusted
- *  input reaching a path-join + symlink write (downloadModel's
- *  `join(snapDir, f.rfilename)` + `symlinkSync`). node:path's `join()`
- *  normalizes `..` segments, so an rfilename like
- *  `../../../../home/x/.ssh/authorized_keys` would otherwise resolve
- *  OUTSIDE the intended snapshots dir and write a symlink at an arbitrary
- *  filesystem path. Reachable over HTTP via POST /api/hub/download
- *  (src/hub-rest.ts), which passes any caller-supplied `repo` straight
- *  through with no allowlist — this check is the actual gate, not that
- *  route. A leading `/` (absolute path) is equally rejected: join() would
- *  otherwise treat it as relative to snapDir and still normalize safely,
- *  but there's no legitimate reason a repo file entry needs one, and
- *  rejecting it removes any doubt. */
-export function isSafeRepoFilename(rfilename: string): boolean {
-  if (!rfilename || rfilename.startsWith("/") || rfilename.includes("\0")) return false;
-  const parts = rfilename.split("/");
-  return parts.every((p) => p !== "" && p !== "." && p !== "..");
-}
-
-/** git blob identity: sha1("blob <size>\0" + content) — what blobId is. */
-export function gitBlobSha1(bytes: Uint8Array): string {
-  const hasher = new Bun.CryptoHasher("sha1");
-  hasher.update(`blob ${bytes.length}\0`);
-  hasher.update(bytes);
-  return hasher.digest("hex");
-}
-
-export async function listRepoFiles(
-  repoId: string, opts: DownloadOptions = {},
-): Promise<RepoListing> {
-  const endpoint = opts.endpoint ?? ENDPOINT;
-  const revision = opts.revision ?? "main";
-  const token = opts.token === undefined ? hfToken() : opts.token;
-  const url = `${endpoint}/api/models/${repoId}/revision/${encodeURIComponent(revision)}?blobs=true`;
-  const res = await fetch(url, {
-    headers: token ? { authorization: `Bearer ${token}` } : {},
-  });
-  if (!res.ok)
-    throw new Error(
-      `HF API ${res.status} for ${repoId}@${revision}: ${(await res.text()).slice(0, 200)}` +
-      authHint(res.status),
-    );
-  const body = (await res.json()) as {
-    sha: string;
-    siblings: {
-      rfilename: string;
-      size?: number;
-      blobId?: string;
-      // The current HF API calls this field `sha256`. Accept the older `oid`
-      // spelling too, but normalize it before the download path sees it.
-      lfs?: { sha256?: string; oid?: string; size: number };
-    }[];
-  };
-  return {
-    sha: body.sha,
-    files: body.siblings.map((s) => {
-      let lfs: RepoFile["lfs"];
-      if (s.lfs) {
-        const sha256 = s.lfs.sha256 ?? s.lfs.oid;
-        if (!sha256 || !/^[0-9a-f]{64}$/i.test(sha256))
-          throw new Error(`HF API returned an invalid LFS sha256 for ${s.rfilename}`);
-        lfs = { sha256: sha256.toLowerCase(), size: s.lfs.size };
-      }
-      if (!lfs && (!s.blobId || !/^[0-9a-f]{40}$/.test(s.blobId)))
-        throw new Error(`HF API returned an invalid git blob SHA-1 for ${s.rfilename}`);
-      return {
-        rfilename: s.rfilename,
-        size: lfs?.size ?? s.size ?? 0,
-        blobId: s.blobId ?? "",
-        lfs,
-      };
-    }),
-  };
-}
-
-/** Follow redirects manually so the Authorization header is DROPPED at
- *  the CDN hop — presigned S3/CloudFront URLs reject requests that
- *  carry it (the classic hub-client footgun). Range survives. */
-async function fetchBlob(
-  url: string, token: string | null, rangeStart: number,
-): Promise<Response> {
-  const range: Record<string, string> = {};
-  if (rangeStart > 0) range["range"] = `bytes=${rangeStart}-`;
-  const authed: Record<string, string> = { ...range };
-  if (token) authed["authorization"] = `Bearer ${token}`;
-  let res = await fetch(url, { redirect: "manual", headers: authed });
-  let hops = 0;
-  while (res.status >= 300 && res.status < 400 && hops < 5) {
-    const loc = res.headers.get("location");
-    if (!loc) break;
-    // no auth past the redirect — presigned URLs reject it
-    res = await fetch(new URL(loc, url).href, { redirect: "manual", headers: range });
-    hops++;
-  }
-  return res;
-}
-
-export async function downloadOne(
-  url: string, token: string | null, blobPath: string,
-  expected: { size: number; sha256?: string; sha1?: string; name: string },
-  onProgress?: DownloadOptions["onProgress"],
-): Promise<void> {
-  // Serialize concurrent writers (foreground get vs background auto-download)
-  // on this blob — both appending to one .incomplete corrupts it.
-  const release = acquireLock(blobPath, expected.name);
-  try {
-    await downloadOneLocked(url, token, blobPath, expected, onProgress);
-  } finally {
-    release();
-  }
-}
-
-async function downloadOneLocked(
-  url: string, token: string | null, blobPath: string,
-  expected: { size: number; sha256?: string; sha1?: string; name: string },
-  onProgress?: DownloadOptions["onProgress"],
-): Promise<void> {
-  const partPath = `${blobPath}.incomplete`;
-  let offset = existsSync(partPath) ? statSync(partPath).size : 0;
-  if (offset > expected.size) {
-    rmSync(partPath); // stale junk; start over
-    offset = 0;
-  }
-
-  // Streaming verification — resume re-hashes the existing prefix so the
-  // final digest always covers every byte on disk. Chunked reads: a resumed
-  // multi-GB blob must not be materialized as one allocation.
-  const sha256 = new Bun.CryptoHasher("sha256");
-  const sha1 = new Bun.CryptoHasher("sha1");
-  sha1.update(`blob ${expected.size}\0`);
-  if (offset > 0) {
-    const fd = openSync(partPath, "r");
-    try {
-      const buf = Buffer.alloc(8 * 2 ** 20);
-      let pos = 0;
-      while (pos < offset) {
-        const n = readSync(fd, buf, 0, Math.min(buf.length, offset - pos), pos);
-        if (n <= 0) break;
-        const chunk = buf.subarray(0, n);
-        sha256.update(chunk);
-        sha1.update(chunk);
-        pos += n;
-      }
-    } finally {
-      closeSync(fd);
-    }
-  }
-
-  if (offset < expected.size) {
-    const res = await fetchBlob(url, token, offset);
-    if (res.status === 200 && offset > 0) {
-      // server ignored Range — start the file (and hashes) over
-      rmSync(partPath);
-      return downloadOneLocked(url, token, blobPath, expected, onProgress);
-    }
-    if (res.status !== 200 && res.status !== 206)
-      throw new Error(`download failed (${res.status}) for ${expected.name}${authHint(res.status)}`);
-    const out = createWriteStream(partPath, { flags: offset > 0 ? "a" : "w" });
-    try {
-      for await (const chunk of res.body as ReadableStream<Uint8Array>) {
-        sha256.update(chunk);
-        sha1.update(chunk);
-        await new Promise<void>((resolve, reject) =>
-          out.write(chunk, (e) => (e ? reject(e) : resolve())),
-        );
-        offset += chunk.length;
-        onProgress?.(expected.name, offset, expected.size);
-      }
-    } finally {
-      await new Promise<void>((resolve) => out.end(() => resolve()));
-    }
-  }
-
-  if (expected.size === 0 && !existsSync(partPath)) await Bun.write(partPath, "");
-  if (offset !== expected.size) {
-    throw new Error(
-      `short download for ${expected.name}: ${offset} of ${expected.size} bytes ` +
-      `(.incomplete kept — rerun to resume)`,
-    );
-  }
-  const digestOk = expected.sha256
-    ? sha256.digest("hex") === expected.sha256
-    : expected.sha1
-      ? sha1.digest("hex") === expected.sha1
-      : true;
-  if (!digestOk) {
-    rmSync(partPath); // corrupt — never resume from it
-    throw new Error(`checksum mismatch for ${expected.name} — partial removed, rerun to retry`);
-  }
-  renameSync(partPath, blobPath);
-}
-
-/** Download (or complete) a model snapshot. Returns the snapshot path.
- *  Idempotent: verified blobs are never re-fetched; partial blobs
- *  resume with a Range request. */
-/** Process-global download tracker — the status page's /downloads
- *  endpoint reads this. Only downloads performed by THIS process are
- *  visible (a `mlx-bun get` in another terminal is not). */
-export interface DownloadStatus {
-  repoId: string;
-  state: "active" | "done" | "error";
-  currentFile: string | null;
-  receivedBytes: number;
-  totalBytes: number;
-  filesDone: number;
-  filesTotal: number;
-  /** Rolling-window transfer rate (server-measured, ~5 s window). */
-  bytesPerSec: number;
-  startedAt: number;
-  finishedAt: number | null;
-  error?: string;
-}
-const downloadLog: DownloadStatus[] = [];
-export function downloadsSnapshot(): DownloadStatus[] {
-  return downloadLog.slice(-5);
-}
-
-/** True when a download for this exact repoId is currently "active" in this
- *  process's tracker (used by the Hub's POST /api/hub/download to refuse a
- *  duplicate kick-off — same repoId, still running — rather than starting a
- *  second writer that would race the first on the same blob lockfile). */
-export function isDownloadActive(repoId: string): boolean {
-  return downloadLog.some((d) => d.repoId === repoId && d.state === "active");
-}
-
-export async function downloadModel(
-  repoId: string, opts: DownloadOptions = {},
-): Promise<string> {
-  const endpoint = opts.endpoint ?? ENDPOINT;
-  const revision = opts.revision ?? "main";
-  const token = opts.token === undefined ? hfToken() : opts.token;
-  const hub = opts.cacheDir ?? DEFAULT_HUB;
-
-  const listing = await listRepoFiles(repoId, { ...opts, token });
-  // Fail the whole download closed (not skip-and-continue) if the repo's
-  // file listing contains a path-traversal rfilename — see
-  // isSafeRepoFilename's doc comment. This gates BOTH the CLI and the web
-  // Hub's POST /api/hub/download (src/hub-rest.ts), which accepts any
-  // caller-supplied repo string with no allowlist of its own.
-  for (const f of listing.files) {
-    if (!isSafeRepoFilename(f.rfilename)) {
-      throw new Error(`${repoId}: refusing unsafe file path in repo listing: ${JSON.stringify(f.rfilename)}`);
-    }
-  }
-  const repoDir = join(hub, `models--${repoId.replaceAll("/", "--")}`);
-  const blobsDir = join(repoDir, "blobs");
-  const snapDir = join(repoDir, "snapshots", listing.sha);
-  mkdirSync(blobsDir, { recursive: true });
-  mkdirSync(join(repoDir, "refs"), { recursive: true });
-
-  // Preflight before the first network payload. This matters for direct
-  // Colibri artifacts (hundreds of GiB): discovering a full volume after the
-  // 140th shard is not a usable failure mode. Existing verified blobs and
-  // partial prefixes are credited exactly, so rerunning after interruption is
-  // both resumable and progressively cheaper.
-  const space = planDownloadSpace(listing.files, blobsDir);
-  if (space.remainingBytes > 0) {
-    const fs = statfsSync(blobsDir);
-    const availableBytes = fs.bavail * fs.bsize;
-    const requiredBytes = space.remainingBytes + DOWNLOAD_DISK_RESERVE_BYTES;
-    if (requiredBytes > availableBytes) {
-      throw new Error(
-        `insufficient disk space for ${repoId}: ${formatGib(space.remainingBytes)} ` +
-        `remains across ${space.remainingFiles} files, but only ` +
-        `${formatGib(availableBytes)} is available in ${hub} ` +
-        `(${formatGib(DOWNLOAD_DISK_RESERVE_BYTES)} safety reserve). ` +
-        `Free space or choose another cache directory, then rerun; ` +
-        `${formatGib(space.resumableBytes)} of partial data will resume.`,
-      );
-    }
-  }
-
-  const status: DownloadStatus = {
-    repoId, state: "active", currentFile: null,
-    receivedBytes: 0, totalBytes: listing.files.reduce((a, f) => a + f.size, 0),
-    filesDone: 0, filesTotal: listing.files.length,
-    bytesPerSec: 0, startedAt: Date.now(), finishedAt: null,
-  };
-  downloadLog.push(status);
-  let doneBytes = 0;
-  // Rolling ~5 s window of (time, receivedBytes) samples for the rate.
-  const samples: Array<[number, number]> = [];
-  const sampleRate = (bytes: number) => {
-    const now = performance.now();
-    samples.push([now, bytes]);
-    while (samples.length > 2 && now - samples[0]![0] > 5000) samples.shift();
-    const [t0, b0] = samples[0]!;
-    status.bytesPerSec = now > t0 ? ((bytes - b0) / (now - t0)) * 1000 : 0;
-  };
-
-  try {
-    for (const f of listing.files) {
-      const blobId = f.lfs?.sha256 ?? f.blobId;
-      if (!blobId) throw new Error(`no blob id for ${f.rfilename} (API response missing ?blobs=true data)`);
-      const blobPath = join(blobsDir, blobId);
-
-      if (!existsSync(blobPath) || statSync(blobPath).size !== f.size) {
-        const url = `${endpoint}/${repoId}/resolve/${listing.sha}/${f.rfilename}`;
-        status.currentFile = f.rfilename;
-        await downloadOne(url, token, blobPath, {
-          size: f.size, name: f.rfilename,
-          ...(f.lfs ? { sha256: f.lfs.sha256 } : { sha1: f.blobId }),
-        }, (file, received, total) => {
-          status.receivedBytes = doneBytes + received;
-          sampleRate(status.receivedBytes);
-          opts.onProgress?.(file, received, total);
-        });
-      }
-      doneBytes += f.size;
-      status.receivedBytes = doneBytes;
-      status.filesDone++;
-      status.currentFile = null;
-
-      const linkPath = join(snapDir, f.rfilename);
-      mkdirSync(dirname(linkPath), { recursive: true });
-      if (!existsSync(linkPath)) {
-        // relative target, depth-aware for nested rfilenames
-        const depth = f.rfilename.split("/").length - 1;
-        symlinkSync(join("../".repeat(depth + 2), "blobs", blobId), linkPath);
-      }
-    }
-    status.state = "done";
-    status.bytesPerSec = 0;
-    status.finishedAt = Date.now();
-  } catch (e) {
-    status.state = "error";
-    status.bytesPerSec = 0;
-    status.error = e instanceof Error ? e.message : String(e);
-    status.finishedAt = Date.now();
-    throw e;
-  }
-
-  await Bun.write(join(repoDir, "refs", revision), listing.sha);
-  return snapDir;
-}

package/src/embed.ts

@@ -1,77 +0,0 @@
-// Text-embedding entry point. Wraps Qwen3Model.embedPooled (last-token hidden →
-// L2-normalized vector) with the Qwen3-Embedding input convention so the CLI
-// (`mlx-bun embed`), the server (`/v1/embeddings`), and in-repo experiments all
-// produce the SAME vectors — the ones verified bit-exact vs mlx-lm in
-// tests/parity/qwen3-embed-parity.test.ts.
-
-import { Qwen3Model } from "./model/qwen3";
-import type { RuntimeModel } from "./model/factory";
-import type { LoadedTokenizer } from "./tokenizer";
-import * as ops from "./mlx/ops";
-
-/** <|endoftext|> — the token Qwen3-Embedding terminates every input with and
- *  pools the last position of. */
-export const EMBED_EOD = 151643;
-
-/** Only plain-Qwen3 (the Qwen3-Embedding backbone) exposes a pooled-embedding
- *  path today. Narrow the served RuntimeModel before embedding. */
-export function isEmbeddingModel(model: RuntimeModel): model is Qwen3Model {
-  return model instanceof Qwen3Model;
-}
-
-/** Qwen3-Embedding query format: a task instruction steers WHICH similarity axis
- *  the geometry reflects ("represent this for topic routing" vs "...for
- *  sentiment"). Documents are embedded raw; only queries get an instruction. */
-export function withInstruction(text: string, instruction?: string): string {
-  return instruction ? `Instruct: ${instruction}\nQuery:${text}` : text;
-}
-
-/** Tripwire: counts embedOne invocations (embedMany accrues via embedOne) so
- *  callers can assert the pipeline embeds exactly as many times as expected. */
-let embedCallCount = 0;
-
-/** Reset the embed tripwire counter to 0. */
-export function resetEmbedCounter(): void {
-  embedCallCount = 0;
-}
-
-/** Read the embed tripwire counter (total embedOne calls since last reset). */
-export function getEmbedCounter(): number {
-  return embedCallCount;
-}
-
-export interface EmbedResult {
-  /** L2-normalized embedding (length = model hidden size). */
-  vector: Float32Array;
-  /** Token count of the embedded input (incl. the EOD pooling token). */
-  tokens: number;
-}
-
-/** Embed one text. `instruction` (optional) applies the query format. */
-export function embedOne(
-  model: Qwen3Model,
-  tok: LoadedTokenizer,
-  text: string,
-  instruction?: string,
-): EmbedResult {
-  embedCallCount++;
-  // addSpecialTokens=false matches the bit-exact parity path (Qwen3 has no BOS;
-  // we append the EOD pooling token ourselves).
-  const ids = [...tok.encode(withInstruction(text, instruction), false), EMBED_EOD];
-  const idArr = ops.fromInt32(ids, [1, ids.length]);
-  const vec = model.embedPooled(idArr);
-  idArr.dispose();
-  const out = vec.toFloat32();
-  vec.dispose();
-  return { vector: out, tokens: ids.length };
-}
-
-/** Embed many texts (one forward each — the runtime is single-sequence). */
-export function embedMany(
-  model: Qwen3Model,
-  tok: LoadedTokenizer,
-  texts: string[],
-  instruction?: string,
-): EmbedResult[] {
-  return texts.map((t) => embedOne(model, tok, t, instruction));
-}

package/src/engine/admission.ts

@@ -1,59 +0,0 @@
-import type { Cancellation } from "../contracts/generation";
-import type { DisposableResource } from "../contracts/resources";
-import { throwIfCancelled } from "./cancellation";
-
-export class AdmissionRejected extends Error {
-  constructor() { super("admission queue is full"); this.name = "AdmissionRejected"; }
-}
-
-/** FIFO reservations. A cancelled waiter releases no active owner's capacity. */
-export class AdmissionPool {
-  #active = 0;
-  #closed = false;
-  #waiting: Array<{ resolve(lease: DisposableResource): void; reject(error: unknown): void; unsubscribe(): void }> = [];
-  constructor(readonly capacity: number, readonly maxQueued = 64) {
-    if (!Number.isSafeInteger(capacity) || capacity < 1 || !Number.isSafeInteger(maxQueued) || maxQueued < 0)
-      throw new Error("invalid admission capacity");
-  }
-  get active(): number { return this.#active; }
-  get queued(): number { return this.#waiting.length; }
-
-  acquire(cancellation?: Cancellation): Promise<DisposableResource> {
-    if (this.#closed) return Promise.reject(new Error("admission is closed"));
-    try { if (cancellation) throwIfCancelled(cancellation); }
-    catch (error) { return Promise.reject(error); }
-    if (this.#active < this.capacity) return Promise.resolve(this.#lease());
-    if (this.#waiting.length >= this.maxQueued) return Promise.reject(new AdmissionRejected());
-    return new Promise((resolve, reject) => {
-      const waiter = { resolve, reject, unsubscribe() {} };
-      this.#waiting.push(waiter);
-      waiter.unsubscribe = cancellation?.subscribe((reason) => {
-        const index = this.#waiting.indexOf(waiter);
-        if (index < 0) return;
-        this.#waiting.splice(index, 1);
-        waiter.unsubscribe();
-        reject(new Error(`admission cancelled: ${reason}`));
-      }) ?? (() => {});
-      if (!this.#waiting.includes(waiter)) waiter.unsubscribe();
-    });
-  }
-
-  #lease(): DisposableResource {
-    this.#active++;
-    let released = false;
-    return { dispose: () => {
-      if (released) return;
-      released = true;
-      this.#active--;
-      const next = this.#waiting.shift();
-      if (next) { next.unsubscribe(); next.resolve(this.#lease()); }
-    } };
-  }
-
-  close(): void {
-    this.#closed = true;
-    for (const waiter of this.#waiting.splice(0)) {
-      waiter.unsubscribe(); waiter.reject(new Error("admission is closed"));
-    }
-  }
-}

package/src/engine/cancellation.ts

@@ -1,38 +0,0 @@
-import type { CancelReason, Cancellation } from "../contracts/generation";
-
-export class GenerationCancelled extends Error {
-  constructor(readonly reason: CancelReason) {
-    super(`generation cancelled: ${reason}`);
-    this.name = "GenerationCancelled";
-  }
-}
-
-export function throwIfCancelled(cancellation: Cancellation): void {
-  if (cancellation.reason !== undefined) throw new GenerationCancelled(cancellation.reason);
-}
-
-export class CancellationSource implements Cancellation {
-  #reason: CancelReason | undefined;
-  #listeners = new Set<(reason: CancelReason) => void>();
-  get reason(): CancelReason | undefined { return this.#reason; }
-
-  subscribe(listener: (reason: CancelReason) => void): () => void {
-    if (this.#reason !== undefined) {
-      listener(this.#reason);
-      return () => {};
-    }
-    this.#listeners.add(listener);
-    return () => { this.#listeners.delete(listener); };
-  }
-
-  cancel(reason: CancelReason): void {
-    if (this.#reason !== undefined) return;
-    this.#reason = reason;
-    const listeners = [...this.#listeners];
-    this.#listeners.clear();
-    // A faulty observer cannot prevent the remaining owners from cancelling.
-    for (const listener of listeners) {
-      try { listener(reason); } catch { /* Observers do not own settlement. */ }
-    }
-  }
-}