@1agh/maude 0.41.0 → 0.42.0

package/apps/studio/export-dialog.tsx

@@ -3,8 +3,10 @@
  * @scope      apps/studio/export-dialog.tsx
  * @purpose    Native `<dialog>`-based export modal. Three controls — format,
  *             scope, per-format options — plus a Recent tab populated by
- *             `/_api/export-history`. Submit fires `POST /_api/export`, the
- *             response is piped to a Blob URL anchor download. `⌘E` opens
+ *             `/_api/export-history`. Submit POSTs `/_api/export-jobs` and
+ *             closes immediately (feature-background-export-notification-
+ *             center) — the main-shell notification center owns status/
+ *             progress/completion from there, not this dialog. `⌘E` opens
  *             the dialog from anywhere inside the canvas; `⌘⇧E` re-runs the
  *             most recent export without opening (T10 fast path).
  *
@@ -293,7 +295,9 @@ export function ExportDialogProvider({ children }: { children: ReactNode }): Rea
     dialogRef.current?.close();
   }, []);
 
-  // Pre-load history when the dialog opens; refresh after each export.
+  // Loaded when the dialog opens. Submit now closes the dialog immediately
+  // (the job runs in the background) instead of refreshing this in place —
+  // the next open picks up whatever's finished by then.
   const loadHistory = useCallback(async () => {
     try {
       if (isCrossOriginFramed()) {
@@ -364,10 +368,13 @@ export function ExportDialogProvider({ children }: { children: ReactNode }): Rea
       setStatus(null);
       try {
         if (isCrossOriginFramed()) {
-          // Bridge through the main shell — the iframe can't reach /_api/export
-          // (canvas origin 403s it). The parent runs the export + triggers the
-          // download, then replies with the saved filename or an error string.
-          const res = await bridgeRequest<{ ok?: boolean; filename?: string; error?: string }>(
+          // Bridge through the main shell — the iframe can't reach
+          // /_api/export-jobs (canvas origin 403s it, DDR-060). The parent
+          // enqueues the job and replies with the id immediately; the
+          // trusted main-shell notification center (which already owns the
+          // WS connection) is the single place status/progress/completion
+          // live from here — this dialog no longer polls or receives bytes.
+          const res = await bridgeRequest<{ ok?: boolean; jobId?: string; error?: string }>(
             'export-request',
             'export-result',
             { payload: { format, scope, options } }
@@ -376,11 +383,10 @@ export function ExportDialogProvider({ children }: { children: ReactNode }): Rea
             setStatus({ text: `Export failed: ${res.error || 'unknown'}`, isError: true });
             return;
           }
-          setStatus({ text: `Saved ${res.filename ?? 'export'}`, isError: false });
-          void loadHistory();
+          close();
           return;
         }
-        const r = await fetch('/_api/export', {
+        const r = await fetch('/_api/export-jobs', {
           method: 'POST',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ format, scope, options }),
@@ -390,20 +396,7 @@ export function ExportDialogProvider({ children }: { children: ReactNode }): Rea
           setStatus({ text: `Export failed: ${text || r.status}`, isError: true });
           return;
         }
-        const disp = r.headers.get('Content-Disposition') ?? '';
-        const filename =
-          /filename="([^"]+)"/.exec(disp)?.[1] ?? `export${FORMAT_META[format].defaultExt}`;
-        const blob = await r.blob();
-        const url = URL.createObjectURL(blob);
-        const a = document.createElement('a');
-        a.href = url;
-        a.download = filename;
-        document.body.appendChild(a);
-        a.click();
-        a.remove();
-        URL.revokeObjectURL(url);
-        setStatus({ text: `Saved ${filename}`, isError: false });
-        void loadHistory();
+        close();
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         setStatus({ text: `Export failed: ${msg}`, isError: true });
@@ -411,7 +404,7 @@ export function ExportDialogProvider({ children }: { children: ReactNode }): Rea
         setSubmitting(false);
       }
     },
-    [loadHistory]
+    [close]
   );
 
   const rerunLast = useCallback(async () => {

package/apps/studio/exporters/_runtime.ts

@@ -67,3 +67,107 @@ export function resolveExportRuntime(): string {
   }
   return runtime;
 }
+
+export interface SpawnShimOptions {
+  /** cwd for the spawned shim — callers pass `path.dirname(<SHIM>)`. */
+  cwd: string;
+  /** Aborts the render — kills the child process. */
+  signal?: AbortSignal;
+  /** Fired for each `MAUDE_PROGRESS {"current":N,"total":M}` stdout line. */
+  onProgress?: (update: { current: number; total: number }) => void;
+}
+
+export interface SpawnShimResult {
+  code: number;
+  /** stdout lines with `MAUDE_PROGRESS` lines filtered out (written-file paths etc.). */
+  stdoutLines: string[];
+  stderr: string;
+}
+
+const PROGRESS_LINE = /^MAUDE_PROGRESS (.+)$/;
+
+/**
+ * Spawn a render shim (`bin/_{png,pdf,svg,html,pptx,video}-playwright.mjs`)
+ * via a resolved node/bun runtime, reading stdout INCREMENTALLY (not
+ * buffered via `new Response(proc.stdout).text()`) so a `MAUDE_PROGRESS`
+ * line written mid-render reaches `onProgress` as soon as it's flushed,
+ * instead of only after the whole process exits. Non-progress lines
+ * (written-file paths, the existing per-adapter contract) collect into
+ * `stdoutLines` in the order they arrived. Exit-code handling stays with the
+ * caller — this returns the same shape the old `Promise.all([...text()])`
+ * block did, so adapters keep their existing `if (code !== 0) throw …`.
+ */
+export async function spawnShim(args: string[], opts: SpawnShimOptions): Promise<SpawnShimResult> {
+  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
+    cwd: opts.cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    signal: opts.signal,
+  });
+  // Bun.spawn's `signal` option kills the child on abort; this listener is a
+  // defensive fallback in case a given Bun build ignores it — cheap and
+  // idempotent (killing an already-exited process is a no-op).
+  const onAbort = () => {
+    try {
+      proc.kill();
+    } catch {
+      /* already exited */
+    }
+  };
+  opts.signal?.addEventListener('abort', onAbort);
+
+  const stderrPromise = new Response(proc.stderr).text();
+  const stdoutLines: string[] = [];
+  let buffer = '';
+  const consumeLine = (line: string) => {
+    if (!line) return;
+    const match = PROGRESS_LINE.exec(line);
+    if (!match) {
+      stdoutLines.push(line);
+      return;
+    }
+    try {
+      const update = JSON.parse(match[1]) as { current: number; total: number };
+      opts.onProgress?.(update);
+    } catch {
+      /* malformed progress line — drop it rather than treat it as a file path */
+    }
+  };
+
+  try {
+    const reader = proc.stdout.pipeThrough(new TextDecoderStream()).getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += value;
+      let newlineIdx = buffer.indexOf('\n');
+      while (newlineIdx !== -1) {
+        consumeLine(buffer.slice(0, newlineIdx).trim());
+        buffer = buffer.slice(newlineIdx + 1);
+        newlineIdx = buffer.indexOf('\n');
+      }
+    }
+    if (buffer.trim()) consumeLine(buffer.trim());
+  } finally {
+    opts.signal?.removeEventListener('abort', onAbort);
+  }
+
+  const [stderr, code] = await Promise.all([stderrPromise, proc.exited]);
+  return { code, stdoutLines, stderr };
+}
+
+/**
+ * `spawnShim()` + the exit-code check every adapter did identically
+ * (`if (code !== 0) throw new Error(...)`; `code review, /flow:done` — six
+ * near-copies collapsed into one). `args[0]` is the shim path by convention
+ * (every adapter builds it that way), used only for the error message.
+ */
+export async function runShim(args: string[], opts: SpawnShimOptions): Promise<string[]> {
+  const { code, stdoutLines, stderr } = await spawnShim(args, opts);
+  if (code !== 0) {
+    throw new Error(
+      `${path.basename(args[0])} exited ${code}: ${stderr.trim() || stdoutLines.join('\n').trim()}`
+    );
+  }
+  return stdoutLines;
+}

package/apps/studio/exporters/html.ts

@@ -11,10 +11,11 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import JSZip from 'jszip';
-import { exportShimPath, resolveExportRuntime } from './_runtime.ts';
+import { exportShimPath, runShim } from './_runtime.ts';
 import {
   canvasShellUrl,
   type ExportContext,
+  type ExportHooks,
   type ExportOptions,
   type ExportResult,
 } from './index.ts';
@@ -27,7 +28,8 @@ async function captureHtml(
   target: Extract<Target, { kind: 'element' }>,
   ctx: ExportContext,
   outDir: string,
-  timeoutSec: number
+  timeoutSec: number,
+  hooks?: ExportHooks
 ): Promise<string[]> {
   const args = [
     HTML_PLAYWRIGHT,
@@ -46,29 +48,18 @@ async function captureHtml(
     if (target.widen) args.push('--widen-to-artboard', '1');
     args.push('--out', path.join(outDir, `${target.canvasSlug}.html`));
   }
-  const proc = Bun.spawn([resolveExportRuntime(), ...args], {
+  return runShim(args, {
     cwd: path.dirname(HTML_PLAYWRIGHT),
-    stdout: 'pipe',
-    stderr: 'pipe',
+    signal: hooks?.signal,
+    onProgress: hooks?.onProgress,
   });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-  const code = await proc.exited;
-  if (code !== 0) {
-    throw new Error(`_html-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
-  }
-  return stdout
-    .split('\n')
-    .map((s) => s.trim())
-    .filter(Boolean);
 }
 
 export async function run(
   targets: Target[],
   options: ExportOptions,
-  ctx: ExportContext
+  ctx: ExportContext,
+  hooks?: ExportHooks
 ): Promise<ExportResult> {
   if (!targets.length) {
     return { filename: 'export.zip', contentType: 'application/zip', body: new Uint8Array(0) };
@@ -83,9 +74,10 @@ export async function run(
   const tmp = mkdtempSync(path.join(tmpdir(), 'maude-html-'));
   try {
     const written: string[] = [];
-    for (const t of elementTargets) {
-      const paths = await captureHtml(t, ctx, tmp, timeoutSec);
+    for (let i = 0; i < elementTargets.length; i += 1) {
+      const paths = await captureHtml(elementTargets[i], ctx, tmp, timeoutSec, hooks);
       written.push(...paths);
+      hooks?.onProgress?.({ current: i + 1, total: elementTargets.length });
     }
     if (!written.length) {
       return { filename: 'export.zip', contentType: 'application/zip', body: new Uint8Array(0) };

package/apps/studio/exporters/index.ts

@@ -74,8 +74,19 @@ export interface ExportResult {
   body: Uint8Array;
 }
 
+/** Progress + cancellation hooks threaded through to the shim-spawning layer. */
+export interface ExportHooks {
+  onProgress?: (update: { current: number; total: number }) => void;
+  signal?: AbortSignal;
+}
+
 export interface Adapter {
-  run(targets: Target[], options: ExportOptions, ctx: ExportContext): Promise<ExportResult>;
+  run(
+    targets: Target[],
+    options: ExportOptions,
+    ctx: ExportContext,
+    hooks?: ExportHooks
+  ): Promise<ExportResult>;
 }
 
 const REGISTRY: Record<Format, Adapter> = {
@@ -114,6 +125,7 @@ export async function runExport(args: {
   options: ExportOptions;
   resolve: Omit<ResolveScopeArgs, 'scope'>;
   ctx: ExportContext;
+  hooks?: ExportHooks;
 }): Promise<ExportResult> {
   // Thread the options bag into the resolver so submit-time selection /
   // active-artboard hints (DDR — selection-passthrough) win over the persisted
@@ -123,7 +135,7 @@ export async function runExport(args: {
   if (!adapter) {
     throw new Error(`unknown format: ${args.format}`);
   }
-  return adapter.run(targets, args.options, args.ctx);
+  return adapter.run(targets, args.options, args.ctx, args.hooks);
 }
 
 export type { Scope, Target };

package/apps/studio/exporters/jobs.ts

@@ -0,0 +1,334 @@
+// Background export job queue (feature-background-export-notification-center).
+//
+// Turns the previously-synchronous `POST /_api/export` into a backgroundable
+// operation: `enqueue()` returns immediately with a job id + a Promise that
+// resolves with the same `ExportResult` the old synchronous call produced, so
+// `/_api/export` stays byte-for-byte contract-unchanged (it just awaits the
+// Promise). `POST /_api/export-jobs` returns the id WITHOUT awaiting, and the
+// job progresses queued → running → done|failed in the background, emitting
+// `bus.emit('export:job', job)` on every transition so ws.ts can broadcast a
+// live snapshot to the notification center.
+//
+// Concurrency is capped by a small hand-rolled counting semaphore (same
+// "no new dependency" convention as `writeLocator()` in http.ts) so N
+// Playwright/Chromium-heavy renders don't all launch at once — MAUDE_EXPORT_
+// MAX_CONCURRENT (default 2) lets a quick PNG start while a slow PDF/video is
+// still running, without letting an unbounded number of Chromiums spawn.
+//
+// History persistence: the in-memory `jobs` Map IS the source of truth. The
+// on-disk `_export-history.json` ledger is re-derived from it (done/failed
+// jobs, newest-first, capped) and overwritten in one shot on every
+// completion — no read-modify-write, so concurrent completions can't drop
+// entries (the race the old api.ts loadExportHistory/appendExportHistory
+// pair had). The ledger is seeded from disk once at construction so history
+// survives a server restart even though job state itself doesn't.
+
+import { readFileSync } from 'node:fs';
+import { mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import type { Bus } from '../context.ts';
+import {
+  type ExportContext,
+  type ExportOptions,
+  type ExportResult,
+  type Format,
+  runExport,
+  type Scope,
+} from './index.ts';
+import type { ResolveScopeArgs } from './scope.ts';
+
+/** Extended shape of the old Phase 6.5 T10 history entry — additive fields only. */
+export interface ExportHistoryEntry {
+  format: string;
+  scope: string;
+  options?: Record<string, unknown>;
+  filename: string;
+  at: string;
+  id?: string;
+  status?: 'done' | 'failed';
+  startedAt?: string;
+  finishedAt?: string;
+  error?: string;
+}
+
+export type ExportJobStatus = 'queued' | 'running' | 'done' | 'failed';
+
+export interface ExportJob {
+  id: string;
+  format: Format;
+  scope: Scope;
+  options: ExportOptions;
+  status: ExportJobStatus;
+  progress?: { current: number; total: number };
+  createdAt: string;
+  startedAt?: string;
+  finishedAt?: string;
+  filename?: string;
+  contentType?: string;
+  error?: string;
+}
+
+export interface EnqueueArgs {
+  format: Format;
+  scope: Scope;
+  options: ExportOptions;
+  resolve: Omit<ResolveScopeArgs, 'scope'>;
+  ctx: ExportContext;
+}
+
+export type DownloadResult =
+  | { ok: true; bytes: Uint8Array; filename: string; contentType: string }
+  | { ok: false; reason: 'missing' | 'not-done' };
+
+export interface ExportJobQueue {
+  enqueue(args: EnqueueArgs): { id: string; result: Promise<ExportResult> };
+  get(id: string): ExportJob | undefined;
+  list(): ExportJob[];
+  loadHistory(): ExportHistoryEntry[];
+  getBytes(id: string): Promise<DownloadResult>;
+}
+
+const HISTORY_DEPTH = 20;
+const MAX_JOB_AGE_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_JOB_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Security fan-out finding (defender, /flow:done) — MEDIUM: `enqueue()` had
+ * no cap on queued/running jobs, so a flood of `POST /_api/export-jobs`
+ * (unauthenticated same-origin-omitted-Origin callers pass `sameOriginWrite`)
+ * could grow the in-memory Map and fill `_export-jobs/` on disk unbounded —
+ * the old synchronous `/_api/export` had natural backpressure (one render at
+ * a time from the client's own perspective) that the background queue
+ * removed. `MAX_PENDING` bounds queued+running jobs; `enqueue()` throws
+ * `ExportQueueFullError` past it and http.ts maps that to 429.
+ */
+const MAX_PENDING = Math.max(1, Number(process.env.MAUDE_EXPORT_MAX_QUEUED) || 20);
+
+/** Thrown by `enqueue()` when `MAX_PENDING` queued/running jobs are already in flight. */
+export class ExportQueueFullError extends Error {
+  constructor() {
+    super('export queue is full — too many pending exports, try again shortly');
+    this.name = 'ExportQueueFullError';
+  }
+}
+
+/** Small counting semaphore — no new dependency, mirrors writeLocator()'s style. */
+class Semaphore {
+  private active = 0;
+  private readonly waiters: Array<() => void> = [];
+
+  constructor(private readonly max: number) {}
+
+  async acquire(): Promise<() => void> {
+    if (this.active >= this.max) {
+      await new Promise<void>((resolve) => this.waiters.push(resolve));
+    }
+    this.active += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.active -= 1;
+      const next = this.waiters.shift();
+      if (next) next();
+    };
+  }
+}
+
+function isFinished(job: ExportJob): boolean {
+  return job.status === 'done' || job.status === 'failed';
+}
+
+export function createExportJobQueue(bus: Bus, designRoot: string): ExportJobQueue {
+  const jobsDir = path.join(designRoot, '_export-jobs');
+  const historyPath = path.join(designRoot, '_export-history.json');
+  const maxConcurrent = Math.max(1, Number(process.env.MAUDE_EXPORT_MAX_CONCURRENT) || 2);
+  const semaphore = new Semaphore(maxConcurrent);
+  const jobs = new Map<string, ExportJob>();
+
+  // Seed the ledger from disk ONCE — the only read of the history file. Every
+  // later persist derives fresh from `jobs` and overwrites; there is no
+  // subsequent read-then-write step, which is what eliminates the race.
+  try {
+    const raw = readFileSync(historyPath, 'utf8');
+    const parsed = JSON.parse(raw) as unknown;
+    if (Array.isArray(parsed)) {
+      for (const entry of parsed) {
+        if (!entry || typeof entry !== 'object') continue;
+        const e = entry as Record<string, unknown>;
+        const id = typeof e.id === 'string' && e.id ? e.id : crypto.randomUUID();
+        const finishedAt =
+          typeof e.finishedAt === 'string'
+            ? e.finishedAt
+            : typeof e.at === 'string'
+              ? e.at
+              : undefined;
+        jobs.set(id, {
+          id,
+          format: e.format as Format,
+          scope: e.scope as Scope,
+          options: (e.options as ExportOptions) ?? {},
+          status: e.status === 'failed' ? 'failed' : 'done',
+          createdAt: (e.startedAt as string) ?? finishedAt ?? new Date().toISOString(),
+          startedAt: e.startedAt as string | undefined,
+          finishedAt,
+          filename: e.filename as string | undefined,
+          error: e.error as string | undefined,
+        });
+      }
+    }
+  } catch {
+    /* no ledger yet, or unreadable — start empty */
+  }
+
+  // Orphaned `_export-jobs/*` dirs from a process that died mid-export — job
+  // state is in-memory only and doesn't survive a restart, so anything on
+  // disk from a prior run is stale. Best-effort, never blocks boot.
+  void rm(jobsDir, { recursive: true, force: true })
+    .catch(() => {})
+    .then(() => mkdir(jobsDir, { recursive: true }).catch(() => {}));
+
+  function emit(job: ExportJob): void {
+    bus.emit('export:job', { ...job });
+  }
+
+  function deriveHistory(): ExportHistoryEntry[] {
+    return Array.from(jobs.values())
+      .filter(isFinished)
+      .sort((a, b) => (b.finishedAt ?? '').localeCompare(a.finishedAt ?? ''))
+      .slice(0, HISTORY_DEPTH)
+      .map((j) => ({
+        id: j.id,
+        format: j.format,
+        scope: j.scope,
+        options: j.options,
+        filename: j.filename ?? '',
+        at: j.finishedAt ?? j.createdAt,
+        status: j.status as 'done' | 'failed',
+        startedAt: j.startedAt,
+        finishedAt: j.finishedAt,
+        error: j.error,
+      }));
+  }
+
+  async function persistAndEvict(): Promise<void> {
+    const history = deriveHistory();
+    await Bun.write(historyPath, JSON.stringify(history, null, 2));
+
+    // Evict bytes (+ the in-memory record) for anything that rolled past the
+    // cap, or aged out, whichever comes first.
+    const finished = Array.from(jobs.values())
+      .filter(isFinished)
+      .sort((a, b) => (b.finishedAt ?? '').localeCompare(a.finishedAt ?? ''));
+    const now = Date.now();
+    const stale = finished.filter((j, i) => {
+      if (i >= HISTORY_DEPTH) return true;
+      const finishedAt = j.finishedAt ? Date.parse(j.finishedAt) : Number.NaN;
+      return Number.isFinite(finishedAt) && now - finishedAt > MAX_JOB_AGE_MS;
+    });
+    for (const job of stale) {
+      jobs.delete(job.id);
+      await rm(path.join(jobsDir, job.id), { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
+  function enqueue(args: EnqueueArgs): { id: string; result: Promise<ExportResult> } {
+    let pending = 0;
+    for (const job of jobs.values()) {
+      if (job.status === 'queued' || job.status === 'running') pending += 1;
+    }
+    if (pending >= MAX_PENDING) throw new ExportQueueFullError();
+
+    const id = crypto.randomUUID();
+    const job: ExportJob = {
+      id,
+      format: args.format,
+      scope: args.scope,
+      options: args.options,
+      status: 'queued',
+      createdAt: new Date().toISOString(),
+    };
+    jobs.set(id, job);
+    emit(job);
+
+    const controller = new AbortController();
+
+    const result = (async (): Promise<ExportResult> => {
+      const release = await semaphore.acquire();
+      // Started here, not at enqueue — the timeout bounds RENDER time (the
+      // intent), not queue-wait time. A job can legitimately sit `queued`
+      // behind MAUDE_EXPORT_MAX_CONCURRENT other jobs for longer than
+      // DEFAULT_JOB_TIMEOUT_MS; arming the timer before the semaphore
+      // resolves would abort it before it ever ran (code-review finding,
+      // /flow:done).
+      const timer = setTimeout(() => controller.abort(), DEFAULT_JOB_TIMEOUT_MS);
+      try {
+        job.status = 'running';
+        job.startedAt = new Date().toISOString();
+        emit(job);
+
+        const res = await runExport({
+          format: args.format,
+          scope: args.scope,
+          options: args.options,
+          resolve: args.resolve,
+          ctx: args.ctx,
+          hooks: {
+            signal: controller.signal,
+            onProgress: (update) => {
+              job.progress = update;
+              emit(job);
+            },
+          },
+        });
+
+        job.status = 'done';
+        job.finishedAt = new Date().toISOString();
+        job.filename = res.filename;
+        job.contentType = res.contentType;
+        if (res.body.byteLength) {
+          const dir = path.join(jobsDir, id);
+          await mkdir(dir, { recursive: true });
+          await Bun.write(path.join(dir, res.filename), res.body);
+        }
+        emit(job);
+        await persistAndEvict();
+        return res;
+      } catch (err) {
+        job.status = 'failed';
+        job.finishedAt = new Date().toISOString();
+        job.error = err instanceof Error ? err.message : String(err);
+        emit(job);
+        await persistAndEvict();
+        throw err;
+      } finally {
+        clearTimeout(timer);
+        release();
+      }
+    })();
+
+    return { id, result };
+  }
+
+  return {
+    enqueue,
+    get: (id) => jobs.get(id),
+    list: () => Array.from(jobs.values()).sort((a, b) => b.createdAt.localeCompare(a.createdAt)),
+    loadHistory: deriveHistory,
+    async getBytes(id) {
+      const job = jobs.get(id);
+      if (!job) return { ok: false, reason: 'missing' };
+      if (job.status !== 'done') return { ok: false, reason: 'not-done' };
+      if (!job.filename) return { ok: false, reason: 'missing' };
+      const file = Bun.file(path.join(jobsDir, id, job.filename));
+      if (!(await file.exists())) return { ok: false, reason: 'missing' };
+      return {
+        ok: true,
+        bytes: new Uint8Array(await file.arrayBuffer()),
+        filename: job.filename,
+        contentType: job.contentType ?? 'application/octet-stream',
+      };
+    },
+  };
+}