@bevel-software/platform-core-backend 0.31.0 → 0.33.0

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', () => {

package/src/modules/workspace/file-readers/__tests__/fixtures/damaged-pdf.ts

@@ -0,0 +1,34 @@
+/**
+ * A SYNTHETIC PDF whose cross-reference table is damaged — never a tenant's
+ * file. One page, one content stream; the xref entry for the content stream
+ * (object 4) points two bytes past where the object starts, and the object's
+ * own header is defaced so pdf.js's recovery scan cannot find it either.
+ * pdf.js answers it with the exception of the 2026-10-15 incident:
+ * `Bad (uncompressed) XRef entry: 4R`.
+ *
+ * `damage: false` builds the same file intact, which reads as `text`.
+ */
+export function xrefPdf(text: string, { damage }: { damage: boolean }): Buffer {
+  const stream = `BT /F1 12 Tf 72 720 Td (${text}) Tj ET`;
+  const objects = [
+    '<< /Type /Catalog /Pages 2 0 R >>',
+    '<< /Type /Pages /Kids [3 0 R] /Count 1 >>',
+    '<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>',
+    `<< /Length ${stream.length} >>\nstream\n${stream}\nendstream`,
+    '<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>',
+  ];
+  let pdf = '%PDF-1.4\n';
+  const offsets: number[] = [];
+  for (let i = 0; i < objects.length; i++) {
+    offsets.push(pdf.length);
+    const header = damage && i === 3 ? `${i + 1} 0 xbj` : `${i + 1} 0 obj`;
+    pdf += `${header}\n${objects[i]}\nendobj\n`;
+  }
+  const xrefStart = pdf.length;
+  pdf += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`;
+  offsets.forEach((off, i) => {
+    pdf += `${String(damage && i === 3 ? off + 2 : off).padStart(10, '0')} 00000 n \n`;
+  });
+  pdf += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xrefStart}\n%%EOF\n`;
+  return Buffer.from(pdf, 'latin1');
+}

package/src/modules/workspace/file-readers/__tests__/fixtures/misbehaving-extract.worker.ts

@@ -0,0 +1,57 @@
+import { serveExtractions } from '../../extraction-worker.js';
+
+/**
+ * An extraction worker serving parsers that misbehave in each of the ways a
+ * real one can, by extension — for `extract-in-worker.test.ts`.
+ */
+serveExtractions({
+  // The incident's shape: a rejection nothing awaits, and a promise that never settles.
+  '.dangling': () => {
+    void Promise.reject(new Error('XRefEntryException: Bad (uncompressed) XRef entry'));
+    return new Promise(() => {});
+  },
+  // Answers, then leaves a rejection behind after the answer.
+  '.straggler': () => {
+    setTimeout(() => void Promise.reject(new Error('late')), 20);
+    return { ok: true, summary: 'straggler', text: 'answered first' };
+  },
+  // Answers, then — once the host has had time to hand the worker its next
+  // job — leaves a rejection behind before that job's message is taken up:
+  // the worker sees it BETWEEN jobs, and ends itself.
+  '.straggler-between-jobs': () => {
+    setImmediate(() => {
+      const until = Date.now() + 200;
+      while (Date.now() < until) {
+        /* the host answers, releases this worker and posts the next job meanwhile */
+      }
+      void Promise.reject(new Error('late, between jobs'));
+    });
+    return { ok: true, summary: 'straggler', text: 'answered first' };
+  },
+  '.throw': () => {
+    throw new Error('boom');
+  },
+  // Spins on the worker's thread: only terminating the worker stops it.
+  '.hang': () => {
+    for (;;) {
+      /* a parser in a loop */
+    }
+  },
+  // The parser itself did not load: the reader's fault, not the file's.
+  '.transient': () => ({ ok: false, transient: true, message: 'could not be read: the PDF reader did not load on the server; try again later' }),
+  '.exit': () => process.exit(3),
+  '.echo': (bytes) => ({ ok: true, summary: 'echo', text: bytes.toString('utf8') }),
+  // Answers after a while: long enough for an earlier job's straggler to land during it.
+  '.slow-echo': (bytes) =>
+    new Promise((resolve) => setTimeout(() => resolve({ ok: true, summary: 'echo', text: bytes.toString('utf8') }), 150)),
+  // Answers, then leaves a rejection behind well into the next job — late
+  // enough that the budget the next job has left is less than that job needs.
+  '.straggler-late': () => {
+    setTimeout(() => void Promise.reject(new Error('late')), 600);
+    return { ok: true, summary: 'straggler', text: 'answered first' };
+  },
+  // A sound document that takes most of a budget: more than what is left
+  // after `.straggler-late` lands, less than the budget whole.
+  '.slow-echo-long': (bytes) =>
+    new Promise((resolve) => setTimeout(() => resolve({ ok: true, summary: 'echo', text: bytes.toString('utf8') }), 1100)),
+});

package/src/modules/workspace/file-readers/__tests__/fixtures/pdf-in-trouble.worker.ts

@@ -0,0 +1,20 @@
+import { extractPdf } from '../../extract-pdf.js';
+import { serveExtractions } from '../../extraction-worker.js';
+
+/**
+ * The real PDF extractor, except for a PDF whose bytes say otherwise: `HANG`
+ * spins forever, `SLOW` spins for 1.5 s before extracting — both on the
+ * worker's thread, as a parser stuck on crafted input would. For the tool
+ * suites that time `/api/health` while a document is being extracted.
+ */
+serveExtractions({
+  '.pdf': (bytes) => {
+    const text = bytes.toString('latin1');
+    if (text.includes('HANG')) for (;;) { /* stuck */ }
+    if (text.includes('SLOW')) {
+      const until = Date.now() + 1_500;
+      while (Date.now() < until) { /* busy */ }
+    }
+    return extractPdf(bytes);
+  },
+});

package/src/modules/workspace/file-readers/__tests__/fixtures/unloadable-extract.worker.ts

@@ -0,0 +1,2 @@
+/** An extraction worker whose script fails to load — for `extract-in-worker.test.ts`. */
+throw new Error('this worker cannot load');

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

@@ -1,5 +1,7 @@
-import { extractionMarker, fileExtension, type ExtractFn, type ExtractResult } from './doc-extract.types.js';
+import type { IDocumentExtractor, IsolatedExtraction } from './document-extractor.contract.js';
+import { extractionMarker, fileExtension } from './doc-extract.types.js';
 import { DocExtractionCache, gitBlobSha } from './extraction-cache.js';
+import type { ReadOrigin } from './file-reader.js';
 
 /** An extraction ready for a consumer: the honest marker header + the text. */
 export interface DocExtraction {
@@ -13,6 +15,34 @@ export type DocExtractOutcome =
   | ({ ok: true } & DocExtraction)
   | { ok: false; message: string };
 
+/** A document whose extraction just failed, as the people looking at it are told. */
+export interface UnreadableDocument {
+  workspaceId: string;
+  path: string;
+  /** What went wrong, worded to follow "Could not be read:". */
+  reason: string;
+}
+
+export interface DocExtractServiceOptions {
+  /** The clock a remembered timeout is judged by (epoch ms). Default `Date.now`. */
+  now?: () => number;
+  /**
+   * Told once per FRESH failure of an extraction a read with an origin
+   * started — never for a failure answered from memory. The composition root
+   * turns it into the `document-unreadable` event.
+   */
+  onUnreadable?: (doc: UnreadableDocument) => void;
+}
+
+/**
+ * How long an extraction stopped over its budget, or whose worker died under
+ * it, is remembered: an overrun is a property of the moment (a busy server, a
+ * large file), not of the bytes, so it is tried again after this. A parser's
+ * refusal is a property of the bytes and is remembered like a success
+ * (decided 2026-10-15/19).
+ */
+export const TIMEOUT_MEMORY_MS = 60 * 60 * 1000;
+
 /**
  * The content-hash CACHE wrap around document text extraction. The per-format
  * `DocumentReader`s in the file-reader registry stay pure (each pairs one
@@ -28,7 +58,15 @@ export type DocExtractOutcome =
  * extract DIFFERENTLY per format: a `.odt` renamed `.ods` must run the ods
  * extractor, not return the odt extraction. Extraction is deterministic
  * (stable slide/sheet/page ordering), which is what makes a content-keyed
- * cache correct. Failures are NOT cached (rare, and fail fast). The key also carries
+ * cache correct.
+ *
+ * Extraction itself runs in a worker, under a budget (`IDocumentExtractor`),
+ * and its FAILURES are remembered under the same key: a parser's refusal for
+ * good, so damaged bytes cost the server once for as long as the entry is
+ * kept (the cache evicts by size, as it does successes), and a timeout or a
+ * crash for {@link TIMEOUT_MEMORY_MS}. A re-saved file is new content and is
+ * extracted again. Only "no worker was free" is not remembered: it says
+ * nothing about the file. The key also carries
  * `EXTRACTION_SCHEMA`, so an upgrade that changes what an extractor emits does
  * not keep serving the previous release's text for unchanged bytes.
  */
@@ -53,55 +91,92 @@ export const EXTRACTION_SCHEMA = 'v3';
 
 export class DocExtractService {
   private readonly cache: DocExtractionCache;
+  private readonly now: () => number;
+  private readonly onUnreadable: ((doc: UnreadableDocument) => void) | undefined;
   /**
    * Cold extractions currently running, by cache key. Two reads of the same
    * document arriving together would otherwise BOTH parse it — the expensive
    * half of this service, run twice for one answer — because neither had
    * written the cache entry yet when the other looked.
    */
-  private readonly inFlight = new Map<string, Promise<ExtractResult>>();
+  private readonly inFlight = new Map<string, Promise<IsolatedExtraction>>();
 
-  constructor(cacheRoot: string) {
+  constructor(
+    cacheRoot: string,
+    private readonly extractor: IDocumentExtractor,
+    opts: DocExtractServiceOptions = {},
+  ) {
     this.cache = new DocExtractionCache(cacheRoot);
+    this.now = opts.now ?? Date.now;
+    this.onUnreadable = opts.onUnreadable;
   }
 
   /**
-   * The CACHED extraction for these bytes, or undefined on a cache miss —
-   * never extracts. `grep` uses this (via `DocumentReader.greppableText`) to
-   * search already-extracted documents for free and apply its per-walk budget
-   * only to cold ones.
+   * What the cache REMEMBERS for these bytes — the extraction, or the notice
+   * of a failed one — or undefined on a miss; never extracts. `grep` uses this
+   * (via `DocumentReader.cachedRead`) to search already-extracted documents
+   * for free, skip remembered failures for free, and apply its per-walk budget
+   * only to cold ones; `file_stat` uses it to report a remembered failure.
    */
-  async getCached(path: string, bytes: Buffer): Promise<DocExtraction | undefined> {
-    const hit = await this.cache.get(this.cacheKey(path, bytes));
-    return hit && { marker: extractionMarker(path, hit.summary), text: hit.text };
+  async getCached(path: string, bytes: Buffer): Promise<DocExtractOutcome | undefined> {
+    const hit = await this.cache.get(this.cacheKey(path, bytes), this.now());
+    if (!hit) return undefined;
+    return hit.failed
+      ? { ok: false, message: hit.message }
+      : { ok: true, marker: extractionMarker(path, hit.summary), text: hit.text };
   }
 
-  /** Extract via `extractFn` (cache hit or parse + store). `path` supplies the marker AND the key's format part. */
-  async extract(path: string, bytes: Buffer, extractFn: ExtractFn): Promise<DocExtractOutcome> {
+  /**
+   * The extraction of `bytes` (remembered, or run in the extractor's worker
+   * and remembered). `path` supplies the marker AND the key's format part;
+   * `origin`, when given, is where a fresh failure is reported.
+   */
+  async extract(path: string, bytes: Buffer, origin?: ReadOrigin): Promise<DocExtractOutcome> {
     const key = this.cacheKey(path, bytes);
-    const hit = await this.cache.get(key);
-    if (hit) return { ok: true, marker: extractionMarker(path, hit.summary), text: hit.text };
+    const remembered = await this.getCached(path, bytes);
+    if (remembered) return remembered;
     const running = this.inFlight.get(key);
     const result = await (running ??
       (() => {
         // The cache write stays INSIDE the shared promise: were the entry
         // dropped as soon as parsing settled, a read arriving during the
         // write would miss both the cache and the in-flight map — and parse
-        // the same document again.
-        const started = (async (): Promise<ExtractResult> => {
-          const res = await extractFn(bytes);
-          if (res.ok) await this.cache.put(key, { summary: res.summary, text: res.text });
+        // the same document again. The bytes are hashed (above) BEFORE the
+        // extractor takes its copy of them.
+        const started = (async (): Promise<IsolatedExtraction> => {
+          const res = await this.extractor.extract(fileExtension(path), bytes);
+          if (res.ok) {
+            await this.cache.put(key, { summary: res.summary, text: res.text });
+          } else if (res.failure !== 'busy') {
+            const until = res.failure === 'parser' ? undefined : this.now() + TIMEOUT_MEMORY_MS;
+            await this.cache.put(key, { failed: true, message: res.message, ...(until === undefined ? {} : { until }) });
+            if (origin) this.notifyUnreadable({ workspaceId: origin.workspaceId, path, reason: reasonOf(res.message) });
+          }
           return res;
         })().finally(() => this.inFlight.delete(key));
         this.inFlight.set(key, started);
         return started;
       })());
-    if (!result.ok) return result;
+    if (!result.ok) return { ok: false, message: result.message };
     return { ok: true, marker: extractionMarker(path, result.summary), text: result.text };
   }
 
+  /** Best-effort, like every event: a listener that throws never fails the read. */
+  private notifyUnreadable(doc: UnreadableDocument): void {
+    try {
+      this.onUnreadable?.(doc);
+    } catch {
+      // the read still answers its notice
+    }
+  }
+
   /** Content hash + lowercased extension — e.g. `…sha….odt` (see the class doc). */
   private cacheKey(path: string, bytes: Buffer): string {
     return `${gitBlobSha(bytes)}${fileExtension(path)}.${EXTRACTION_SCHEMA}`;
   }
 }
+
+/** A failure's notice, worded to follow "Could not be read:" (the explorer's copy) without saying it twice. */
+function reasonOf(message: string): string {
+  return message.replace(/^could not be read: /, '');
+}

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

@@ -34,13 +34,23 @@ export interface ExtractedDoc {
  */
 export type ExtractResult =
   | ({ ok: true } & ExtractedDoc)
-  | { ok: false; message: string };
+  | {
+      ok: false;
+      message: string;
+      /**
+       * Set when the failure is the reader's, not the file's — the parser
+       * itself did not load — so it is not remembered as the file's answer
+       * the way a refusal of its bytes is.
+       */
+      transient?: true;
+    };
 
 /**
  * A format's PURE extract function — bytes in, `ExtractResult` out (async for
  * pdf.js). One per supported format (extract-docx.ts and friends); each is
- * paired with its extension by a `DocumentReader` entry in the file-reader
- * registry, and cache-wrapped by `DocExtractService`.
+ * paired with its extension in the extraction worker's table
+ * (`document-extractors.ts`), run there under a budget, and cache-wrapped by
+ * `DocExtractService`.
  */
 export type ExtractFn = (bytes: Buffer) => ExtractResult | Promise<ExtractResult>;
 

package/src/modules/workspace/file-readers/document-extractor.contract.ts

@@ -0,0 +1,42 @@
+import type { ExtractedDoc } from './doc-extract.types.js';
+
+/**
+ * The contract for running a document's extractor: what `DocExtractService`
+ * depends on, so it never holds a concrete engine. The one implementation is
+ * `WorkerDocumentExtractor` (`extract-in-worker.ts`), owned by the
+ * composition root and closed with the graph.
+ *
+ * A parser can hang on crafted input and can reject promises it never hands
+ * back, so an implementation must never run one on the request thread, must
+ * stop an extraction that outlives its budget, and must answer every failure
+ * — a parser error, a dangling rejection, a crash — as an outcome, never as a
+ * rejection of `extract` and never as an event on the server's process.
+ */
+export interface IDocumentExtractor {
+  /** Extract `bytes` as a file of `extension` (lowercased, with its dot). The caller's buffer is left as it was. */
+  extract(extension: string, bytes: Buffer): Promise<IsolatedExtraction>;
+  /** Ends the workers; an extraction after this is answered `busy`. */
+  close(): Promise<void>;
+}
+
+/**
+ * Why an extraction failed, which is what decides how long the failure is
+ * remembered (see `DocExtractService`):
+ *  - `parser`: the parser refused the bytes, threw, or left a rejection behind
+ *    it — a property of the content;
+ *  - `timeout`: the extraction outlived its budget and was stopped;
+ *  - `crashed`: the worker failed or died under the job without answering
+ *    (out of memory, a script that would not load), or the parser itself did
+ *    not load — a fault of the moment;
+ *  - `busy`: no worker could take the job — nothing was learned about the file.
+ */
+export type ExtractionFailure = 'parser' | 'timeout' | 'crashed' | 'busy';
+
+export type IsolatedExtraction =
+  | ({ ok: true } & ExtractedDoc)
+  | { ok: false; message: string; failure: ExtractionFailure };
+
+/** The notice an extraction stopped over its budget answers with. */
+export function extractionTimeoutNotice(budgetMs: number): string {
+  return `could not be read: extracting its text took longer than ${budgetMs / 1000} seconds`;
+}

package/src/modules/workspace/file-readers/document-extractors.ts

@@ -0,0 +1,28 @@
+import type { DocumentExtension } from './document-formats.js';
+import type { ExtractFn } from './doc-extract.types.js';
+import { extractDocx } from './extract-docx.js';
+import { extractEml } from './extract-eml.js';
+import { extractMsg } from './extract-msg.js';
+import { extractOdp } from './extract-odp.js';
+import { extractOds } from './extract-ods.js';
+import { extractOdt } from './extract-odt.js';
+import { extractPdf } from './extract-pdf.js';
+import { extractPptx } from './extract-pptx.js';
+import { extractXlsx } from './extract-xlsx.js';
+
+/**
+ * Which pure extract function owns which document format. Loaded by the
+ * extraction worker only (`extract.worker.ts`): no parser runs on the
+ * server's request thread.
+ */
+export const DOCUMENT_EXTRACTORS: Readonly<Record<DocumentExtension, ExtractFn>> = {
+  '.docx': extractDocx,
+  '.pptx': extractPptx,
+  '.xlsx': extractXlsx,
+  '.pdf': extractPdf,
+  '.odt': extractOdt,
+  '.odp': extractOdp,
+  '.ods': extractOds,
+  '.eml': extractEml,
+  '.msg': extractMsg,
+};

package/src/modules/workspace/file-readers/document-formats.ts

@@ -0,0 +1,13 @@
+/**
+ * The document formats whose text is EXTRACTED rather than read: the one list
+ * both sides of the extraction worker agree on. The file-reader registry
+ * builds a reader for each, on the request thread, without loading a single
+ * parser; the worker's table (`document-extractors.ts`) is typed by these
+ * lists, so a format added here and not there fails to compile.
+ */
+export const OFFICE_DOCUMENT_EXTENSIONS = ['.docx', '.pptx', '.xlsx', '.pdf', '.odt', '.odp', '.ods'] as const;
+
+/** Email files: extracted the same way, refused for writing with an email-honest message (see `EmailReader`). */
+export const EMAIL_EXTENSIONS = ['.eml', '.msg'] as const;
+
+export type DocumentExtension = (typeof OFFICE_DOCUMENT_EXTENSIONS)[number] | (typeof EMAIL_EXTENSIONS)[number];