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

package/dist/modules/workspace/file-readers/doc-extract.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"doc-extract.types.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/doc-extract.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AA8B7D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAe;IAC5D,OAAO,sBAAsB,aAAa,CAAC,IAAI,CAAC,MAAM,OAAO,GAAG,CAAC;AACnE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACtD,CAAC"}
+{"version":3,"file":"doc-extract.types.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/doc-extract.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAwC7D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAe;IAC5D,OAAO,sBAAsB,aAAa,CAAC,IAAI,CAAC,MAAM,OAAO,GAAG,CAAC;AACnE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACtD,CAAC"}

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

@@ -0,0 +1,41 @@
+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 declare function extractionTimeoutNotice(budgetMs: number): string;
+//# sourceMappingURL=document-extractor.contract.d.ts.map

package/dist/modules/workspace/file-readers/document-extractor.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-extractor.contract.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-extractor.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,kHAAkH;IAClH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACvE,qEAAqE;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1E,MAAM,MAAM,kBAAkB,GAC1B,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,YAAY,CAAC,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAE/D,qEAAqE;AACrE,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/modules/workspace/file-readers/document-extractor.contract.js

@@ -0,0 +1,5 @@
+/** The notice an extraction stopped over its budget answers with. */
+export function extractionTimeoutNotice(budgetMs) {
+    return `could not be read: extracting its text took longer than ${budgetMs / 1000} seconds`;
+}
+//# sourceMappingURL=document-extractor.contract.js.map

package/dist/modules/workspace/file-readers/document-extractor.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-extractor.contract.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-extractor.contract.ts"],"names":[],"mappings":"AAsCA,qEAAqE;AACrE,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,OAAO,2DAA2D,QAAQ,GAAG,IAAI,UAAU,CAAC;AAC9F,CAAC"}

package/dist/modules/workspace/file-readers/document-extractors.d.ts

@@ -0,0 +1,9 @@
+import type { DocumentExtension } from './document-formats.js';
+import type { ExtractFn } from './doc-extract.types.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 declare const DOCUMENT_EXTRACTORS: Readonly<Record<DocumentExtension, ExtractFn>>;
+//# sourceMappingURL=document-extractors.d.ts.map

package/dist/modules/workspace/file-readers/document-extractors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-extractors.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-extractors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAWxD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAU9E,CAAC"}

package/dist/modules/workspace/file-readers/document-extractors.js

@@ -0,0 +1,26 @@
+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 = {
+    '.docx': extractDocx,
+    '.pptx': extractPptx,
+    '.xlsx': extractXlsx,
+    '.pdf': extractPdf,
+    '.odt': extractOdt,
+    '.odp': extractOdp,
+    '.ods': extractOds,
+    '.eml': extractEml,
+    '.msg': extractMsg,
+};
+//# sourceMappingURL=document-extractors.js.map

package/dist/modules/workspace/file-readers/document-extractors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-extractors.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-extractors.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAmD;IACjF,OAAO,EAAE,WAAW;IACpB,OAAO,EAAE,WAAW;IACpB,OAAO,EAAE,WAAW;IACpB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;CACnB,CAAC"}

package/dist/modules/workspace/file-readers/document-formats.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare const OFFICE_DOCUMENT_EXTENSIONS: readonly [".docx", ".pptx", ".xlsx", ".pdf", ".odt", ".odp", ".ods"];
+/** Email files: extracted the same way, refused for writing with an email-honest message (see `EmailReader`). */
+export declare const EMAIL_EXTENSIONS: readonly [".eml", ".msg"];
+export type DocumentExtension = (typeof OFFICE_DOCUMENT_EXTENSIONS)[number] | (typeof EMAIL_EXTENSIONS)[number];
+//# sourceMappingURL=document-formats.d.ts.map

package/dist/modules/workspace/file-readers/document-formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-formats.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-formats.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,sEAAuE,CAAC;AAE/G,iHAAiH;AACjH,eAAO,MAAM,gBAAgB,2BAA4B,CAAC;AAE1D,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/modules/workspace/file-readers/document-formats.js

@@ -0,0 +1,11 @@
+/**
+ * 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'];
+/** Email files: extracted the same way, refused for writing with an email-honest message (see `EmailReader`). */
+export const EMAIL_EXTENSIONS = ['.eml', '.msg'];
+//# sourceMappingURL=document-formats.js.map

package/dist/modules/workspace/file-readers/document-formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-formats.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-formats.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC;AAE/G,iHAAiH;AACjH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAU,CAAC"}

package/dist/modules/workspace/file-readers/document-reader.d.ts

@@ -1,21 +1,20 @@
 import type { DocExtractService } from './doc-extract.service.js';
-import type { ExtractFn } from './doc-extract.types.js';
-import { type FileReader, type ReadResult } from './file-reader.js';
+import { type FileReader, type ReadOrigin, type ReadResult } from './file-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 declare class DocumentReader implements FileReader {
-    private readonly extract;
     private readonly service;
     readonly extensions: readonly string[];
     /**
@@ -25,10 +24,15 @@ export declare class DocumentReader implements FileReader {
      */
     readonly textEditable = false;
     readonly fileKind: "document";
-    constructor(extension: string, extract: ExtractFn, service: DocExtractService);
-    read(bytes: Buffer, path: string): Promise<ReadResult>;
+    constructor(extension: string, service: DocExtractService);
+    /** `origin` names the workspace the file was read in, so a fresh failure can be reported there. */
+    read(bytes: Buffer, path: string, origin?: ReadOrigin): Promise<ReadResult>;
+    /**
+     * 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.
+     */
+    cachedRead(bytes: Buffer, path: string): Promise<ReadResult | undefined>;
     mimeFor(path: string): string | undefined;
-    /** The cached extraction (marker line included, so grep's line numbers match read_file's), or null when cold. */
-    greppableText(bytes: Buffer, path: string): Promise<string | null>;
 }
 //# sourceMappingURL=document-reader.d.ts.map

package/dist/modules/workspace/file-readers/document-reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-reader.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAwB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG1F;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAe,YAAW,UAAU;IAY7C,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZ1B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,SAAS;IAC9B,QAAQ,CAAC,QAAQ,EAAG,UAAU,CAAU;gBAGtC,SAAS,EAAE,MAAM,EACA,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,iBAAiB;IAKvC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAwB5D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIzC,iHAAiH;IAC3G,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAIzE"}
+{"version":3,"file":"document-reader.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAqB,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,EAAwB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG3G;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,YAAW,UAAU;IAY7C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAX1B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,SAAS;IAC9B,QAAQ,CAAC,QAAQ,EAAG,UAAU,CAAU;gBAGtC,SAAS,EAAE,MAAM,EACA,OAAO,EAAE,iBAAiB;IAK7C,mGAAmG;IAC7F,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAcjF;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAK9E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAG1C"}

package/dist/modules/workspace/file-readers/document-reader.js

@@ -1,20 +1,20 @@
 import { displayPath, oneLine } 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 {
-    extract;
     service;
     extensions;
     /**
@@ -24,41 +24,45 @@ export class DocumentReader {
      */
     textEditable = false;
     fileKind = 'document';
-    constructor(extension, extract, service) {
-        this.extract = extract;
+    constructor(extension, service) {
         this.service = service;
         this.extensions = [extension];
     }
-    async read(bytes, path) {
-        // 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.
+    /** `origin` names the workspace the file was read in, so a fresh failure can be reported there. */
+    async read(bytes, path, origin) {
+        // 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;
         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 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.]`,
-            };
+        return toReadResult(path, res);
+    }
+    /**
+     * 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, path) {
+        const hit = await this.service.getCached(path, bytes);
+        return hit && toReadResult(path, hit);
     }
     mimeFor(path) {
         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, path) {
-        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, 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.]`,
+        };
 }
 //# sourceMappingURL=document-reader.js.map

package/dist/modules/workspace/file-readers/document-reader.js.map

@@ -1 +1 @@
-{"version":3,"file":"document-reader.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-reader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAoC,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,cAAc;IAYN;IACA;IAZV,UAAU,CAAoB;IACvC;;;;OAIG;IACM,YAAY,GAAG,KAAK,CAAC;IACrB,QAAQ,GAAG,UAAmB,CAAC;IAExC,YACE,SAAiB,EACA,OAAkB,EAClB,OAA0B;QAD1B,YAAO,GAAP,OAAO,CAAW;QAClB,YAAO,GAAP,OAAO,CAAmB;QAE3C,IAAI,CAAC,UAAU,GAAG,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,IAAY;QACpC,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,6CAA6C;QAC7C,IAAI,GAAqD,CAAC;QAC1D,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,4BAA4B,OAAO,CAAC,MAAM,CAAC,yGAAyG;aACnL,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,CAAC,EAAE;YACX,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,EAAE;YACtD,CAAC,CAAC;gBACE,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,wGAAwG;aAC/J,CAAC;IACR,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,iHAAiH;IACjH,KAAK,CAAC,aAAa,CAAC,KAAa,EAAE,IAAY;QAC7C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACtD,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACnD,CAAC;CACF"}
+{"version":3,"file":"document-reader.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/document-reader.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAqD,MAAM,kBAAkB,CAAC;AAC3G,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,cAAc;IAYN;IAXV,UAAU,CAAoB;IACvC;;;;OAIG;IACM,YAAY,GAAG,KAAK,CAAC;IACrB,QAAQ,GAAG,UAAmB,CAAC;IAExC,YACE,SAAiB,EACA,OAA0B;QAA1B,YAAO,GAAP,OAAO,CAAmB;QAE3C,IAAI,CAAC,UAAU,GAAG,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,mGAAmG;IACnG,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,IAAY,EAAE,MAAmB;QACzD,0EAA0E;QAC1E,0EAA0E;QAC1E,4EAA4E;QAC5E,IAAI,GAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,GAAG,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,2BAA2B,MAAM,GAAG,EAAE,CAAC;QACrE,CAAC;QACD,OAAO,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU,CAAC,KAAa,EAAE,IAAY;QAC1C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACtD,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;CACF;AAED,6FAA6F;AAC7F,SAAS,YAAY,CAAC,IAAY,EAAE,GAAsB;IACxD,OAAO,GAAG,CAAC,EAAE;QACX,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,EAAE;QACtD,CAAC,CAAC;YACE,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,wGAAwG;SAC/J,CAAC;AACR,CAAC"}

package/dist/modules/workspace/file-readers/extract-in-worker.d.ts

@@ -0,0 +1,60 @@
+import { type IDocumentExtractor, type IsolatedExtraction } from './document-extractor.contract.js';
+/**
+ * Extraction time one document may spend in its worker: the platform's rule,
+ * not a deployment's (decided 2026-10-19). A longer wait is too unresponsive
+ * for a read or a search; the hour a timeout is remembered for is what keeps a
+ * hanging file cheap (see `DocExtractService`).
+ */
+export declare const EXTRACTION_BUDGET_MS = 10000;
+/** What a document answers when its worker failed outside the parser: never the worker's own error. */
+export declare const EXTRACTION_WORKER_FAILED = "could not be read: its extraction failed on the server; try again later";
+/** The worker script: a module that calls `serveExtractions` (see `extraction-worker.ts`). */
+export interface ExtractionWorkerEntry {
+    url: URL;
+    /** Node options for the worker thread — a TypeScript entry needs its loader. */
+    execArgv: string[];
+}
+export interface WorkerDocumentExtractorOptions {
+    /** Worker time one extraction may spend. Default {@link EXTRACTION_BUDGET_MS}. */
+    budgetMs?: number;
+    /** Workers kept for extractions at once; one past this waits for a worker. Default 4. */
+    poolMax?: number;
+    /**
+     * Extractions that may wait for a worker at once. A waiting extraction holds
+     * the file's bytes, so the queue is capped: past it an extraction is answered
+     * `busy`, and nothing about the file is remembered. Default 32.
+     */
+    maxWaiting?: number;
+    /**
+     * The worker script. Default: the document extractors (`extract.worker`).
+     * A composition serving other extractors — a test's misbehaving parser —
+     * names its own module calling `serveExtractions`.
+     */
+    entry?: ExtractionWorkerEntry;
+}
+/**
+ * The one place a document's extractor runs (see {@link IDocumentExtractor}):
+ * a pooled worker thread — the extraction worker kind of the shared
+ * {@link WorkerPool}, which `grep`'s regex matcher is the other kind of —
+ * under a budget per file.
+ *
+ * The bytes are COPIED once on the request thread and the copy transferred,
+ * so the caller's buffer (already hashed for the cache key, and possibly a
+ * slice of Node's shared pool) is never detached. Past the budget the worker is
+ * terminated, which stops a parser mid-loop, and the file answers the timeout
+ * notice. A worker that answers with a dangling rejection, raises, or dies is
+ * never reused; the pool replaces it. A rejection the worker cannot pin on
+ * this job — it had served another before (see `serveExtractions`) — runs the
+ * job again in a fresh worker, so one file's failure is never another's.
+ */
+export declare class WorkerDocumentExtractor implements IDocumentExtractor {
+    private readonly budgetMs;
+    private readonly pool;
+    private nextJob;
+    private closing;
+    constructor(opts?: WorkerDocumentExtractorOptions);
+    extract(extension: string, bytes: Buffer): Promise<IsolatedExtraction>;
+    private attempt;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=extract-in-worker.d.ts.map

package/dist/modules/workspace/file-readers/extract-in-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-in-worker.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/extract-in-worker.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,kCAAkC,CAAC;AAM1C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,uGAAuG;AACvG,eAAO,MAAM,wBAAwB,4EAA4E,CAAC;AAElH,8FAA8F;AAC9F,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,GAAG,CAAC;IACT,gFAAgF;IAChF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,8BAA8B;IAC7C,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAC;CAC/B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,uBAAwB,YAAW,kBAAkB;IAChE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,GAAE,8BAAmC;IAc/C,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;YAe9D,OAAO;IAkDrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAIvB"}

package/dist/modules/workspace/file-readers/extract-in-worker.js

@@ -0,0 +1,140 @@
+import { Worker } from 'node:worker_threads';
+import { exchange, MAX_TIMER_MS, sizingOption, WorkerPool } from '../worker-pool.js';
+import { extractionTimeoutNotice, } from './document-extractor.contract.js';
+import { logger } from '../../../shared/logging.js';
+const log = logger('documents');
+/**
+ * Extraction time one document may spend in its worker: the platform's rule,
+ * not a deployment's (decided 2026-10-19). A longer wait is too unresponsive
+ * for a read or a search; the hour a timeout is remembered for is what keeps a
+ * hanging file cheap (see `DocExtractService`).
+ */
+export const EXTRACTION_BUDGET_MS = 10_000;
+/** What a document answers when its worker failed outside the parser: never the worker's own error. */
+export const EXTRACTION_WORKER_FAILED = 'could not be read: its extraction failed on the server; try again later';
+/**
+ * The one place a document's extractor runs (see {@link IDocumentExtractor}):
+ * a pooled worker thread — the extraction worker kind of the shared
+ * {@link WorkerPool}, which `grep`'s regex matcher is the other kind of —
+ * under a budget per file.
+ *
+ * The bytes are COPIED once on the request thread and the copy transferred,
+ * so the caller's buffer (already hashed for the cache key, and possibly a
+ * slice of Node's shared pool) is never detached. Past the budget the worker is
+ * terminated, which stops a parser mid-loop, and the file answers the timeout
+ * notice. A worker that answers with a dangling rejection, raises, or dies is
+ * never reused; the pool replaces it. A rejection the worker cannot pin on
+ * this job — it had served another before (see `serveExtractions`) — runs the
+ * job again in a fresh worker, so one file's failure is never another's.
+ */
+export class WorkerDocumentExtractor {
+    budgetMs;
+    pool;
+    nextJob = 1;
+    closing = false;
+    constructor(opts = {}) {
+        this.budgetMs = sizingOption('WorkerDocumentExtractor', 'budgetMs', opts.budgetMs ?? EXTRACTION_BUDGET_MS, 1, MAX_TIMER_MS);
+        const entry = opts.entry ?? defaultEntry();
+        this.pool = new WorkerPool(() => new Worker(entry.url, { execArgv: entry.execArgv }), {
+            // Three documents extracted at once each get a worker of their own.
+            poolMax: sizingOption('WorkerDocumentExtractor', 'poolMax', opts.poolMax ?? 4, 1),
+            maxWaiting: sizingOption('WorkerDocumentExtractor', 'maxWaiting', opts.maxWaiting ?? 32, 0),
+        }, () => new ExtractionBusyError());
+    }
+    async extract(extension, bytes) {
+        const first = await this.attempt(extension, bytes, this.budgetMs, false);
+        if (!('unattributed' in first))
+            return first;
+        // A rejection came while a worker that had served another job ran this one,
+        // and may be that job's: run it again where it is the first job, so what
+        // the file is answered (and remembered) as is its own. With the WHOLE
+        // budget again: the first run was cut short by another file's leftover,
+        // not by this file, and a run given only what was left would time out a
+        // sound document — and remember that timeout for an hour.
+        const again = await this.attempt(extension, bytes, this.budgetMs, true);
+        // In a fresh worker the worker never answers `unattributed`; a crash of the moment if it ever did —
+        // and never with that rejection's words, which may be another file's.
+        return 'unattributed' in again ? { ok: false, failure: 'crashed', message: EXTRACTION_WORKER_FAILED } : again;
+    }
+    async attempt(extension, bytes, budgetMs, fresh) {
+        let w;
+        try {
+            w = await (fresh ? this.pool.acquireFresh() : this.pool.acquire());
+        }
+        catch {
+            return busy();
+        }
+        const copy = new Uint8Array(bytes);
+        const job = { id: this.nextJob++, extension, bytes: copy };
+        const outcome = await exchange(w, job, budgetMs, [copy.buffer]);
+        if ('timeout' in outcome) {
+            this.pool.discard(w);
+            return { ok: false, failure: 'timeout', message: extractionTimeoutNotice(this.budgetMs) };
+        }
+        if ('error' in outcome) {
+            // Raised outside every guard the worker installs — its script failed to
+            // load, or it ran out of memory: a fault of the moment rather than of
+            // the bytes. The worker is ending, and the pool replaces it. What went
+            // wrong is the server's (a module path, a heap size): logged here, and
+            // the reader is told — and the hour remembers — the same words each time.
+            log.error('an extraction worker failed', { err: outcome.error });
+            return { ok: false, failure: 'crashed', message: EXTRACTION_WORKER_FAILED };
+        }
+        if ('exited' in outcome) {
+            if (this.closing)
+                return busy();
+            // Exit 0 is the worker ending itself over an earlier job's straggler that
+            // landed between jobs (see `serveExtractions`), after this job was posted
+            // but before it was taken up: it says nothing about this file. Run it
+            // again in a fresh worker, as for any rejection it cannot pin on this job.
+            if (outcome.exited === 0 && !fresh)
+                return { unattributed: true, message: EXTRACTION_WORKER_FAILED };
+            return {
+                ok: false,
+                failure: 'crashed',
+                message: `could not be read: its extraction stopped unexpectedly (exit code ${outcome.exited})`,
+            };
+        }
+        const { reply } = outcome;
+        if (reply.retire)
+            this.pool.discard(w);
+        else
+            this.pool.release(w);
+        if (reply.unattributed && !reply.ok)
+            return { unattributed: true, message: reply.message };
+        return reply.ok
+            ? { ok: true, summary: reply.summary, text: reply.text }
+            : { ok: false, failure: reply.transient ? 'crashed' : 'parser', message: reply.message };
+    }
+    close() {
+        this.closing = true;
+        return this.pool.close();
+    }
+}
+/** Every worker busy and the queue for one full. */
+class ExtractionBusyError extends Error {
+    constructor() {
+        super('every extraction worker is busy');
+        this.name = 'ExtractionBusyError';
+    }
+}
+function busy() {
+    return {
+        ok: false,
+        failure: 'busy',
+        message: 'could not be read: too many documents are being extracted at once; try again in a few seconds',
+    };
+}
+/**
+ * The document extractors' worker, beside this module. Run from the build it
+ * is plain JavaScript; run from source (the test suites) it is TypeScript,
+ * which a worker thread loads through `tsx`, as the suites themselves are.
+ */
+function defaultEntry() {
+    const fromSource = import.meta.url.endsWith('.ts');
+    return {
+        url: new URL(fromSource ? './extract.worker.ts' : './extract.worker.js', import.meta.url),
+        execArgv: fromSource ? ['--import', 'tsx'] : [],
+    };
+}
+//# sourceMappingURL=extract-in-worker.js.map

package/dist/modules/workspace/file-readers/extract-in-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-in-worker.js","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/extract-in-worker.ts"],"names":[],"mappings":"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"}

package/dist/modules/workspace/file-readers/extract-pdf.d.ts

@@ -1,3 +1,5 @@
 import type { ExtractResult } from './doc-extract.types.js';
 export declare function extractPdf(bytes: Buffer): Promise<ExtractResult>;
+/** What a PDF read answers when pdf.js itself failed to load: the same words, whatever the cause. */
+export declare const READER_DID_NOT_LOAD = "could not be read: the PDF reader did not load on the server; try again later";
 //# sourceMappingURL=extract-pdf.d.ts.map

package/dist/modules/workspace/file-readers/extract-pdf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-pdf.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/extract-pdf.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAwD5D,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA+GtE"}
+{"version":3,"file":"extract-pdf.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/file-readers/extract-pdf.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AA2D5D,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAyHtE;AAED,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,kFAAkF,CAAC"}

package/dist/modules/workspace/file-readers/extract-pdf.js

@@ -1,4 +1,6 @@
 import { MAX_DOC_PART_BYTES } from './ooxml-text.js';
+import { logger } from '../../../shared/logging.js';
+const log = logger('documents');
 /**
  * Extract a PDF's TEXT LAYER page by page with pdf.js (`pdfjs-dist`,
  * Mozilla's maintained renderer — chosen over the unmaintained thin wrappers
@@ -61,9 +63,20 @@ export async function extractPdf(bytes) {
     // The loading TASK is what gets destroyed at the end, not the document:
     // pdf.js 6 dropped `PDFDocumentProxy.destroy()`, and destroying the task
     // frees the document (and its pages) with it — the shape the viewer uses.
+    let getDocument;
+    try {
+        ({ getDocument } = await loadPdfJs());
+    }
+    catch (err) {
+        // The reader, not the file: a later read must try this file again. Why
+        // it did not load is the server's to know (a module path, a missing
+        // dependency) — logged here, never quoted to the reader.
+        log.error('the PDF reader did not load', { err });
+        return { ok: false, transient: true, message: READER_DID_NOT_LOAD };
+    }
     let task;
     try {
-        task = await openPdf(bytes);
+        task = openPdf(getDocument, bytes);
     }
     catch (err) {
         return { ok: false, message: `could not be parsed as a PDF (${err.message})` };
@@ -167,8 +180,10 @@ export async function extractPdf(bytes) {
         await task.destroy();
     }
 }
+/** What a PDF read answers when pdf.js itself failed to load: the same words, whatever the cause. */
+export const READER_DID_NOT_LOAD = 'could not be read: the PDF reader did not load on the server; try again later';
 let pdfjsPromise;
-async function openPdf(bytes) {
+function loadPdfJs() {
     pdfjsPromise ??= import('pdfjs-dist/legacy/build/pdf.mjs').catch((err) => {
         // A FAILED load must not be memoized: left in place, the rejected promise
         // would answer every later read and disable PDF extraction for the whole
@@ -176,7 +191,9 @@ async function openPdf(bytes) {
         pdfjsPromise = undefined;
         throw err;
     });
-    const { getDocument } = await pdfjsPromise;
+    return pdfjsPromise;
+}
+function openPdf(getDocument, bytes) {
     // Returns the loading task; the caller awaits `.promise` for the document
     // and destroys the task when done (see `extractPdf`).
     return getDocument({