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

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 } from './document-extractor.contract.js';
+import { extractionMarker, fileExtension, type ExtractedDoc } 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,46 @@ export type DocExtractOutcome =
   | ({ ok: true } & DocExtraction)
   | { ok: false; message: string };
 
+/**
+ * What one read of some bytes answers before any path names it: the cache's
+ * own shape (an extraction, or a failure's message). `named` turns it into
+ * what `extract` returns for the path it was asked about.
+ */
+type RawOutcome = ({ ok: true } & ExtractedDoc) | { ok: false; message: string };
+
+/** `raw` as the answer for `path`: its marker names that path. */
+function named(path: string, raw: RawOutcome): DocExtractOutcome {
+  return raw.ok ? { ok: true, marker: extractionMarker(path, raw.summary), text: raw.text } : raw;
+}
+
+/** 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 +70,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,51 +103,104 @@ 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.
+   * Reads currently running, by cache key — the cache lookup included, from
+   * the moment `extract` is called. 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. The entry is set before anything
+   * is awaited: were the lookup awaited first, a second read could miss the
+   * cache (its read of the file started before the first read's write) AND
+   * the map (the first read finished and left it in that window), and parse
+   * the document again, telling the people looking at it twice.
+   *
+   * What is shared is exactly what the key identifies — the bytes' extraction
+   * under a format, which is what the cache holds — and nothing of the read
+   * that started it: the key carries no path, so two reads of the same bytes
+   * at different paths share one promise, and each names the answer with its
+   * own path (`extract`).
    */
-  private readonly inFlight = new Map<string, Promise<ExtractResult>>();
+  private readonly inFlight = new Map<string, Promise<RawOutcome>>();
 
-  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.remembered(this.cacheKey(path, bytes));
+    return hit && named(path, hit);
   }
 
-  /** 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> {
+    // The bytes are hashed BEFORE the extractor takes its copy of them.
     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 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 });
-          return res;
-        })().finally(() => this.inFlight.delete(key));
-        this.inFlight.set(key, started);
-        return started;
-      })());
-    if (!result.ok) return result;
-    return { ok: true, marker: extractionMarker(path, result.summary), text: result.text };
+    return named(path, await (this.inFlight.get(key) ?? this.read(key, path, bytes, origin)));
+  }
+
+  /** What the cache holds for `key`, or undefined on a miss. */
+  private async remembered(key: string): Promise<RawOutcome | undefined> {
+    const hit = await this.cache.get(key, this.now());
+    if (!hit) return undefined;
+    return hit.failed ? { ok: false, message: hit.message } : { ok: true, summary: hit.summary, text: hit.text };
+  }
+
+  /**
+   * One read of `bytes`, shared by every `extract` of the same key that
+   * arrives before it settles (see `inFlight`): the cache lookup, then the
+   * extraction and its cache write. The 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 map — and
+   * parse the same document again. A failure is reported to the FIRST
+   * read's origin and path, once; `path` otherwise gives only the format,
+   * which every read of the key shares.
+   */
+  private read(key: string, path: string, bytes: Buffer, origin: ReadOrigin | undefined): Promise<RawOutcome> {
+    const started = (async (): Promise<RawOutcome> => {
+      const hit = await this.remembered(key);
+      if (hit) return hit;
+      const res = await this.extractor.extract(fileExtension(path), bytes);
+      if (res.ok) {
+        await this.cache.put(key, { summary: res.summary, text: res.text });
+        return { ok: true, summary: res.summary, text: res.text };
+      }
+      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 { ok: false, message: res.message };
+    })().finally(() => this.inFlight.delete(key));
+    this.inFlight.set(key, started);
+    return started;
+  }
+
+  /** 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). */
@@ -105,3 +208,8 @@ export class DocExtractService {
     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];

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

@@ -1,20 +1,20 @@
-import type { DocExtractService } from './doc-extract.service.js';
-import type { ExtractFn } from './doc-extract.types.js';
-import { displayPath, oneLine, type FileReader, type ReadResult } from './file-reader.js';
+import type { DocExtractOutcome, DocExtractService } from './doc-extract.service.js';
+import { displayPath, oneLine, type FileReader, type ReadOrigin, type ReadResult } from './file-reader.js';
 import { extensionMime } from './text-reader.js';
 
 /**
- * FileReader over one document format: a thin wrapper pairing the format's
- * PURE extract function (extract-docx.ts and friends) with the shared
- * content-hash extraction cache (`DocExtractService`). Reads return the
- * extraction under its honest `[extracted text of …]` marker; a parse failure
- * becomes a refusal message, never a 500.
+ * FileReader over one document format: a thin wrapper around the shared
+ * content-hash extraction service (`DocExtractService`), which runs the
+ * format's extractor in a worker and remembers what it answered. Reads return
+ * the extraction under its honest `[extracted text of …]` marker; a failed
+ * extraction becomes a refusal message, never a 500.
  *
- * `grep` semantics: `greppableText` serves only the CACHED extraction (a hit
- * costs one small JSON read), returning null for a cold document — whether to
- * spend grep's per-walk extraction budget on a cold one is the walk's call,
- * which then extracts through `read` (see grepWalk in workspace.tools.ts).
- * grep also branches on `instanceof DocumentReader` for exactly that decision.
+ * `grep` semantics: `cachedRead` answers only what the cache REMEMBERS (a hit
+ * costs one small JSON read) — the extraction, or a failure's notice — and
+ * undefined for a cold document; whether to spend grep's per-walk extraction
+ * budget on a cold one is the walk's call, which then extracts through `read`
+ * (see grepWalk in workspace.tools.ts). grep also branches on
+ * `instanceof DocumentReader` for exactly that decision.
  */
 export class DocumentReader implements FileReader {
   readonly extensions: readonly string[];
@@ -28,43 +28,47 @@ export class DocumentReader implements FileReader {
 
   constructor(
     extension: string,
-    private readonly extract: ExtractFn,
     private readonly service: DocExtractService,
   ) {
     this.extensions = [extension];
   }
 
-  async read(bytes: Buffer, path: string): Promise<ReadResult> {
-    // An extractor is contracted to ANSWER for bad content rather than throw,
-    // but it wraps third-party parsers, and one of those throwing past its own
-    // guard is a corrupt file — not a server fault. read_file says so instead
-    // of failing the whole tool call with a 500.
-    let res: Awaited<ReturnType<typeof this.service.extract>>;
+  /** `origin` names the workspace the file was read in, so a fresh failure can be reported there. */
+  async read(bytes: Buffer, path: string, origin?: ReadOrigin): Promise<ReadResult> {
+    // The service answers every parser failure as an outcome; a throw here is
+    // the service's own fault (the cache's disk, say) — still answered as the
+    // file's honest refusal rather than failing the whole tool call with a 500.
+    let res: DocExtractOutcome;
     try {
-      res = await this.service.extract(path, bytes, this.extract);
+      res = await this.service.extract(path, bytes, origin);
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err);
-      return {
-        kind: 'refusal',
-        message: `[${displayPath(path)} could not be extracted (${oneLine(reason)}) — the file may be corrupt or mislabeled. To fix it, replace the document by uploading a new version.]`,
-      };
+      res = { ok: false, message: `could not be extracted (${reason})` };
     }
+    return toReadResult(path, res);
+  }
 
-    return res.ok
-      ? { kind: 'text', text: `${res.marker}\n${res.text}` }
-      : {
-          kind: 'refusal',
-          message: `[${displayPath(path)} ${oneLine(res.message)} — the file may be corrupt or mislabeled. To fix it, replace the document by uploading a new version.]`,
-        };
+  /**
+   * What `read` would answer, from the cache alone — the extraction (marker
+   * line included, so grep's line numbers match read_file's) or a remembered
+   * failure's refusal — or undefined when the document is cold. Never extracts.
+   */
+  async cachedRead(bytes: Buffer, path: string): Promise<ReadResult | undefined> {
+    const hit = await this.service.getCached(path, bytes);
+    return hit && toReadResult(path, hit);
   }
 
   mimeFor(path: string): string | undefined {
     return extensionMime(path);
   }
+}
 
-  /** The cached extraction (marker line included, so grep's line numbers match read_file's), or null when cold. */
-  async greppableText(bytes: Buffer, path: string): Promise<string | null> {
-    const hit = await this.service.getCached(path, bytes);
-    return hit ? `${hit.marker}\n${hit.text}` : null;
-  }
+/** One outcome, one wording: the same refusal whether the failure is fresh or remembered. */
+function toReadResult(path: string, res: DocExtractOutcome): ReadResult {
+  return res.ok
+    ? { kind: 'text', text: `${res.marker}\n${res.text}` }
+    : {
+        kind: 'refusal',
+        message: `[${displayPath(path)} ${oneLine(res.message)} — the file may be corrupt or mislabeled. To fix it, replace the document by uploading a new version.]`,
+      };
 }