@bevel-software/platform-core-backend 0.11.1 → 0.12.0

package/src/modules/workspace/file-readers/extract-msg.ts

@@ -0,0 +1,134 @@
+import MsgReaderImport from '@kenjiuno/msgreader';
+import type { ExtractResult } from './doc-extract.types.js';
+import { emailExtraction, htmlToEmailText, type EmailAttachment, type EmailModel } from './email-text.js';
+import { MAX_DOC_PART_BYTES } from './ooxml-text.js';
+
+/**
+ * Extract a `.msg` (Outlook item, CFB container) email into the shared email
+ * text shape (see `email-text.ts`).
+ *
+ * Parsing is `@kenjiuno/msgreader` (HiraokaHyperTools, Apache-2.0) — the
+ * maintained MAPI/CFB reader. It never throws for bad content of its own
+ * accord: unparseable bytes come back as `{ dataType: null, error }`, which
+ * maps onto the typed could-not-be-parsed failure here.
+ *
+ * Body preference mirrors `.eml`: the plain-text `PidTagBody` first, an HTML
+ * body stripped to text second. An Outlook item whose body exists ONLY as
+ * compressed RTF is degraded honestly — the extraction says
+ * "[body is RTF; no plain-text part]" instead of pretending to decode RTF.
+ */
+export function extractMsg(bytes: Buffer): ExtractResult {
+  if (bytes.length > MAX_DOC_PART_BYTES) {
+    return {
+      ok: false,
+      message: `could not be extracted as a .msg (the file is ${bytes.length} bytes — over the ${MAX_DOC_PART_BYTES}-byte (50 MB) extraction limit)`,
+    };
+  }
+  let fields: FieldsData;
+  try {
+    // DataView over the Buffer's exact region — no copy, and msgreader never
+    // sees bytes outside the file.
+    fields = new MsgReader(new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)).getFileData();
+  } catch (err) {
+    return { ok: false, message: `could not be parsed as a .msg (${(err as Error).message})` };
+  }
+  if (fields.dataType !== 'msg') {
+    return {
+      ok: false,
+      message: `could not be parsed as a .msg (${fields.error ?? 'not an Outlook message file'})`,
+    };
+  }
+  return { ok: true, ...emailExtraction(msgModel(fields)) };
+}
+
+/** msgreader's field data, shaped into the format-independent email model. */
+function msgModel(fields: FieldsData): EmailModel {
+  const recipients = fields.recipients ?? [];
+  const text = fields.body !== undefined && fields.body.trim() !== '' ? fields.body : undefined;
+  const html = htmlBody(fields);
+  const body = text ?? (html !== undefined ? htmlToEmailText(html) : '');
+  const bodySource: EmailModel['bodySource'] =
+    text !== undefined ? 'text' : html !== undefined ? 'html' : fields.compressedRtf !== undefined ? 'rtf-only' : 'none';
+  const date = fields.clientSubmitTime ?? fields.messageDeliveryTime;
+  return {
+    from: mailboxText(fields.senderName, fields.senderSmtpAddress ?? fields.senderEmail),
+    to: recipientList(recipients, 'to'),
+    cc: recipientList(recipients, 'cc'),
+    bcc: recipientList(recipients, 'bcc'),
+    subject: fields.subject,
+    date: date !== undefined ? isoDate(date) : undefined,
+    body: body.replace(/\s+$/, ''),
+    bodySource,
+    attachments: (fields.attachments ?? []).map(
+      (a): EmailAttachment => ({
+        name: a.fileName ?? a.fileNameShort ?? a.name ?? 'unnamed attachment',
+        mimeType: a.attachMimeTag,
+        sizeBytes: a.contentLength,
+      }),
+    ),
+  };
+}
+
+/** The HTML body, whichever MAPI property carries it (string, or utf-8 bytes). */
+function htmlBody(fields: FieldsData): string | undefined {
+  if (fields.bodyHtml !== undefined && fields.bodyHtml.trim() !== '') return fields.bodyHtml;
+  if (fields.html instanceof Uint8Array && fields.html.length > 0) {
+    return Buffer.from(fields.html).toString('utf8');
+  }
+  return undefined;
+}
+
+/** `Name <addr>` / `Name` / `addr` — whatever the message carries. */
+function mailboxText(name: string | undefined, address: string | undefined): string | undefined {
+  const n = name?.trim() ?? '';
+  const a = address?.trim() ?? '';
+  if (n !== '' && a !== '' && n !== a) return `${n} <${a}>`;
+  if (a !== '') return a;
+  return n !== '' ? n : undefined;
+}
+
+/**
+ * The bucket a recipient belongs to. msgreader maps the MAPI `PidTagRecipientType`
+ * values 1/2/3 to these strings itself (lib/MsgReader.js, the `recipType` case)
+ * — but ONLY those three: any other raw PT_LONG value, e.g. `MAPI_TO | MAPI_P1`
+ * (0x10000001) on a resubmitted message, leaks through as a NUMBER despite the
+ * `'to' | 'cc' | 'bcc'` typing. Mask the resubmit/submitted flag bits and remap
+ * so such a recipient keeps its line instead of vanishing; anything else
+ * (including untyped) counts as `to`, matching the frontend's `msgMessage.ts`.
+ */
+function recipientBucket(recipType: unknown): 'to' | 'cc' | 'bcc' {
+  if (recipType === 'to' || recipType === 'cc' || recipType === 'bcc') return recipType;
+  if (typeof recipType === 'number') {
+    const base = recipType & 0x0fffffff; // strip MAPI_SUBMITTED (0x80000000) / MAPI_P1 (0x10000000)
+    if (base === 2) return 'cc';
+    if (base === 3) return 'bcc';
+  }
+  return 'to';
+}
+
+/** The comma-joined mailboxes of one recipient type. Untyped recipients count as `to`. */
+function recipientList(recipients: readonly FieldsData[], type: 'to' | 'cc' | 'bcc'): string | undefined {
+  const s = recipients
+    .filter((r) => recipientBucket(r.recipType) === type)
+    .map((r) => mailboxText(r.name, r.smtpAddress ?? r.email))
+    .filter((t): t is string => t !== undefined)
+    .join(', ');
+  return s === '' ? undefined : s;
+}
+
+/** msgreader emits RFC-1123 GMT strings; normalize to ISO, keep raw when unparseable. */
+function isoDate(value: string): string {
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? value : d.toISOString();
+}
+
+/**
+ * CJS/ESM interop: msgreader is CJS with a transpiled `exports.default`.
+ * Vitest's transform hands the class straight through the default import, but
+ * NATIVE Node ESM (the built `dist/`) hands the exports OBJECT — so unwrap
+ * `.default` when it is there.
+ */
+type MsgReaderClass = typeof MsgReaderImport;
+const MsgReader: MsgReaderClass =
+  (MsgReaderImport as unknown as { default?: MsgReaderClass }).default ?? MsgReaderImport;
+type FieldsData = ReturnType<InstanceType<MsgReaderClass>['getFileData']>;

package/src/modules/workspace/file-readers/extract-odp.ts

@@ -0,0 +1,63 @@
+import type { ExtractResult } from './doc-extract.types.js';
+import { odfParagraphLines, readOdfContentXml } from './odf-text.js';
+import { localBlocks, localElementBlocks, removeLocalElements } from './ooxml-text.js';
+
+/**
+ * Extract the text of a `.odp` (OpenDocument Presentation) deck.
+ *
+ * Slides are the `<draw:page>` elements of `content.xml`, in DOCUMENT order —
+ * ODF orders slides in the file itself, so unlike pptx there is no numeric
+ * filename sort. Each slide is emitted under a `[slide N]` marker (N = 1-based
+ * position); speaker notes (`<presentation:notes>` inside the page) follow
+ * under `[slide N notes]` when non-empty. Within a slide, each `<text:p>` in
+ * its frames is a line; spans concatenate with no separator.
+ */
+export function extractOdp(bytes: Buffer): ExtractResult {
+  const content = readOdfContentXml(bytes, '.odp');
+  if (!content.ok) return content;
+
+  const pages = drawPageBlocks(content.xml);
+  if (pages.length === 0) {
+    return { ok: false, message: 'could not be parsed as a .odp (no draw:page elements in content.xml)' };
+  }
+
+  const lines: string[] = [];
+  let anyNotes = false;
+  pages.forEach((page, i) => {
+    // Split the notes part out FIRST so its paragraphs don't render as slide text.
+    // Notes read by the parser and matched on their LOCAL name: a comment that
+    // resembled `<presentation:notes>` used to be emitted as real speaker notes,
+    // and a deck binding the presentation namespace to another prefix had none.
+    const notesXml = localBlocks(page, 'notes')[0] ?? '';
+    // The slide's own text is the page with the notes ELEMENTS removed by
+    // their parsed boundaries — global string replacement of the notes BODY
+    // also deleted slide text that happened to serialize identically to it.
+    const slideXml = removeLocalElements(page, ['notes']);
+    lines.push(`[slide ${i + 1}]`);
+    lines.push(...odfParagraphLines(slideXml));
+    const noteLines = odfParagraphLines(notesXml);
+    if (noteLines.length > 0) {
+      anyNotes = true;
+      lines.push(`[slide ${i + 1} notes]`);
+      lines.push(...noteLines);
+    }
+  });
+  return {
+    ok: true,
+    summary: `${pages.length} slide${pages.length === 1 ? '' : 's'}${anyNotes ? ' + notes' : ''}; layout, images and formatting omitted`,
+    text: lines.join('\n'),
+  };
+}
+
+/**
+ * The `<draw:page>…</draw:page>` bodies in document order (pages never nest).
+ * A SELF-CLOSING `<draw:page/>` is a legal, fully blank slide — it yields ''
+ * so the deck's numbering (and a deliberately blank deck) stays correct.
+ */
+function drawPageBlocks(xml: string): string[] {
+  // The shared quote-aware scanner: a `/>` INSIDE a quoted attribute value (a
+  // page name like `a/>b`) is part of the value, never the self-closing
+  // delimiter, and a page whose close tag is missing costs one scan of the
+  // document rather than one per opener (see `xmlElementBlocks`).
+  return localElementBlocks(xml, ['page']).map((e) => e.body ?? '');
+}

package/src/modules/workspace/file-readers/extract-ods.ts

@@ -0,0 +1,182 @@
+import type { ExtractResult } from './doc-extract.types.js';
+import {
+  attrByLocalName,
+  decodeXmlEntities,
+  localElementBlocks,
+  localName,
+  walkLocalElementBlocks,
+} from './ooxml-text.js';
+import {
+  odfParagraphBlocks,
+  odfParagraphText,
+  readOdfContentXml,
+} from './odf-text.js';
+
+/**
+ * Per-sheet extraction caps — the SAME bounds as the xlsx extractor. ODF is
+ * fond of `table:number-columns-repeated="16384"` (or a million empty trailing
+ * rows) to pad a sheet to the grid, so repeats are expanded BOUNDED and the
+ * extraction says when it truncated (a `[sheet truncated …]` line right under
+ * the sheet marker). Trailing EMPTY cells/rows are trimmed before their
+ * repeats are applied at all, so grid padding never counts as truncation.
+ */
+const MAX_ROWS_PER_SHEET = 10_000;
+const MAX_COLS_PER_SHEET = 200;
+
+/**
+ * Extract a `.ods` (OpenDocument Spreadsheet) workbook: per `<table:table>`
+ * (sheet) a `[sheet: Name]` marker (the `table:name` attribute), then the rows
+ * as tab-separated cell text. A cell's text is its `<text:p>` content
+ * (multiple paragraphs join with a space — a newline would break the row
+ * line); covered cells (under a merge) render empty.
+ */
+export function extractOds(bytes: Buffer): ExtractResult {
+  const content = readOdfContentXml(bytes, '.ods');
+  if (!content.ok) return content;
+
+  const tables = tableBlocks(content.xml);
+  if (tables.length === 0) {
+    return { ok: false, message: 'could not be parsed as a .ods (no table:table elements in content.xml)' };
+  }
+
+  const lines: string[] = [];
+  for (const table of tables) {
+    lines.push(`[sheet: ${table.name}]`);
+    const { rows, truncated } = expandRows(table.xml);
+    if (truncated.length > 0) lines.push(`[sheet truncated to the ${truncated.join(' and ')}]`);
+    lines.push(...rows.map((cells) => cells.join('\t')));
+  }
+  return {
+    ok: true,
+    summary: `${tables.length} sheet${tables.length === 1 ? '' : 's'}, rows as tab-separated values; formulas, formatting and charts omitted`,
+    text: lines.join('\n'),
+  };
+}
+
+/**
+ * The `<table:table>` blocks with their decoded `table:name`, in document
+ * order. Non-greedy close — a nested table (legal in ODF text documents, not
+ * produced by spreadsheets) would end the outer block early, degrading
+ * grouping but never crashing.
+ */
+function tableBlocks(xml: string): Array<{ name: string; xml: string }> {
+  // Read by the parser and matched on the LOCAL name: a comment or CDATA
+  // section holding a table-looking fragment used to answer as a real sheet,
+  // and a document binding the table namespace to another prefix had none.
+  const out: Array<{ name: string; xml: string }> = [];
+  for (const table of localElementBlocks(xml, ['table'])) {
+    const raw = attrByLocalName(table.attributes, 'name');
+    out.push({
+      // Control separators become spaces: a name holding an encoded newline
+      // or tab (`&#10;`) would corrupt the `[sheet: …]` marker's own line and
+      // the TSV structure under it.
+      name: raw ? decodeXmlEntities(raw).replace(/[\t\n\r]+/g, ' ') : `Sheet${out.length + 1}`,
+      xml: table.body ?? '',
+    });
+  }
+  return out;
+}
+
+/**
+ * Expand a sheet's rows with BOUNDED repeat handling, INCREMENTALLY — a row's
+ * expansion lands in the capped output as it parses, so the caps bound memory
+ * as well as output (materializing every row's cells before consulting the
+ * cap let an accepted ODS allocate its whole expansion first):
+ *
+ *  - all-empty rows are buffered as a COUNT (with their
+ *    `table:number-rows-repeated` applied) and flushed only when a non-empty
+ *    row follows, so a million-row empty tail simply disappears,
+ *  - once the row cap is hit, the remaining rows are never parsed at all.
+ *
+ * `truncated` lists what the caps cut (mirrors the xlsx extractor's note).
+ */
+function expandRows(tableXml: string): { rows: string[][]; truncated: string[] } {
+  // The shared quote-aware scanner as a WALK, not an array: materializing
+  // every row block before consulting the cap let a sheet of >10k explicit
+  // rows allocate them all first. Each row lands here as it parses, and the
+  // visitor's `true` stops the scan at the cap — a self-closing row WITH
+  // attributes is still a row, a `/>` inside a quoted attribute value is not
+  // a delimiter, and an UNCLOSED row costs one scan of the sheet rather than
+  // one per opener (see `xmlElementBlocks`).
+  const rows: string[][] = [];
+  let pendingEmpty = 0;
+  let rowsTruncated = false;
+  let colsTruncated = false;
+  walkLocalElementBlocks(tableXml, ['table-row'], (row) => {
+    const repeat = repeatCount(attrByLocalName(row.attributes, 'number-rows-repeated'));
+    const cells = expandCells(row.body ?? '');
+    if (cells.cells.length === 0) {
+      // Empty rows are interior padding until a non-empty row proves it —
+      // trailing ones are dropped with their repeats (grid padding, not data).
+      pendingEmpty += repeat;
+      return false;
+    }
+    if (cells.truncated) colsTruncated = true;
+    for (; pendingEmpty > 0 && rows.length < MAX_ROWS_PER_SHEET; pendingEmpty--) rows.push([]);
+    let i = 0;
+    for (; i < repeat && rows.length < MAX_ROWS_PER_SHEET; i++) rows.push(cells.cells);
+    if (pendingEmpty > 0 || i < repeat) {
+      // The cap cut real content (a sheet that merely FILLS it is not truncated).
+      rowsTruncated = true;
+      return true;
+    }
+    return false;
+  });
+  const truncated: string[] = [];
+  if (rowsTruncated) truncated.push(`first ${MAX_ROWS_PER_SHEET} rows`);
+  if (colsTruncated) truncated.push(`first ${MAX_COLS_PER_SHEET} columns`);
+  return { rows, truncated };
+}
+
+/**
+ * One row's cell texts: `<table:table-cell>` / `<table:covered-table-cell>`
+ * in order, expanded INCREMENTALLY like the rows above — trailing EMPTY cells
+ * are buffered as a count (their `table:number-columns-repeated` never
+ * expands) and the parse stops at the column cap.
+ */
+function expandCells(rowXml: string): { cells: string[]; truncated: boolean } {
+  // Same walking scanner as the rows above — a row spelling a million
+  // explicit cells stops parsing at the column cap too.
+  const cells: string[] = [];
+  let pendingEmpty = 0;
+  let truncated = false;
+  walkLocalElementBlocks(rowXml, ['table-cell', 'covered-table-cell'], (cell) => {
+    const repeat = repeatCount(attrByLocalName(cell.attributes, 'number-columns-repeated'));
+    // Covered cells carry no own text anyway. Element-produced newlines/tabs
+    // INSIDE a cell (<text:line-break/>, <text:tab/>) become single spaces:
+    // the extraction's contract is one row per line with tab-separated cells,
+    // and a literal \n or \t inside a cell's text would silently break both.
+    // A COVERED cell is the hidden half of a merge: the visible cell carries
+    // the text. Such a cell may still hold stale content, and emitting it put
+    // a value in the grid where the sheet shows none.
+    const text = localName(cell.name) === 'covered-table-cell'
+      ? ''
+      : odfParagraphBlocks(cell.body ?? '')
+          .map(odfParagraphText)
+          .join(' ')
+          .replace(/[\t\n\r]+/g, ' ');
+    if (text === '') {
+      pendingEmpty += repeat;
+      return false;
+    }
+    for (; pendingEmpty > 0 && cells.length < MAX_COLS_PER_SHEET; pendingEmpty--) cells.push('');
+    let i = 0;
+    for (; i < repeat && cells.length < MAX_COLS_PER_SHEET; i++) cells.push(text);
+    if (pendingEmpty > 0 || i < repeat) {
+      // The cap cut real content (a row that merely FILLS it is not truncated).
+      truncated = true;
+      return true;
+    }
+    return false;
+  });
+  return { cells, truncated };
+}
+
+/** A `…-repeated="N"` attribute value, clamped to a sane positive integer. */
+function repeatCount(raw: string | undefined): number {
+  // Decoded first: the block scanner hands attribute values RAW, and a repeat
+  // legally written with character references (`&#49;&#48;`) must count as
+  // 10, not silently fall back to 1.
+  const n = raw !== undefined ? parseInt(decodeXmlEntities(raw), 10) : 1;
+  return Number.isFinite(n) && n >= 1 ? n : 1;
+}

package/src/modules/workspace/file-readers/extract-odt.ts

@@ -0,0 +1,48 @@
+import type { ExtractResult } from './doc-extract.types.js';
+import { localBlocks, removeLocalElements } from './ooxml-text.js';
+import { odfParagraphBlocks, odfParagraphText, readOdfContentXml } from './odf-text.js';
+
+/**
+ * Extract the BODY text of a `.odt` (OpenDocument Text) document.
+ *
+ * An odt is a zip whose main part is `content.xml`; the body lives under
+ * `<office:text>`. Headers/footers are skipped like docx — in ODF they live in
+ * `styles.xml`, which is never opened, so reading `content.xml` alone IS the
+ * body-only extraction.
+ *
+ * Paragraphs (`<text:p>`) and headings (`<text:h>`, heading text as its own
+ * line) become lines in document order; `<text:span>` runs inside concatenate
+ * with NO separator, and the ODF whitespace elements (`<text:tab/>`,
+ * `<text:line-break/>`, `<text:s text:c="N"/>`) render as real characters —
+ * see `odfParagraphText`.
+ */
+export function extractOdt(bytes: Buffer): ExtractResult {
+  const content = readOdfContentXml(bytes, '.odt');
+  if (!content.ok) return content;
+
+  // Table cells contain their own <text:p>, so the flat paragraph scan renders
+  // table text too (one line per cell paragraph, like the raw document order).
+  // The text BODY, read by the parser and matched on its LOCAL name: a
+  // comment mentioning `</office:text>` used to terminate the body early and
+  // drop every paragraph after it, and an ODT binding the office namespace to
+  // another prefix had no body at all.
+  const body = localBlocks(content.xml, 'text')[0] ?? content.xml;
+
+  // Tracked-change bookkeeping is not body text: `<text:tracked-changes>`
+  // stores every DELETION's content as ordinary paragraphs, so the flat scan
+  // below would read deleted text back in as document lines. Removed by its
+  // parsed element boundaries before the paragraph walk.
+  // `<office:annotation>` is a COMMENT on the document, stored as ordinary
+  // paragraphs: read flat, a reviewer's note came back as a document line.
+  const visible = removeLocalElements(body, ['tracked-changes', 'annotation']);
+
+  const lines = odfParagraphBlocks(visible).map(odfParagraphText);
+  const paragraphs = lines.length;
+  while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop();
+
+  return {
+    ok: true,
+    summary: `${paragraphs} paragraph${paragraphs === 1 ? '' : 's'}; layout, images and formatting omitted`,
+    text: lines.join('\n'),
+  };
+}

package/src/modules/workspace/file-readers/extract-pdf.ts

@@ -0,0 +1,178 @@
+import type { ExtractResult } from './doc-extract.types.js';
+import { MAX_DOC_PART_BYTES } from './ooxml-text.js';
+
+/**
+ * Extract a PDF's TEXT LAYER page by page with pdf.js (`pdfjs-dist`,
+ * Mozilla's maintained renderer — chosen over the unmaintained thin wrappers
+ * around it). The LEGACY build is the one supported under Node; it is loaded
+ * lazily (and once) because it is a heavyweight module most deployments only
+ * need after the first PDF read.
+ *
+ * Layout heuristic: text items on one line are joined with single spaces; a
+ * new line starts when pdf.js flags an EOL or the item's Y position jumps.
+ * A PDF with NO text layer (a scan) extracts to just the `[page N]` markers,
+ * and the summary says "no text layer (scanned document?)" — no OCR in v1.
+ */
+/**
+ * How much DECODED text one PDF may yield before extraction gives up.
+ *
+ * The raw-size cap below bounds what arrives; it does not bound what comes
+ * out. PDF text lives in compressed streams, so a file comfortably under
+ * 50 MB can decode to far more than that, and every character of it is held
+ * in `lines` until the extraction returns. This bound is the decoded
+ * counterpart, checked as the text accumulates rather than after.
+ */
+const MAX_PDF_TEXT_CHARS = 20 * 1024 * 1024; // 20M chars of extracted text
+
+/**
+ * How many pages one PDF may have before extraction gives up.
+ *
+ * The decoded-text bound does not cover a document whose cost is its PAGE
+ * COUNT rather than its prose: every page costs a `getPage`, a
+ * `getTextContent` and a retained `[page N]` marker even when it holds no
+ * text at all, so a file declaring hundreds of thousands of empty pages spends
+ * minutes and megabytes without ever tripping a character budget. Real
+ * documents do not come close — a 2,000-page manual is an outlier.
+ */
+const MAX_PDF_PAGES = 10_000;
+
+/**
+ * How many text items one PAGE may hold. Items arrive through
+ * `streamTextContent` in small chunks (~100 items each), so this bound — like
+ * the character budget — fires while the page is still streaming, not after
+ * it has materialized. It exists because item COUNT is its own cost: each
+ * item is a retained heap object, and a page of empty-string items would
+ * never trip the character budget.
+ */
+const MAX_PDF_ITEMS_PER_PAGE = 200_000;
+
+/** The typed failure both decoded-text bounds return. */
+function overBudget(): ExtractResult {
+  return {
+    ok: false,
+    message: `could not be extracted as a PDF (its text decodes to over ${MAX_PDF_TEXT_CHARS} characters — over the extraction limit)`,
+  };
+}
+
+export async function extractPdf(bytes: Buffer): Promise<ExtractResult> {
+  // The same bounded-read guard the zip-based extractors apply per part: a
+  // PDF has no compressed container to pre-scan, so the bound is simply the
+  // file's raw size, checked before pdf.js parses anything.
+  if (bytes.length > MAX_DOC_PART_BYTES) {
+    return {
+      ok: false,
+      message: `could not be extracted as a PDF (the file is ${bytes.length} bytes — over the ${MAX_DOC_PART_BYTES}-byte (50 MB) extraction limit)`,
+    };
+  }
+  let doc: Awaited<ReturnType<typeof openPdf>>;
+  try {
+    doc = await openPdf(bytes);
+  } catch (err) {
+    return { ok: false, message: `could not be parsed as a PDF (${(err as Error).message})` };
+  }
+  try {
+    if (doc.numPages > MAX_PDF_PAGES) {
+      return {
+        ok: false,
+        message: `could not be extracted as a PDF (it declares ${doc.numPages} pages — over the ${MAX_PDF_PAGES}-page extraction limit)`,
+      };
+    }
+    const lines: string[] = [];
+    let textChars = 0;
+    let anyText = false;
+    for (let n = 1; n <= doc.numPages; n++) {
+      lines.push(`[page ${n}]`);
+      // The marker is retained text like any other line: a document whose cost
+      // is its page count must reach the same bound as one whose cost is prose.
+      textChars += n.toString().length + 8;
+      if (textChars > MAX_PDF_TEXT_CHARS) return overBudget();
+      const page = await doc.getPage(n);
+      // `streamTextContent` delivers the page's items in small chunks (~100
+      // items each, `getTextContent` is just this stream materialized), so
+      // both budgets fire WHILE the page streams: a crafted single page can
+      // no longer build its whole item array before a bound trips. Once one
+      // does, the reader is cancelled and pdf.js stops producing.
+      const reader = (
+        page.streamTextContent() as ReadableStream<Awaited<ReturnType<typeof page.getTextContent>>>
+      ).getReader();
+      let pageItems = 0;
+      let line = '';
+      let lastY: number | undefined;
+      const flush = (): void => {
+        if (line.trim() !== '') {
+          lines.push(line);
+          anyText = true;
+          // The '\n' the final join emits for this line is retained text too.
+          textChars += 1;
+        }
+        line = '';
+      };
+      for (;;) {
+        const { done, value: chunk } = await reader.read();
+        if (done) break;
+        pageItems += chunk.items.length;
+        if (pageItems > MAX_PDF_ITEMS_PER_PAGE) {
+          await reader.cancel().catch(() => undefined);
+          page.cleanup();
+          return {
+            ok: false,
+            message: `could not be extracted as a PDF (page ${n} holds more than ${MAX_PDF_ITEMS_PER_PAGE} text items — over the extraction limit)`,
+          };
+        }
+        for (const item of chunk.items) {
+          if (!('str' in item)) continue; // marked-content item — no text
+          const y = item.transform?.[5];
+          // Y-position jump = new visual line (1pt tolerance for kerning wobble).
+          if (typeof y === 'number') {
+            if (lastY !== undefined && Math.abs(y - lastY) > 1) flush();
+            lastY = y;
+          }
+          if (item.str !== '') {
+            // COUNTED before it is kept — the join space included: the bound
+            // exists to stop the decoded text from accumulating, so it must
+            // fire mid-page and cover every character the result will hold.
+            textChars += item.str.length + (line === '' ? 0 : 1);
+            if (textChars > MAX_PDF_TEXT_CHARS) {
+              await reader.cancel().catch(() => undefined);
+              return overBudget();
+            }
+            line += (line === '' ? '' : ' ') + item.str;
+          }
+          if (item.hasEOL) flush();
+        }
+      }
+      flush();
+      page.cleanup();
+    }
+    const pages = `${doc.numPages} page${doc.numPages === 1 ? '' : 's'}`;
+    return anyText
+      ? { ok: true, summary: `${pages}; layout, images and formatting omitted`, text: lines.join('\n') }
+      : { ok: true, summary: `${pages}; no text layer (scanned document?)`, text: lines.join('\n') };
+  } catch (err) {
+    return { ok: false, message: `could not extract the PDF's text (${(err as Error).message})` };
+  } finally {
+    await doc.destroy();
+  }
+}
+
+type PdfJs = typeof import('pdfjs-dist/legacy/build/pdf.mjs');
+let pdfjsPromise: Promise<PdfJs> | undefined;
+
+async function openPdf(bytes: Buffer) {
+  pdfjsPromise ??= import('pdfjs-dist/legacy/build/pdf.mjs').catch((err: unknown) => {
+    // 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
+    // process. Reset so the next read retries the import.
+    pdfjsPromise = undefined;
+    throw err;
+  });
+  const { getDocument } = await pdfjsPromise;
+  return getDocument({
+    // Copy into a fresh Uint8Array: pdf.js TRANSFERS the buffer it is given
+    // (detaching it), and the caller's Buffer must stay usable for hashing.
+    data: new Uint8Array(bytes),
+    // Server side: no font rendering — text content is all we consume.
+    disableFontFace: true,
+    useSystemFonts: true,
+  }).promise;
+}