@bli-cockpit/cli 0.2.271 → 0.2.273

package/dist/cursors/raw-evidence-cursor.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { bookkeepingRead, bookkeepingWrite } from "../bookkeeping-session.js";
 import { describeError, isMissingFileFailure } from "../health-detail.js";
 /**
  * Durable local cursor for raw-evidence harvesting.
@@ -37,7 +38,22 @@ export function emptyRawEvidenceCursorState() {
         sessions: {},
     };
 }
+/**
+ * Inside a worktree-loop bookkeeping session the cursor is loaded once and handed out as one shared object
+ * (`bookkeeping-session.ts`, BLI-23346); anywhere else this is the plain disk read.
+ */
 export async function readRawEvidenceCursor(paths, options = {}) {
+    let key;
+    try {
+        key = rawEvidenceCursorPath(paths, options.filename);
+    }
+    catch {
+        // Paths without a cursors dir: the disk reader below reports it exactly as it always did.
+        return readRawEvidenceCursorFromDisk(paths, options);
+    }
+    return bookkeepingRead(key, () => readRawEvidenceCursorFromDisk(paths, options));
+}
+async function readRawEvidenceCursorFromDisk(paths, options) {
     try {
         const raw = JSON.parse(await fs.readFile(rawEvidenceCursorPath(paths, options.filename), "utf8"));
         return parseCursorState(raw);
@@ -59,6 +75,9 @@ export async function readRawEvidenceCursor(paths, options = {}) {
     }
 }
 export async function writeRawEvidenceCursor(paths, state, options = {}) {
+    await bookkeepingWrite(rawEvidenceCursorPath(paths, options.filename), state, (held) => writeRawEvidenceCursorToDisk(paths, held, options));
+}
+async function writeRawEvidenceCursorToDisk(paths, state, options) {
     const filePath = rawEvidenceCursorPath(paths, options.filename);
     await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
     const pruned = pruneCursorState(state);

package/dist/image-census-stream.js

@@ -17,11 +17,17 @@ import { isUtf8 } from "node:buffer";
 import { formatImageMarker } from "@bli-cockpit/telemetry-core";
 import { TranscriptNotStreamable } from "./adapters/transcript-text-stream.js";
 import { bytesMayHoldImage, scanImagesInLine } from "./image-byte-scan.js";
+import { bytesMayHoldPdf, scanPdfsInLine } from "./pdf-byte-scan.js";
 export async function censusOfLines(lines) {
-    const census = { total: 0, occurrences: [], unique: new Map(), tally: new Map() };
+    const census = { total: 0, occurrences: [], unique: new Map(), tally: new Map(), pdfs: [] };
     for await (const { start, bytes } of lines) {
         if (!isUtf8(bytes))
             throw new TranscriptNotStreamable("invalid_utf8");
+        if (bytesMayHoldPdf(bytes)) {
+            for (const pdf of scanPdfsInLine(bytes)) {
+                census.pdfs.push({ ...pdf, replaceStart: pdf.replaceStart + start, replaceEnd: pdf.replaceEnd + start, base64Start: pdf.base64Start + start, base64End: pdf.base64End + start });
+            }
+        }
         if (!bytesMayHoldImage(bytes))
             continue;
         for (const found of scanImagesInLine(bytes)) {

package/dist/image-description-session.js

@@ -11,6 +11,7 @@ import { sendPendingImages } from "./image-description-send.js";
 import { resolveImageHandlingMode } from "./image-mode-state.js";
 import { censusOfLines } from "./image-census-stream.js";
 import { sha256OfBase64Run } from "./image-byte-scan.js";
+import { addPdfsToFinds, mergeOccurrences, pdfsOfText } from "./pdf-transcript-step.js";
 import { openPinnedTranscript } from "./adapters/pinned-transcript.js";
 import { openStagedOutput, readStagedText } from "./adapters/staged-output.js";
 import { TranscriptNotStreamable } from "./adapters/transcript-text-stream.js";
@@ -47,7 +48,12 @@ export async function openImageDescriptions(options) {
         isDescribed: (sha256) => described.has(imageStateKey(sha256)),
         hasDescribeRoom: (sha256s) => describeRoomLeft(run, sha256s),
         async prepareTranscript(input) {
-            const { replace, finds, ...afterImages } = await describeAndReplace(run, input, findsOfText(input.text));
+            // BLI-23347: in drop mode each base64 PDF becomes a marker block (its text, or its described page images).
+            const imageFinds = findsOfText(input.text);
+            const finds0 = mode === "describe_and_drop"
+                ? await addPdfsToFinds(imageFinds, pdfsOfText(input.text), pdfContext(run, { stateDir: options.stateDir, read: async (pdf) => input.text.slice(pdf.base64Start, pdf.base64End), changed: () => new Error("pdf_changed_in_text") }))
+                : imageFinds;
+            const { replace, finds, ...afterImages } = await describeAndReplace(run, input, finds0);
             if (mode !== "describe_and_drop")
                 return { ...afterImages, text: input.text, changed: false, slim: null };
             // BLI-23317: the image swap and the slim rules are ONE pass over the lines (one joined string, no
@@ -116,11 +122,17 @@ async function prepareFileInTwoPasses(run, input) {
         // Pass one: discover. Nothing of the text is kept; only where each image is and what it is.
         const census = await censusOfLines(source.lines());
         // Describe attempts finish and the swap decisions are settled before a single line is swapped, as with the whole text.
-        const { replace, finds: _finds, ...afterImages } = await describeAndReplace(run, input, findsOfCensus(census, source));
+        // BLI-23347: the census also found the PDFs; they are converted here and swapped in the same pass as the images.
+        const pdfFinds = await addPdfsToFinds(findsOfCensus(census, source), census.pdfs, pdfContext(run, {
+            stateDir: run.options.stateDir,
+            read: (pdf) => source.read(pdf.base64Start, pdf.base64End - pdf.base64Start),
+            changed: () => new TranscriptNotStreamable("file_changed_during_pass"),
+        }));
+        const { replace, finds, ...afterImages } = await describeAndReplace(run, input, pdfFinds);
         // Pass two: swap and slim over exactly the bytes pass one saw, writing the result to staging as it goes.
         writer = input.stageDir ? await openStagedOutput(input.stageDir) : undefined;
         const memory = writer ? undefined : new LineBytesSink(source.length);
-        const slim = await slimLineStream(source.lines(), input.source, census.occurrences, replace, writer ?? memory);
+        const slim = await slimLineStream(source.lines(), input.source, mergeOccurrences(census.occurrences, finds.extraOccurrences), replace, writer ?? memory);
         if (slim.replacedCount !== afterImages.replacedCount)
             throw new TranscriptNotStreamable("images_changed_between_passes");
         await source.verifyUnchanged();
@@ -202,14 +214,24 @@ function countImageSwaps(swap) {
     let replacedCount = 0;
     let charsSaved = 0;
     for (const image of swap.images) {
-        if (!swap.replace(image))
+        if (image.replacement === undefined && !swap.replace(image))
             continue;
-        const marker = formatImageMarker({ sha256: image.sha256, mediaType: image.mediaType, byteSize: image.byteSize });
+        const marker = image.replacement ?? formatImageMarker({ sha256: image.sha256, mediaType: image.mediaType, byteSize: image.byteSize });
         replacedCount += 1;
         charsSaved += image.replaceEnd - image.replaceStart - marker.length;
     }
     return { replacedCount, charsSaved };
 }
+/** What the PDF step needs from this run (BLI-23347); `described` is the same set the image step reads. */
+function pdfContext(run, parts) {
+    return {
+        key: run,
+        stateDir: parts.stateDir,
+        isDescribed: (sha256) => run.described.has(imageStateKey(sha256)),
+        readBase64: parts.read,
+        sourceChanged: parts.changed,
+    };
+}
 function selectImagesToDescribe(run, unique, counts) {
     const { described, settledThisRun, failedImages, now } = run;
     const toSend = [];

package/dist/pdf-byte-scan.js

@@ -0,0 +1,109 @@
+/**
+ * Find the base64 PDFs of one transcript line on its BYTES (BLI-23347), the PDF twin of `image-byte-scan.ts`.
+ *
+ * Claude Code stores a PDF it read twice on one line (`message.content[].content[].source.data` and
+ * `toolUseResult.file.base64`). Two shapes are recognised, both ASCII so a byte offset here is the character
+ * offset on ASCII text:
+ *
+ *  - a whole-string payload: a base64 run that starts right after a `"` with `JVBERi0` (the base64 of
+ *    `%PDF-`), is at least `PDF_MIN_BASE64_CHARS` long and is closed by `"` or by `\"` (a string that was
+ *    itself stored inside a string; `escapeDepth` says which, so the replacement is escaped to match);
+ *  - a data URL `data:application/pdf;base64,` followed by such a run; the whole URL is the replaced range.
+ *
+ * The run is hashed in blocks of 48 Ki characters straight from the line, so neither a string of the
+ * run nor a Buffer of the whole PDF exists here; the first block is sniffed for `%PDF-`. A run whose `=`
+ * characters are not plain trailing padding is not a PDF we can vouch for and is left alone.
+ */
+import { createHash } from "node:crypto";
+const QUOTE = 0x22;
+const BACKSLASH = 0x5c;
+const EQUALS = 0x3d;
+/** Characters per decoded block. A multiple of 4: each block is a whole number of base64 quanta. */
+const BLOCK_CHARS = 48 * 1024;
+/** Below this a "PDF" is a stub, not a document anyone read (a one-line minimal PDF is about 400 bytes). */
+export const PDF_MIN_BASE64_CHARS = 600;
+const BASE64 = new Uint8Array(256);
+for (const range of ["AZ", "az", "09"]) {
+    for (let code = range.charCodeAt(0); code <= range.charCodeAt(1); code += 1)
+        BASE64[code] = 1;
+}
+for (const char of "+/=")
+    BASE64[char.charCodeAt(0)] = 1;
+const START = Buffer.from("JVBERi0", "latin1");
+const DATA_URL = Buffer.from("data:application/pdf;base64,", "latin1");
+const PDF_MAGIC = Buffer.from("%PDF-", "latin1");
+/** Is there any chance this line holds a PDF? */
+export function bytesMayHoldPdf(line) {
+    return line.includes(START) || line.includes(DATA_URL);
+}
+function runEnd(line, from) {
+    let at = from;
+    while (at < line.length && BASE64[line[at]] === 1)
+        at += 1;
+    return at;
+}
+/** sha256 and decoded size of the PDF `line[from, to)` encodes, or null when it is not one we can vouch for. */
+export function digestPdfRun(line, from, to) {
+    const length = to - from;
+    const firstPad = line.subarray(from, to).indexOf(EQUALS);
+    if (firstPad !== -1) {
+        const padCount = length - firstPad;
+        if (padCount > 2 || length % 4 !== 0)
+            return null;
+        for (let at = from + firstPad; at < to; at += 1)
+            if (line[at] !== EQUALS)
+                return null;
+    }
+    const hash = createHash("sha256");
+    let byteSize = 0;
+    for (let at = from; at < to; at += BLOCK_CHARS) {
+        const block = Buffer.from(line.toString("latin1", at, Math.min(to, at + BLOCK_CHARS)), "base64");
+        if (at === from && block.compare(PDF_MAGIC, 0, PDF_MAGIC.length, 0, PDF_MAGIC.length) !== 0)
+            return null;
+        hash.update(block);
+        byteSize += block.byteLength;
+    }
+    return { sha256: hash.digest("hex"), byteSize };
+}
+/** Every embedded PDF in one physical line, in order, with byte offsets inside the line. */
+export function scanPdfsInLine(line) {
+    const found = [];
+    if (line.length < PDF_MIN_BASE64_CHARS)
+        return found;
+    let position = 0;
+    while (position < line.length) {
+        const quoted = nextQuotedStart(line, position);
+        const dataUrl = line.indexOf(DATA_URL, position);
+        if (quoted === -1 && dataUrl === -1)
+            break;
+        const useUrl = dataUrl !== -1 && (quoted === -1 || dataUrl < quoted);
+        const base64Start = useUrl ? dataUrl + DATA_URL.length : quoted;
+        const end = runEnd(line, base64Start);
+        position = Math.max(end, base64Start + 1);
+        if (end - base64Start < PDF_MIN_BASE64_CHARS)
+            continue;
+        let escapeDepth = 0;
+        if (!useUrl) {
+            const plain = end < line.length && line[end] === QUOTE;
+            const escaped = end + 1 < line.length && line[end] === BACKSLASH && line[end + 1] === QUOTE;
+            if (!plain && !escaped)
+                continue;
+            escapeDepth = escaped ? 1 : 0;
+        }
+        else if (dataUrl >= 2 && line[dataUrl - 2] === BACKSLASH && line[dataUrl - 1] === QUOTE) {
+            escapeDepth = 1;
+        }
+        const digest = digestPdfRun(line, base64Start, end);
+        if (!digest)
+            continue;
+        found.push({ replaceStart: useUrl ? dataUrl : base64Start, replaceEnd: end, base64Start, base64End: end, escapeDepth, ...digest });
+    }
+    return found;
+}
+/** The next index at or after `from` where the PDF start sits right after a `"`, or -1. */
+function nextQuotedStart(line, from) {
+    let at = line.indexOf(START, from);
+    while (at !== -1 && !(at > 0 && line[at - 1] === QUOTE))
+        at = line.indexOf(START, at + 1);
+    return at;
+}

package/dist/pdf-conversion-cache.js

@@ -0,0 +1,91 @@
+/**
+ * What a PDF became, kept on disk by its sha256 so a transcript that is rebuilt every tick does not re-read
+ * the same PDF every tick (BLI-23347).
+ *
+ * One small JSON file per distinct PDF under `<state dir>/pdf-conversions/`: the converted text, or for a
+ * scan the page list (page number, sha256 and size of each page image). Never the PDF, never a page image,
+ * never a path: the text is what the transcript carries anyway. A file written by other rules (a different
+ * `PDF_RULES_VERSION`) or damaged is treated as absent, with the reason logged. At most `MAX_ENTRIES` files
+ * stay; the oldest go first.
+ */
+import { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { PDF_RULES_VERSION } from "@bli-cockpit/telemetry-core";
+const TAG = "[pdf-cache]";
+const DIRECTORY = "pdf-conversions";
+const MAX_ENTRIES = 300;
+const SHA = /^[0-9a-f]{64}$/;
+function fileOf(stateDir, sha256) {
+    return path.join(stateDir, DIRECTORY, `${sha256}.json`);
+}
+function valid(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    if (typeof record["pages"] !== "number" || !Array.isArray(record["notes"]) || !record["notes"].every((note) => typeof note === "string"))
+        return false;
+    if (record["kind"] === "text")
+        return typeof record["body"] === "string";
+    if (record["kind"] !== "scanned" || !Array.isArray(record["pageImages"]))
+        return false;
+    return record["pageImages"].every((entry) => typeof entry === "object" && entry !== null
+        && typeof entry["page"] === "number"
+        && typeof entry["sha256"] === "string" && SHA.test(entry["sha256"])
+        && typeof entry["byteSize"] === "number");
+}
+export async function readCachedPdf(stateDir, sha256) {
+    let raw;
+    try {
+        raw = await readFile(fileOf(stateDir, sha256), "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            console.error(TAG + " entry unreadable, converting again", JSON.stringify({ reason: "cache_read_failed", error_name: error instanceof Error ? error.name : typeof error }));
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.rules !== PDF_RULES_VERSION) {
+            console.error(TAG + " entry made by other rules, converting again", JSON.stringify({ reason: "cache_rules_changed" }));
+            return null;
+        }
+        if (valid(parsed.entry))
+            return parsed.entry;
+    }
+    catch {
+        // Falls through to the damaged-entry log below.
+    }
+    console.error(TAG + " entry damaged, converting again", JSON.stringify({ reason: "cache_entry_invalid", byte_size: raw.length }));
+    return null;
+}
+export async function writeCachedPdf(stateDir, sha256, entry) {
+    const directory = path.join(stateDir, DIRECTORY);
+    const target = fileOf(stateDir, sha256);
+    const partial = `${target}.${process.pid}.partial`;
+    try {
+        await mkdir(directory, { recursive: true });
+        await writeFile(partial, JSON.stringify({ rules: PDF_RULES_VERSION, entry }), "utf8");
+        await rename(partial, target);
+    }
+    catch (error) {
+        await unlink(partial).catch(() => undefined);
+        console.error(TAG + " entry not saved, it will be converted again next time", JSON.stringify({ reason: "cache_write_failed", error_name: error instanceof Error ? error.name : typeof error }));
+        return;
+    }
+    await prune(directory);
+}
+async function prune(directory) {
+    try {
+        const names = (await readdir(directory)).filter((name) => name.endsWith(".json"));
+        if (names.length <= MAX_ENTRIES)
+            return;
+        const aged = await Promise.all(names.map(async (name) => ({ name, mtime: (await stat(path.join(directory, name)).catch(() => null))?.mtimeMs ?? 0 })));
+        aged.sort((a, b) => a.mtime - b.mtime);
+        const drop = aged.slice(0, names.length - MAX_ENTRIES + 50);
+        await Promise.all(drop.map(({ name }) => unlink(path.join(directory, name)).catch(() => undefined)));
+        console.error(TAG + " oldest entries removed", JSON.stringify({ reason: "cache_over_limit", removed: drop.length, kept: names.length - drop.length }));
+    }
+    catch (error) {
+        console.error(TAG + " prune failed", JSON.stringify({ reason: "cache_prune_failed", error_name: error instanceof Error ? error.name : typeof error }));
+    }
+}

package/dist/pdf-convert.js

@@ -0,0 +1,152 @@
+/**
+ * One PDF's bytes to what the transcript keeps (BLI-23347): its text with tables kept, or, for a scan with no
+ * text layer, the PNG of each page's image so the existing image describe door can read it.
+ *
+ * pdf.js comes from `unpdf`, which ships it as one self-contained module: no native dependency, no canvas, so
+ * macOS and Windows behave the same. A scan is not RENDERED (that needs a canvas); each page's largest embedded
+ * image is decoded by pdf.js's own decoders and re-encoded by `pdf-page-image.ts`. A page drawn as vector shapes
+ * with no text and no image has nothing to extract and is named as such.
+ *
+ * Bounded: the document is held once (the caller's bytes), one page's raster at a time, at most
+ * `MAX_TEXT_PAGES` pages of text, `MAX_TEXT_CHARS` of it, `MAX_IMAGE_PAGES` page images, and a wall-clock
+ * budget per document. Hitting a bound is said in `notes`, never silent. Never throws: a document that cannot
+ * be read comes back as `failed` with a reason label.
+ *
+ * CHANGING WHAT THIS PRODUCES (limits, the text/scan rule, pdf-layout.ts heuristics) MUST BUMP
+ * `PDF_RULES_VERSION` in telemetry-core so every collector rebuilds the transcripts it converted.
+ */
+import { IMAGE_DESCRIBE_MAX_BYTES } from "@bli-cockpit/telemetry-core";
+import { layoutPage } from "./pdf-layout.js";
+import { rasterToPagePng } from "./pdf-page-image.js";
+export const MAX_TEXT_PAGES = 300;
+export const MAX_TEXT_CHARS = 400_000;
+export const MAX_IMAGE_PAGES = 8;
+export const MAX_CONVERT_MS = 25_000;
+/** A document whose first pages hold fewer characters per page than this has no usable text layer. */
+const MIN_CHARS_PER_PAGE = 30;
+/** Pages sampled to decide text or scan. */
+const SAMPLE_PAGES = 10;
+let loading;
+/** pdf.js through unpdf, loaded once per process; null (and a logged reason) when the package is missing. */
+async function loadPdfJs() {
+    loading ??= import("unpdf")
+        .then(async (unpdf) => (await unpdf.getResolvedPDFJS()))
+        .catch((error) => {
+        console.error("[pdf-convert] extractor unavailable", JSON.stringify({ reason: "extractor_unavailable", error_name: error instanceof Error ? error.name : typeof error }));
+        return null;
+    });
+    return loading;
+}
+function textItemsOf(content) {
+    const items = [];
+    for (const item of content.items) {
+        if (typeof item.str !== "string" || !item.transform)
+            continue;
+        items.push({ str: item.str, x: item.transform[4], y: item.transform[5], width: item.width ?? 0, size: Math.abs(item.transform[3]) || item.height || 10 });
+    }
+    return items;
+}
+/** Control characters other than tab and newline mean nothing to a reader and break line-oriented tools. */
+function clean(text) {
+    return text.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
+}
+function failure(error, pages) {
+    const name = error instanceof Error ? error.name : typeof error;
+    const reason = name === "PasswordException" ? "password_protected" : name === "InvalidPDFException" || name === "FormatError" ? "not_a_readable_pdf" : "extract_error";
+    return { kind: "failed", reason, pages };
+}
+async function pageRaster(pdfjs, page) {
+    const list = await page.getOperatorList();
+    let best = null;
+    for (let index = 0; index < list.fnArray.length; index += 1) {
+        const op = list.fnArray[index];
+        if (op !== pdfjs.OPS.paintImageXObject && op !== pdfjs.OPS.paintInlineImageXObject)
+            continue;
+        const arg = list.argsArray[index]?.[0];
+        let image = arg;
+        if (typeof arg === "string") {
+            image = page.objs.has(arg) ? page.objs.get(arg) : await new Promise((resolve) => { page.objs.get(arg, resolve); });
+        }
+        const candidate = image;
+        if (!candidate?.data || !candidate.width || !candidate.height || (candidate.kind !== 1 && candidate.kind !== 2 && candidate.kind !== 3))
+            continue;
+        if (!best || candidate.width * candidate.height > best.width * best.height)
+            best = candidate;
+    }
+    return best;
+}
+export async function convertPdf(bytes, now = Date.now) {
+    const started = now();
+    const pdfjs = await loadPdfJs();
+    if (!pdfjs)
+        return { kind: "failed", reason: "extractor_unavailable", pages: null };
+    const task = pdfjs.getDocument({ data: bytes, isEvalSupported: false, disableFontFace: true, useSystemFonts: false, verbosity: 0 });
+    let doc;
+    try {
+        doc = await task.promise;
+        const pages = doc.numPages;
+        // Text first: the first pages decide text or scan, and a text document goes on page by page.
+        const rendered = [];
+        const notes = [];
+        let chars = 0;
+        let sampledChars = 0;
+        let shown = 0;
+        for (let number = 1; number <= Math.min(pages, MAX_TEXT_PAGES); number += 1) {
+            if (now() - started > MAX_CONVERT_MS) {
+                notes.push(`stopped after ${MAX_CONVERT_MS / 1000} s`);
+                break;
+            }
+            const page = await doc.getPage(number);
+            const text = clean(layoutPage(textItemsOf(await page.getTextContent())));
+            page.cleanup();
+            if (number <= SAMPLE_PAGES)
+                sampledChars += text.replace(/\s/g, "").length;
+            if (number === Math.min(pages, SAMPLE_PAGES) && sampledChars < MIN_CHARS_PER_PAGE * number)
+                return await scannedPages(pdfjs, doc, pages, started, now);
+            if (chars + text.length > MAX_TEXT_CHARS) {
+                notes.push(`text cut at ${MAX_TEXT_CHARS} characters`);
+                break;
+            }
+            chars += text.length;
+            rendered.push(text === "" ? `[page ${number}: no text]` : `[page ${number}]\n${text}`);
+            shown = number;
+        }
+        // Nothing read (the time budget was gone before page one): never a text block of nothing in place of a document.
+        if (shown === 0)
+            return { kind: "failed", reason: "time_budget_spent_before_first_page", pages };
+        if (shown < pages)
+            notes.push(`pages 1-${shown} of ${pages} shown`);
+        return { kind: "text", pages, body: rendered.join("\n\n"), notes };
+    }
+    catch (error) {
+        return failure(error, doc?.numPages ?? null);
+    }
+    finally {
+        await task.destroy().catch(() => undefined);
+    }
+}
+async function scannedPages(pdfjs, doc, pages, started, now) {
+    const pageImages = [];
+    const notes = ["no text layer"];
+    const missing = [];
+    const limit = Math.min(pages, MAX_IMAGE_PAGES);
+    for (let number = 1; number <= limit; number += 1) {
+        if (now() - started > MAX_CONVERT_MS) {
+            notes.push(`stopped after ${MAX_CONVERT_MS / 1000} s`);
+            break;
+        }
+        const page = await doc.getPage(number);
+        const raster = await pageRaster(pdfjs, page);
+        page.cleanup();
+        const png = raster ? rasterToPagePng(raster, IMAGE_DESCRIBE_MAX_BYTES - 100_000) : null;
+        if (png)
+            pageImages.push({ page: number, png });
+        else
+            missing.push(number);
+    }
+    if (missing.length > 0)
+        notes.push(`no page image on ${missing.length === 1 ? "page" : "pages"} ${missing.join(", ")}`);
+    if (pages > limit)
+        notes.push(`pages 1-${limit} of ${pages} described`);
+    return { kind: "scanned", pages, pageImages, notes };
+}