@bevel-software/platform-core-backend 0.32.0 → 0.34.0

package/src/modules/workspace/agent-access.gate.ts

@@ -19,9 +19,9 @@
  * all branches and to reads).
  */
 
-import type { JsonSchema } from '../tool-registry/tool.contract.js';
-import type { ToolContext } from '../tool-helpers/tool.contract.js';
-import type { WorkflowHooks } from '../workflow/workflow-hooks.js';
+import type { JsonSchema } from '../tool-registry/index.js';
+import type { ToolContext } from '../tool-helpers/index.js';
+import type { WorkflowHooks } from '../workflow/index.js';
 
 /**
  * What the `sessionId` input says on its own, before any deployment note. The

package/src/modules/workspace/agent-download.builder.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import AdmZip from 'adm-zip';
-import { hasHttpStatus, ToolError } from '../tool-helpers/tool.contract.js';
+import { hasHttpStatus, ToolError } from '../tool-helpers/index.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { DownloadArtifact } from './agent-download.store.js';
 

package/src/modules/workspace/agent-upload.routes.ts

@@ -135,6 +135,25 @@ export function createAgentUploadRoutes(deps: AgentUploadRouteDeps): express.Rou
   router.post(AGENT_UPLOAD_ROUTE, handle);
   router.post(AGENT_UPLOAD_HEADER_ROUTE, handle);
 
+  // `DELETE /api/agent/uploads` with the token in `x-upload-token`: give the
+  // token up unapplied, and its bytes with it, now rather than at its expiry
+  // (see `AgentUploadStore.discard`). The app sends it when a page's
+  // `uploadFile` was refused, since nobody else holds that token to retry.
+  // Header form only: the token stays out of the address here too.
+  router.delete(AGENT_UPLOAD_HEADER_ROUTE, async (req, res) => {
+    try {
+      await uploads.discard(tokenOf(req));
+      res.status(204).end();
+    } catch (err) {
+      if (err instanceof UploadTokenError) {
+        res.status(err.status).json({ error: err.message });
+        return;
+      }
+      log.error('discarding an upload failed:', { err });
+      res.status(500).json({ error: 'Discarding the upload failed' });
+    }
+  });
+
   return router;
 }
 

package/src/modules/workspace/agent-upload.store.ts

@@ -417,6 +417,24 @@ export class AgentUploadStore {
     }
   }
 
+  /**
+   * Give `token` up unapplied: spend it and delete any bytes sent with it NOW,
+   * rather than when it expires. For a caller that will not retry — the app
+   * answering a page's `uploadFile`, which holds the token on the page's behalf
+   * and drops it when the upload or the apply is refused.
+   *
+   * Refused with the one refusal, like every unusable token, and also while
+   * the token is busy — bytes still arriving, or an apply holding it — so a
+   * discard never deletes a file somebody is writing or reading.
+   */
+  async discard(token: string): Promise<void> {
+    const record = this.find(token);
+    // `attaching` stays set once the bytes are in; only without `received` are they still arriving.
+    const arriving = record.attaching && record.received === undefined;
+    if (arriving || record.claimed) throw new UploadTokenError(UPLOAD_TOKEN_REFUSAL, 404);
+    await this.consume(token);
+  }
+
   /** Spend the token and delete its bytes. Idempotent. */
   async consume(token: string): Promise<void> {
     const key = hash(token);

package/src/modules/workspace/file-readers/README.md

@@ -8,6 +8,15 @@ under an `[extracted text of …]` marker whose summary states what was left out
 When an extractor's OUTPUT changes, bump `EXTRACTION_SCHEMA` in
 `doc-extract.service.ts` so cached extractions of unchanged bytes refresh.
 
+No extractor runs on the server's request thread: `DocExtractService` hands the
+bytes to `WorkerDocumentExtractor` (`extract-in-worker.ts`), a pool of worker
+threads running `extract.worker.ts` (the table in `document-extractors.ts`)
+under a 10-second budget per file. A failed extraction is cached under the same
+key — a parser's refusal for good, a timeout or crash for an hour — and a fresh
+failure is reported as the `document-unreadable` event. A new format is added
+to `document-formats.ts` and to the worker's table; the compiler holds the two
+together.
+
 ## Word (`.docx`)
 
 - Paragraphs become lines; table rows become lines of tab-separated cells.

package/src/modules/workspace/file-readers/__tests__/doc-extract.service.test.ts

@@ -0,0 +1,175 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { DocExtractService, TIMEOUT_MEMORY_MS, type UnreadableDocument } from '../doc-extract.service.js';
+import type { IDocumentExtractor, IsolatedExtraction } from '../document-extractor.contract.js';
+import { WorkerDocumentExtractor } from '../extract-in-worker.js';
+import { xrefPdf } from './fixtures/damaged-pdf.js';
+
+/**
+ * What `DocExtractService` remembers about a failed extraction, and whom it
+ * tells: a parser's refusal for good, a timeout or crash for an hour, "busy"
+ * not at all; a fresh failure reported once, a remembered one never.
+ */
+
+/** An extractor that answers what each test scripts, and counts the extractions it was asked for. */
+function scriptedExtractor(answer: (extension: string, bytes: Buffer) => IsolatedExtraction): IDocumentExtractor & { calls: number } {
+  return {
+    calls: 0,
+    async extract(extension, bytes) {
+      this.calls++;
+      return answer(extension, bytes);
+    },
+    close: async () => {},
+  };
+}
+
+const TIMEOUT: IsolatedExtraction = {
+  ok: false,
+  failure: 'timeout',
+  message: 'could not be read: extracting its text took longer than 10 seconds',
+};
+const ORIGIN = { workspaceId: 'main' };
+
+let cacheRoot = '';
+let clock = 0;
+let told: UnreadableDocument[] = [];
+const now = () => clock;
+const onUnreadable = (doc: UnreadableDocument) => told.push(doc);
+
+beforeEach(async () => {
+  cacheRoot = await mkdtemp(join(tmpdir(), 'doc-extract-service-'));
+  clock = 1_800_000_000_000;
+  told = [];
+});
+afterEach(() => rm(cacheRoot, { recursive: true, force: true }));
+
+describe('DocExtractService — a damaged PDF, through the real worker', () => {
+  let extractor: WorkerDocumentExtractor;
+  beforeEach(() => {
+    extractor = new WorkerDocumentExtractor();
+  });
+  afterEach(() => extractor.close());
+
+  it('is extracted once; every later read and the cheap lookup answer the remembered notice', async () => {
+    let extractions = 0;
+    const counting: IDocumentExtractor = {
+      extract: (ext, bytes) => {
+        extractions++;
+        return extractor.extract(ext, bytes);
+      },
+      close: () => extractor.close(),
+    };
+    const service = new DocExtractService(cacheRoot, counting, { now, onUnreadable });
+    const pdf = xrefPdf('Hello', { damage: true });
+    const first = await service.extract('kb/Supplier-Agreement.pdf', pdf, ORIGIN);
+    expect(first).toEqual({ ok: false, message: "could not extract the PDF's text (Bad (uncompressed) XRef entry: 4R)" });
+    expect(await service.extract('kb/Supplier-Agreement.pdf', pdf, ORIGIN)).toEqual(first);
+    expect(await service.getCached('kb/Supplier-Agreement.pdf', pdf)).toEqual(first);
+    expect(extractions).toBe(1);
+    // Told once, for the fresh failure only — under the reason the explorer shows.
+    expect(told).toEqual([
+      { workspaceId: 'main', path: 'kb/Supplier-Agreement.pdf', reason: "could not extract the PDF's text (Bad (uncompressed) XRef entry: 4R)" },
+    ]);
+  });
+
+  it('extracts the repaired file — new content — and reads it normally', async () => {
+    const service = new DocExtractService(cacheRoot, extractor, { now, onUnreadable });
+    await service.extract('a.pdf', xrefPdf('Hello', { damage: true }), ORIGIN);
+    const repaired = await service.extract('a.pdf', xrefPdf('Hello', { damage: false }), ORIGIN);
+    expect(repaired).toMatchObject({ ok: true, text: '[page 1]\nHello' });
+  });
+});
+
+describe('DocExtractService — how long a failure is remembered', () => {
+  it('remembers a parser failure for good — even long past an hour', async () => {
+    const extractor = scriptedExtractor(() => ({ ok: false, failure: 'parser', message: 'could not be parsed as a PDF (x)' }));
+    const service = new DocExtractService(cacheRoot, extractor, { now });
+    const bytes = Buffer.from('damaged');
+    await service.extract('a.pdf', bytes);
+    clock += 30 * TIMEOUT_MEMORY_MS;
+    expect(await service.extract('a.pdf', bytes)).toEqual({ ok: false, message: 'could not be parsed as a PDF (x)' });
+    expect(extractor.calls).toBe(1);
+  });
+
+  it('remembers a timeout for one hour, then extracts again', async () => {
+    let answer: IsolatedExtraction = TIMEOUT;
+    const extractor = scriptedExtractor(() => answer);
+    const service = new DocExtractService(cacheRoot, extractor, { now, onUnreadable });
+    const bytes = Buffer.from('slow');
+    expect(await service.extract('big.pdf', bytes, ORIGIN)).toEqual({ ok: false, message: TIMEOUT.message });
+    // Within the hour: the notice, at once, from every read and from the cheap lookup.
+    clock += TIMEOUT_MEMORY_MS - 1;
+    expect(await service.extract('big.pdf', bytes, ORIGIN)).toEqual({ ok: false, message: TIMEOUT.message });
+    expect(await service.getCached('big.pdf', bytes)).toEqual({ ok: false, message: TIMEOUT.message });
+    expect(extractor.calls).toBe(1);
+    // After it: tried again, and this time the server had the moment to spare.
+    clock += 1;
+    expect(await service.getCached('big.pdf', bytes)).toBeUndefined();
+    answer = { ok: true, summary: '1 page', text: '[page 1]\nfinally' };
+    expect(await service.extract('big.pdf', bytes, ORIGIN)).toMatchObject({ ok: true, text: '[page 1]\nfinally' });
+    expect(extractor.calls).toBe(2);
+    expect(told).toEqual([{ workspaceId: 'main', path: 'big.pdf', reason: 'extracting its text took longer than 10 seconds' }]);
+  });
+
+  it('remembers a crashed extraction for an hour, like a timeout', async () => {
+    const extractor = scriptedExtractor(() => ({ ok: false, failure: 'crashed', message: 'could not be read: its extraction stopped unexpectedly (exit code 3)' }));
+    const service = new DocExtractService(cacheRoot, extractor, { now });
+    const bytes = Buffer.from('oom');
+    await service.extract('a.pdf', bytes);
+    await service.extract('a.pdf', bytes);
+    expect(extractor.calls).toBe(1);
+    clock += TIMEOUT_MEMORY_MS;
+    await service.extract('a.pdf', bytes);
+    expect(extractor.calls).toBe(2);
+  });
+
+  it('remembers nothing, and tells no one, when no worker was free', async () => {
+    const extractor = scriptedExtractor(() => ({ ok: false, failure: 'busy', message: 'could not be read: too many documents are being extracted at once; try again in a few seconds' }));
+    const service = new DocExtractService(cacheRoot, extractor, { now, onUnreadable });
+    const bytes = Buffer.from('fine');
+    expect((await service.extract('a.pdf', bytes, ORIGIN)).ok).toBe(false);
+    expect(await service.getCached('a.pdf', bytes)).toBeUndefined();
+    await service.extract('a.pdf', bytes, ORIGIN);
+    expect(extractor.calls).toBe(2);
+    expect(told).toEqual([]);
+  });
+
+  it('tells no one about a failure of a read with no origin', async () => {
+    const extractor = scriptedExtractor(() => TIMEOUT);
+    const service = new DocExtractService(cacheRoot, extractor, { now, onUnreadable });
+    await service.extract('a.pdf', Buffer.from('x'));
+    expect(told).toEqual([]);
+  });
+
+  it('tells once when two reads of the same document fail together', async () => {
+    const extractor = scriptedExtractor(() => TIMEOUT);
+    const service = new DocExtractService(cacheRoot, extractor, { now, onUnreadable });
+    const bytes = Buffer.from('twice');
+    await Promise.all([service.extract('a.pdf', bytes, ORIGIN), service.extract('a.pdf', bytes, ORIGIN)]);
+    expect(extractor.calls).toBe(1);
+    expect(told).toHaveLength(1);
+  });
+
+  it('two reads of the same bytes at different paths share one extraction, and each marker names its own path', async () => {
+    const extractor = scriptedExtractor(() => ({ ok: true, summary: '1 page', text: '[page 1]\nshared' }));
+    const service = new DocExtractService(cacheRoot, extractor, { now, onUnreadable });
+    const bytes = Buffer.from('same bytes, two names');
+    const [a, b] = await Promise.all([service.extract('a/deck.pdf', bytes, ORIGIN), service.extract('b/copy.pdf', bytes, ORIGIN)]);
+    expect(extractor.calls).toBe(1);
+    expect(a).toEqual({ ok: true, marker: '[extracted text of a/deck.pdf — 1 page]', text: '[page 1]\nshared' });
+    expect(b).toEqual({ ok: true, marker: '[extracted text of b/copy.pdf — 1 page]', text: '[page 1]\nshared' });
+  });
+
+  it('still answers the read when whoever is told throws', async () => {
+    const extractor = scriptedExtractor(() => TIMEOUT);
+    const service = new DocExtractService(cacheRoot, extractor, {
+      now,
+      onUnreadable: () => {
+        throw new Error('listener broke');
+      },
+    });
+    expect(await service.extract('a.pdf', Buffer.from('x'), ORIGIN)).toEqual({ ok: false, message: TIMEOUT.message });
+  });
+});

package/src/modules/workspace/file-readers/__tests__/doc-extract.test.ts

@@ -7,18 +7,18 @@ import AdmZip from 'adm-zip';
 import * as XLSX from 'xlsx';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { extractDocx } from '../extract-docx.js';
-import { extractPptx } from '../extract-pptx.js';
+import { extractPptx, notesTargetFromRels } from '../extract-pptx.js';
 import { extractXlsx } from '../extract-xlsx.js';
 import { extractPdf } from '../extract-pdf.js';
 import { extractOdt } from '../extract-odt.js';
 import { extractOdp } from '../extract-odp.js';
 import { extractOds } from '../extract-ods.js';
 import { DocExtractService, EXTRACTION_SCHEMA } from '../doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../extract-in-worker.js';
 import { DocExtractionCache, gitBlobSha } from '../extraction-cache.js';
 import { fileExtension } from '../doc-extract.types.js';
 import { MAX_ODF_NS_ALIASES, normalizeOdfPrefixes, odfParagraphBlocks } from '../odf-text.js';
 import { decodeXmlEntities, xmlAttrValue, xmlAttrValueByLocalName } from '../ooxml-text.js';
-import { notesTargetFromRels } from '../extract-pptx.js';
 
 /**
  * REAL fixtures, no mocks: docx/pptx are handcrafted OOXML zips built with
@@ -612,7 +612,7 @@ describe('DocExtractService cache', () => {
 
   beforeEach(async () => {
     cacheRoot = await mkdtemp(join(tmpdir(), 'doc-extract-cache-'));
-    service = new DocExtractService(cacheRoot);
+    service = new DocExtractService(cacheRoot, new WorkerDocumentExtractor());
   });
   afterEach(async () => {
     await rm(cacheRoot, { recursive: true, force: true });
@@ -620,7 +620,7 @@ describe('DocExtractService cache', () => {
 
   it('extracts ONCE per content: the second read is served from the cache file', async () => {
     const bytes = docxBytes(para('Cache me once'));
-    const first = await service.extract('a.docx', bytes, extractDocx);
+    const first = await service.extract('a.docx', bytes);
     expect(first.ok).toBe(true);
     const entries = await readdir(cacheRoot);
     expect(entries).toEqual([`${gitBlobSha(bytes)}.docx.${EXTRACTION_SCHEMA}.json`]);
@@ -629,7 +629,7 @@ describe('DocExtractService cache', () => {
     // text, it came from the cache — the parser did NOT run again. (Real-files
     // proof without spying on module internals.)
     await writeFile(join(cacheRoot, entries[0]), JSON.stringify({ summary: 'tampered summary', text: 'FROM CACHE' }), 'utf8');
-    const second = await service.extract('a.docx', bytes, extractDocx);
+    const second = await service.extract('a.docx', bytes);
     if (!second.ok) throw new Error(second.message);
     expect(second.text).toBe('FROM CACHE');
     expect(second.marker).toBe('[extracted text of a.docx — tampered summary]');
@@ -638,9 +638,9 @@ describe('DocExtractService cache', () => {
   it('is invalidated by CONTENT change (new blob sha → fresh extraction, new entry)', async () => {
     const v1 = docxBytes(para('version one'));
     const v2 = docxBytes(para('version two'));
-    await service.extract('a.docx', v1, extractDocx);
+    await service.extract('a.docx', v1);
     const after1 = await readdir(cacheRoot);
-    const res = await service.extract('a.docx', v2, extractDocx);
+    const res = await service.extract('a.docx', v2);
     if (!res.ok) throw new Error(res.message);
     expect(res.text).toBe('version two');
     const after2 = await readdir(cacheRoot);
@@ -650,9 +650,9 @@ describe('DocExtractService cache', () => {
 
   it('keys by content, not path: the same bytes under another path reuse the entry, marker names the read path', async () => {
     const bytes = docxBytes(para('Shared content'));
-    await service.extract('one.docx', bytes, extractDocx);
+    await service.extract('one.docx', bytes);
     expect(await readdir(cacheRoot)).toHaveLength(1);
-    const other = await service.extract('two/other.docx', bytes, extractDocx);
+    const other = await service.extract('two/other.docx', bytes);
     if (!other.ok) throw new Error(other.message);
     expect(other.marker).toMatch(/^\[extracted text of two\/other\.docx — /);
     expect(await readdir(cacheRoot)).toHaveLength(1);
@@ -661,15 +661,20 @@ describe('DocExtractService cache', () => {
   it('getCached misses before extraction and hits after — the grep budget contract', async () => {
     const bytes = docxBytes(para('Budget line'));
     expect(await service.getCached('a.docx', bytes)).toBeUndefined();
-    await service.extract('a.docx', bytes, extractDocx);
+    await service.extract('a.docx', bytes);
     const hit = await service.getCached('a.docx', bytes);
     expect(hit?.text).toBe('Budget line');
   });
 
-  it('does NOT cache failures — a corrupt file is re-tried on the next read', async () => {
-    const res = await service.extract('bad.docx', Buffer.from('junk'), extractDocx);
+  it('remembers a parser failure under the content key — a corrupt file is answered from the cache', async () => {
+    // Reversed on purpose (Damaged-Document-Never-Hangs): a damaged file was
+    // extracted again on every read and every grep; now its failure is kept
+    // like a success, and the cheap lookup answers it too.
+    const junk = Buffer.from('junk');
+    const res = await service.extract('bad.docx', junk);
     expect(res.ok).toBe(false);
-    expect(await readdir(cacheRoot)).toHaveLength(0);
+    expect(await readdir(cacheRoot)).toEqual([`${gitBlobSha(junk)}.docx.${EXTRACTION_SCHEMA}.json`]);
+    expect(await service.getCached('bad.docx', junk)).toEqual(res);
   });
 
   it('computes the git blob sha (matches `git hash-object`)', async () => {
@@ -679,7 +684,7 @@ describe('DocExtractService cache', () => {
 
   it('the cached entry on disk is the {summary, text} JSON', async () => {
     const bytes = docxBytes(para('On disk'));
-    await service.extract('a.docx', bytes, extractDocx);
+    await service.extract('a.docx', bytes);
     const raw = JSON.parse(await readFile(join(cacheRoot, `${gitBlobSha(bytes)}.docx.${EXTRACTION_SCHEMA}.json`), 'utf8')) as { summary: string; text: string };
     expect(raw.text).toBe('On disk');
     expect(typeof raw.summary).toBe('string');
@@ -694,12 +699,12 @@ describe('DocExtractService cache', () => {
         `${odsCell('cell')}` +
         '</table:table-row></table:table></office:text>',
     );
-    const asOdt = await service.extract('doc.odt', bytes, extractOdt);
+    const asOdt = await service.extract('doc.odt', bytes);
     if (!asOdt.ok) throw new Error(asOdt.message);
     expect(asOdt.text).toContain('Prose line');
 
     // Same bytes, renamed .ods: the odt extraction must NOT come back.
-    const asOds = await service.extract('doc.ods', bytes, extractOds);
+    const asOds = await service.extract('doc.ods', bytes);
     if (!asOds.ok) throw new Error(asOds.message);
     expect(asOds.text.split('\n')[0]).toBe('[sheet: Grid]');
     expect(asOds.marker).toContain('sheet');

package/src/modules/workspace/file-readers/__tests__/extract-in-worker.test.ts

@@ -0,0 +1,229 @@
+import { readFile } from 'node:fs/promises';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { extractionTimeoutNotice } from '../document-extractor.contract.js';
+import { extractDocx } from '../extract-docx.js';
+import { EXTRACTION_BUDGET_MS, EXTRACTION_WORKER_FAILED, WorkerDocumentExtractor, type ExtractionWorkerEntry } from '../extract-in-worker.js';
+import { extractPdf } from '../extract-pdf.js';
+import { xrefPdf } from './fixtures/damaged-pdf.js';
+
+/**
+ * The extraction worker kind: every document's extractor runs in a pooled
+ * worker thread under a budget, and nothing a parser does — an error, a
+ * rejection it never hands back, a loop, a crash — reaches this process.
+ */
+
+/** A worker module from this suite's fixtures, loaded as the suites are (TypeScript, through tsx). */
+function fixtureEntry(name: string): ExtractionWorkerEntry {
+  return { url: new URL(`./fixtures/${name}`, import.meta.url), execArgv: ['--import', 'tsx'] };
+}
+
+/** Every unhandled rejection and uncaught exception THIS process sees while a test runs. */
+let processSaw: unknown[] = [];
+const onRejection = (reason: unknown) => processSaw.push(reason);
+const onException = (err: unknown) => processSaw.push(err);
+beforeEach(() => {
+  processSaw = [];
+  process.on('unhandledRejection', onRejection);
+  process.on('uncaughtException', onException);
+});
+afterEach(() => {
+  process.off('unhandledRejection', onRejection);
+  process.off('uncaughtException', onException);
+});
+
+describe('WorkerDocumentExtractor — the real document extractors', () => {
+  let extractor: WorkerDocumentExtractor;
+  beforeEach(() => {
+    extractor = new WorkerDocumentExtractor();
+  });
+  afterEach(() => extractor.close());
+
+  it('budgets ten seconds per file by default, and words a timeout as the ticket does', () => {
+    expect(EXTRACTION_BUDGET_MS).toBe(10_000);
+    expect(extractionTimeoutNotice(EXTRACTION_BUDGET_MS)).toBe(
+      'could not be read: extracting its text took longer than 10 seconds',
+    );
+  });
+
+  it('answers a PDF with a damaged cross-reference table with pdf.js’s own message, as a parser failure', async () => {
+    const res = await extractor.extract('.pdf', xrefPdf('Hello', { damage: true }));
+    expect(res).toEqual({
+      ok: false,
+      failure: 'parser',
+      message: "could not extract the PDF's text (Bad (uncompressed) XRef entry: 4R)",
+    });
+    // Long enough for any rejection pdf.js left behind to have surfaced.
+    await new Promise((r) => setTimeout(r, 50));
+    expect(processSaw).toEqual([]);
+  });
+
+  it('extracts a sound document exactly as the extractor does on its own — same text, same summary', async () => {
+    const pdf = xrefPdf('Hello PDF world', { damage: false });
+    const docx = await readFile(new URL('./fixtures/tab.docx', import.meta.url));
+    const inProcess = [await extractPdf(pdf), await extractDocx(docx)];
+    const inWorker = [await extractor.extract('.pdf', pdf), await extractor.extract('.docx', docx)];
+    expect(inWorker).toEqual(inProcess);
+    expect(inWorker[0]).toMatchObject({ ok: true, text: '[page 1]\nHello PDF world' });
+  });
+
+  it('leaves the caller’s buffer as it was — the worker gets a copy', async () => {
+    const pdf = xrefPdf('Keep me', { damage: false });
+    const before = Buffer.from(pdf);
+    await extractor.extract('.pdf', pdf);
+    expect(pdf.byteLength).toBe(before.byteLength);
+    expect(pdf.equals(before)).toBe(true);
+  });
+});
+
+describe('WorkerDocumentExtractor — a parser that misbehaves', () => {
+  let extractor: WorkerDocumentExtractor;
+  afterEach(() => extractor.close());
+
+  it('turns a rejection the parser never hands back into the job’s failure — this process sees none', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts') });
+    const res = await extractor.extract('.dangling', Buffer.from('x'));
+    expect(res).toEqual({
+      ok: false,
+      failure: 'parser',
+      message: 'could not be extracted (XRefEntryException: Bad (uncompressed) XRef entry)',
+    });
+    await new Promise((r) => setTimeout(r, 50));
+    expect(processSaw).toEqual([]);
+    // The worker it happened in is retired; the next job gets a sound one.
+    expect(await extractor.extract('.echo', Buffer.from('after'))).toMatchObject({ ok: true, text: 'after' });
+  });
+
+  it('keeps a rejection left behind AFTER an answer out of this process and out of the next job', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts'), poolMax: 1 });
+    expect(await extractor.extract('.straggler', Buffer.from('x'))).toMatchObject({ ok: true, text: 'answered first' });
+    await new Promise((r) => setTimeout(r, 100));
+    expect(await extractor.extract('.echo', Buffer.from('next'))).toMatchObject({ ok: true, text: 'next' });
+    expect(processSaw).toEqual([]);
+  });
+
+  it('never pins an earlier job’s late rejection on the job the worker runs next — reused at once', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts'), poolMax: 1 });
+    expect(await extractor.extract('.straggler', Buffer.from('x'))).toMatchObject({ ok: true, text: 'answered first' });
+    // No pause: the one worker gets this job straight away, and the straggler lands while it runs.
+    expect(await extractor.extract('.slow-echo', Buffer.from('mine'))).toEqual({ ok: true, summary: 'echo', text: 'mine' });
+    expect(processSaw).toEqual([]);
+  });
+
+  it('never answers the next job as crashed when the worker ends itself over a straggler between jobs', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts'), poolMax: 1 });
+    expect(await extractor.extract('.straggler-between-jobs', Buffer.from('x'))).toMatchObject({ ok: true });
+    // The one worker is handed this job at once, and exits (code 0) before taking it up:
+    // the job runs again in a fresh worker and is answered as its own.
+    expect(await extractor.extract('.echo', Buffer.from('mine'))).toEqual({ ok: true, summary: 'echo', text: 'mine' });
+    expect(processSaw).toEqual([]);
+  });
+
+  it('gives a job rerun over another file’s straggler the whole budget again, not what was left', async () => {
+    // Budget 1500 ms. The straggler lands 600 ms into the next job, which
+    // needs 1100 ms: the 900 ms the budget had left would not do, the whole
+    // budget does. A rerun on the leftover would time out a sound document
+    // and remember that timeout for an hour.
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts'), poolMax: 1, budgetMs: 1500 });
+    expect(await extractor.extract('.straggler-late', Buffer.from('x'))).toMatchObject({ ok: true, text: 'answered first' });
+    // No pause: the one worker gets this job straight away, and the straggler lands while it runs.
+    expect(await extractor.extract('.slow-echo-long', Buffer.from('mine'))).toEqual({ ok: true, summary: 'echo', text: 'mine' });
+    expect(processSaw).toEqual([]);
+  }, 10_000);
+
+  it('still pins a rejection on its own job when the worker had served another first', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts'), poolMax: 1 });
+    expect(await extractor.extract('.echo', Buffer.from('warm'))).toMatchObject({ ok: true });
+    expect(await extractor.extract('.dangling', Buffer.from('x'))).toEqual({
+      ok: false,
+      failure: 'parser',
+      message: 'could not be extracted (XRefEntryException: Bad (uncompressed) XRef entry)',
+    });
+    expect(await extractor.extract('.echo', Buffer.from('after'))).toMatchObject({ ok: true, text: 'after' });
+    expect(processSaw).toEqual([]);
+  });
+
+  it('answers a parser that throws with its message', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts') });
+    expect(await extractor.extract('.throw', Buffer.from('x'))).toEqual({
+      ok: false,
+      failure: 'parser',
+      message: 'could not be extracted (boom)',
+    });
+  });
+
+  it('terminates a parser past its budget and answers the timeout notice — while this thread stays free', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts'), budgetMs: 300 });
+    // Warm the worker so its start-up is not part of the budget measured below.
+    await extractor.extract('.echo', Buffer.from('warm'));
+    const started = Date.now();
+    let ticks = 0;
+    const ticker = setInterval(() => ticks++, 20);
+    const res = await extractor.extract('.hang', Buffer.from('x'));
+    clearInterval(ticker);
+    expect(res).toEqual({
+      ok: false,
+      failure: 'timeout',
+      message: 'could not be read: extracting its text took longer than 0.3 seconds',
+    });
+    expect(Date.now() - started).toBeLessThan(2_000);
+    // The loop ran on the worker's thread: this one kept turning the whole time.
+    expect(ticks).toBeGreaterThan(5);
+    expect(await extractor.extract('.echo', Buffer.from('again'))).toMatchObject({ ok: true, text: 'again' });
+  });
+
+  it('gives three documents at once a worker and a budget each', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts'), budgetMs: 500 });
+    await Promise.all([1, 2, 3].map(() => extractor.extract('.echo', Buffer.from('warm'))));
+    const started = Date.now();
+    const results = await Promise.all([1, 2, 3].map(() => extractor.extract('.hang', Buffer.from('x'))));
+    expect(results.map((r) => !r.ok && r.failure)).toEqual(['timeout', 'timeout', 'timeout']);
+    // Side by side, not one after another: none waited a budget for a worker.
+    expect(Date.now() - started).toBeLessThan(1_000);
+  });
+
+  it('answers a worker that dies under the job as crashed, and one that cannot load the same way', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts') });
+    expect(await extractor.extract('.exit', Buffer.from('x'))).toEqual({
+      ok: false,
+      failure: 'crashed',
+      message: 'could not be read: its extraction stopped unexpectedly (exit code 3)',
+    });
+    await extractor.close();
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('unloadable-extract.worker.ts') });
+    const res = await extractor.extract('.pdf', Buffer.from('x'));
+    expect(res.ok).toBe(false);
+    expect(!res.ok && res.failure).toBe('crashed');
+    expect(!res.ok && res.message).toBe(EXTRACTION_WORKER_FAILED);
+    expect(processSaw).toEqual([]);
+  });
+
+  it('answers a parser that did not load as crashed — remembered for the hour, not for good', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts') });
+    expect(await extractor.extract('.transient', Buffer.from('x'))).toEqual({
+      ok: false,
+      failure: 'crashed',
+      message: 'could not be read: the PDF reader did not load on the server; try again later',
+    });
+  });
+
+  it('answers busy — nothing learned about the file — when every worker is taken and no one may wait', async () => {
+    extractor = new WorkerDocumentExtractor({
+      entry: fixtureEntry('misbehaving-extract.worker.ts'),
+      budgetMs: 500,
+      poolMax: 1,
+      maxWaiting: 0,
+    });
+    const hanging = extractor.extract('.hang', Buffer.from('x'));
+    await new Promise((r) => setTimeout(r, 50));
+    expect(await extractor.extract('.echo', Buffer.from('y'))).toMatchObject({ ok: false, failure: 'busy' });
+    expect(await hanging).toMatchObject({ failure: 'timeout' });
+  });
+
+  it('answers busy for an extraction running when the graph stops', async () => {
+    extractor = new WorkerDocumentExtractor({ entry: fixtureEntry('misbehaving-extract.worker.ts'), budgetMs: 5_000 });
+    const hanging = extractor.extract('.hang', Buffer.from('x'));
+    await new Promise((r) => setTimeout(r, 300));
+    await extractor.close();
+    expect(await hanging).toMatchObject({ ok: false, failure: 'busy' });
+  });
+});

package/src/modules/workspace/file-readers/__tests__/file-reader.registry.test.ts

@@ -2,6 +2,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { describe, expect, it } from 'vitest';
 import { DocExtractService } from '../doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../extract-in-worker.js';
 import { DocumentReader } from '../document-reader.js';
 import { EmailReader } from '../email-reader.js';
 import { FileReaderRegistry, type FileReader, type ReadResult } from '../file-reader.js';
@@ -21,7 +22,7 @@ import { accessFrontmatterExtensionList } from '../../../access-model/access-gra
  */
 
 const registry = createFileReaderRegistry(
-  new DocExtractService(join(tmpdir(), 'bevel-test-file-reader-registry')),
+  new DocExtractService(join(tmpdir(), 'bevel-test-file-reader-registry'), new WorkerDocumentExtractor()),
 );
 
 describe('file-reader registry routing', () => {