@hraness/wordcell 0.26.3 → 0.27.0

package/src/pdf/bundle-reader.ts

@@ -0,0 +1,457 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants, type BigIntStats } from "node:fs";
+import { lstat, open, opendir, realpath, type FileHandle } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { PdfCaptureError } from "./errors.js";
+import { parsePdfImageInterpretations } from "./layout.js";
+
+// The same no-follow/inode fencing used by the article reader, specialized for PDF.
+function boundedInteger(value: number | undefined, fallback: number, maximum: number, label: string): number {
+  const selected = value ?? fallback;
+  if (!Number.isSafeInteger(selected) || selected < 1 || selected > maximum) {
+    throw new PdfCaptureError("invalid-input", `${label} must be an integer from 1 through ${maximum}`);
+  }
+  return selected;
+}
+
+function confinedRelativePath(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > 4_096 || value.includes("\0")) {
+    throw new PdfCaptureError("integrity", `${label} must be a bounded non-empty path`);
+  }
+  if (isAbsolute(value) || value.includes("\\")) throw new PdfCaptureError("integrity", `${label} must be a relative POSIX path`);
+  const segments = value.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new PdfCaptureError("integrity", `${label} contains an unsafe segment`);
+  }
+  return value;
+}
+
+type SafeBundleRoot = {
+  readonly path: string;
+  readonly handle: FileHandle;
+  readonly device: bigint;
+  readonly inode: bigint;
+};
+
+class MissingCaptureAssetError extends PdfCaptureError {
+  constructor(message: string) { super("integrity", message); }
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+function assertAssetVerificationDeadline(deadline: number | undefined): void {
+  if (deadline !== undefined && performance.now() >= deadline) {
+    throw new PdfCaptureError("timeout", "capture asset verification exceeded its time budget");
+  }
+}
+
+function confined(root: SafeBundleRoot, relativePath: string, label: string): string {
+  const path = resolve(root.path, relativePath);
+  const lexical = relative(root.path, path);
+  if (lexical === "" || lexical === ".." || lexical.startsWith(`..${sep}`) || isAbsolute(lexical)) {
+    throw new PdfCaptureError("integrity", `${label} escapes the capture bundle`);
+  }
+  return path;
+}
+
+async function safeDirectory(pathInput: string): Promise<SafeBundleRoot> {
+  if (pathInput.trim() === "") throw new PdfCaptureError("integrity", "capture bundle path is required");
+  const path = resolve(pathInput);
+  const canonical = await realpath(path);
+  if (canonical !== path) throw new PdfCaptureError("integrity", "capture bundle path must be canonical and cannot traverse a symbolic link");
+  const stats = await lstat(path, { bigint: true });
+  if (!stats.isDirectory() || stats.isSymbolicLink()) throw new PdfCaptureError("integrity", "capture bundle path must be a real directory");
+  if (dirname(path) === path) throw new PdfCaptureError("integrity", "refusing a filesystem root as a capture bundle");
+  const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  try {
+    const opened = await handle.stat({ bigint: true });
+    if (!opened.isDirectory() || opened.dev !== stats.dev || opened.ino !== stats.ino) {
+      throw new PdfCaptureError("integrity", "capture bundle root changed while it was opened");
+    }
+    return { path, handle, device: opened.dev, inode: opened.ino };
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
+}
+
+async function assertBundleRoot(root: SafeBundleRoot, deadline?: number): Promise<void> {
+  assertAssetVerificationDeadline(deadline);
+  const [opened, named, canonical] = await Promise.all([
+    root.handle.stat({ bigint: true }),
+    lstat(root.path, { bigint: true }),
+    realpath(root.path),
+  ]);
+  assertAssetVerificationDeadline(deadline);
+  if (
+    canonical !== root.path
+    || !opened.isDirectory()
+    || !named.isDirectory()
+    || named.isSymbolicLink()
+    || opened.dev !== root.device
+    || opened.ino !== root.inode
+    || named.dev !== root.device
+    || named.ino !== root.inode
+  ) throw new PdfCaptureError("integrity", "capture bundle root changed during inspection");
+}
+
+async function assertAncestorChain(
+  root: SafeBundleRoot,
+  relativePath: string,
+  label: string,
+  deadline?: number,
+): Promise<void> {
+  await assertBundleRoot(root, deadline);
+  const segments = confinedRelativePath(relativePath, label).split("/");
+  let current = root.path;
+  for (const segment of segments.slice(0, -1)) {
+    current = resolve(current, segment);
+    assertAssetVerificationDeadline(deadline);
+    const metadata = await lstat(current, { bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+      throw new PdfCaptureError("integrity", `${label} must not traverse a linked or non-directory ancestor`);
+    }
+    const canonical = await realpath(current);
+    assertAssetVerificationDeadline(deadline);
+    if (canonical !== current) {
+      throw new PdfCaptureError("integrity", `${label} must not traverse a filesystem alias`);
+    }
+  }
+  await assertBundleRoot(root, deadline);
+}
+
+async function withRegularFile<T>(
+  root: SafeBundleRoot,
+  relativePath: string,
+  maximumBytes: number,
+  label: string,
+  read: (handle: FileHandle, size: number) => Promise<T>,
+  deadline?: number,
+  missingError?: Error,
+): Promise<T> {
+  await assertAncestorChain(root, relativePath, label, deadline);
+  const path = confined(root, relativePath, label);
+  assertAssetVerificationDeadline(deadline);
+  let before: BigIntStats;
+  try {
+    before = await lstat(path, { bigint: true });
+  } catch (error) {
+    assertAssetVerificationDeadline(deadline);
+    if (missingError !== undefined && isMissingPathError(error)) throw missingError;
+    throw error;
+  }
+  assertAssetVerificationDeadline(deadline);
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n) {
+    throw new PdfCaptureError("integrity", `${label} must be a regular single-link file`);
+  }
+  if (before.size > BigInt(maximumBytes)) throw new PdfCaptureError("integrity", `${label} exceeds ${maximumBytes} bytes`);
+  const canonical = await realpath(path);
+  assertAssetVerificationDeadline(deadline);
+  if (canonical !== path) throw new PdfCaptureError("integrity", `${label} must not traverse a filesystem alias`);
+  const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  try {
+    assertAssetVerificationDeadline(deadline);
+    const opened = await handle.stat({ bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    if (
+      !opened.isFile()
+      || opened.nlink !== 1n
+      || opened.dev !== before.dev
+      || opened.ino !== before.ino
+      || opened.size !== before.size
+    ) throw new PdfCaptureError("integrity", `${label} changed while it was opened`);
+    await assertAncestorChain(root, relativePath, label, deadline);
+    const result = await read(handle, Number(opened.size));
+    assertAssetVerificationDeadline(deadline);
+    const after = await handle.stat({ bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    const named = await lstat(path, { bigint: true });
+    assertAssetVerificationDeadline(deadline);
+    await assertAncestorChain(root, relativePath, label, deadline);
+    const finalCanonical = await realpath(path);
+    assertAssetVerificationDeadline(deadline);
+    if (
+      after.dev !== before.dev
+      || after.ino !== before.ino
+      || after.size !== before.size
+      || after.mtimeNs !== before.mtimeNs
+      || after.nlink !== 1n
+      || named.dev !== before.dev
+      || named.ino !== before.ino
+      || named.size !== before.size
+      || named.mtimeNs !== before.mtimeNs
+      || named.nlink !== 1n
+      || named.isSymbolicLink()
+      || finalCanonical !== path
+    ) throw new PdfCaptureError("integrity", `${label} changed while it was read`);
+    return result;
+  } finally {
+    await handle.close();
+    assertAssetVerificationDeadline(deadline);
+  }
+}
+
+async function readRegularFile(
+  root: SafeBundleRoot,
+  relativePath: string,
+  maximumBytes: number,
+  label: string,
+  deadline?: number,
+): Promise<Buffer> {
+  return withRegularFile(root, relativePath, maximumBytes, label, async (handle, size) => {
+    const bytes = Buffer.alloc(size);
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+      assertAssetVerificationDeadline(deadline);
+      const result = await handle.read(bytes, offset, bytes.byteLength - offset, offset);
+      if (result.bytesRead === 0) throw new PdfCaptureError("integrity", `${label} changed while it was read`);
+      offset += result.bytesRead;
+    }
+    return bytes;
+  }, deadline);
+}
+
+async function hashRegularFile(
+  root: SafeBundleRoot,
+  relativePath: string,
+  maximumBytes: number,
+  deadline: number,
+  label: string,
+): Promise<{ readonly bytes: number; readonly sha256: string }> {
+  assertAssetVerificationDeadline(deadline);
+  await assertBundleRoot(root, deadline);
+  assertAssetVerificationDeadline(deadline);
+  await assertAncestorChain(root, relativePath, label, deadline);
+  const path = confined(root, relativePath, label);
+  assertAssetVerificationDeadline(deadline);
+  try {
+    await lstat(path, { bigint: true });
+  } catch (error) {
+    assertAssetVerificationDeadline(deadline);
+    if (isMissingPathError(error)) {
+      await assertBundleRoot(root, deadline);
+      throw new MissingCaptureAssetError(`capture asset ${relativePath} is missing`);
+    }
+    throw error;
+  }
+  assertAssetVerificationDeadline(deadline);
+  return withRegularFile(root, relativePath, maximumBytes, label, async (handle, size) => {
+    assertAssetVerificationDeadline(deadline);
+    const hash = createHash("sha256");
+    const chunk = Buffer.allocUnsafe(Math.min(1 * 1_024 * 1_024, Math.max(1, size)));
+    let offset = 0;
+    while (offset < size) {
+      assertAssetVerificationDeadline(deadline);
+      const result = await handle.read(chunk, 0, Math.min(chunk.byteLength, size - offset), offset);
+      assertAssetVerificationDeadline(deadline);
+      if (result.bytesRead === 0) throw new PdfCaptureError("integrity", `${label} changed while it was read`);
+      hash.update(chunk.subarray(0, result.bytesRead));
+      offset += result.bytesRead;
+    }
+    assertAssetVerificationDeadline(deadline);
+    return { bytes: size, sha256: hash.digest("hex") };
+  }, deadline, new MissingCaptureAssetError(`capture asset ${relativePath} is missing`));
+}
+
+function digest(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+
+type RecordValue = Readonly<Record<string, unknown>>;
+type Descriptor = { readonly path: string; readonly bytes: number; readonly sha256: string };
+export type PdfBundleIntegrity = "verified" | "mismatch" | "unavailable";
+export type PdfBundleFile = Descriptor & { readonly integrity: PdfBundleIntegrity };
+export type PdfBundleInspection = {
+  readonly root: string;
+  readonly schemaVersion: 1;
+  readonly status: "complete" | "partial";
+  readonly pageCount: number;
+  readonly processedPages: number;
+  readonly markdown: PdfBundleFile & { readonly markdown: string };
+  readonly source: PdfBundleFile;
+  readonly assets: readonly PdfBundleFile[];
+  readonly annotations: PdfBundleFile | null;
+};
+export type ReadPdfCaptureBundleOptions = {
+  readonly maxDocumentBytes?: number;
+  readonly maxSourceBytes?: number;
+  readonly maxAssetBytes?: number;
+  readonly maxTotalAssetBytes?: number;
+  readonly maxVerifiedAssets?: number;
+  readonly maxVerificationMs?: number;
+};
+export type PdfBundleVerification = {
+  readonly ok: boolean;
+  readonly inspection: PdfBundleInspection;
+  readonly issues: readonly { readonly kind: "document-integrity" | "source-integrity" | "asset-integrity" | "annotation-integrity"; readonly path: string; readonly integrity: PdfBundleIntegrity }[];
+};
+function invalid(message: string): never { throw new PdfCaptureError("invalid-input", message); }
+function object(value: unknown): RecordValue {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) invalid("PDF bundle requires an object");
+  return value as RecordValue;
+}
+function integer(value: unknown, maximum: number, minimum = 0): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) invalid("PDF bundle has an invalid count or page reference");
+  return value;
+}
+function descriptor(value: unknown): Descriptor {
+  const entry = object(value);
+  if (typeof entry.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(entry.sha256)) invalid("PDF bundle has an invalid digest");
+  return { path: confinedRelativePath(entry.path, "PDF artifact"), bytes: integer(entry.bytes, 8 * 1024 ** 3), sha256: entry.sha256 };
+}
+function decode(bytes: Buffer): string {
+  try { return new TextDecoder("utf-8", { fatal: true }).decode(bytes); }
+  catch { return invalid("PDF bundle text is not UTF-8"); }
+}
+function parse(bytes: Buffer): unknown {
+  try { return JSON.parse(decode(bytes)) as unknown; }
+  catch (error) { if (error instanceof PdfCaptureError) throw error; return invalid("PDF bundle JSON is invalid"); }
+}
+
+/** Inspect retained source and assets without following aliases or trusting manifest paths. */
+export async function inspectPdfCaptureBundle(path: string, options: ReadPdfCaptureBundleOptions = {}): Promise<PdfBundleInspection> {
+  const maxDocument = boundedInteger(options.maxDocumentBytes, 64 * 1024 ** 2, 256 * 1024 ** 2, "maxDocumentBytes");
+  const maxSource = boundedInteger(options.maxSourceBytes, 512 * 1024 ** 2, 8 * 1024 ** 3, "maxSourceBytes");
+  const maxAsset = boundedInteger(options.maxAssetBytes, 100 * 1024 ** 2, 8 * 1024 ** 3, "maxAssetBytes");
+  const maxTotal = boundedInteger(options.maxTotalAssetBytes, 500 * 1024 ** 2, 8 * 1024 ** 3, "maxTotalAssetBytes");
+  const maxAssets = boundedInteger(options.maxVerifiedAssets, 1000, 10_000, "maxVerifiedAssets");
+  const deadline = performance.now() + boundedInteger(options.maxVerificationMs, 30_000, 300_000, "maxVerificationMs");
+  const root = await safeDirectory(path);
+  try {
+    const manifest = object(parse(await readRegularFile(root, "capture.json", 4 * 1024 ** 2, "PDF manifest", deadline)));
+    if (manifest.schemaVersion !== 1) throw new PdfCaptureError("unsupported-schema", "Unsupported PDF manifest schema");
+    if (manifest.kind !== "pdf" || (manifest.status !== "complete" && manifest.status !== "partial")) invalid("Invalid PDF manifest kind or status");
+    const document = object(manifest.document);
+    const pageCount = integer(document.pageCount, 100_000, 1);
+    const processedPages = integer(document.processedPages, pageCount, 1);
+    if (processedPages < pageCount && manifest.status !== "partial") invalid("Truncated PDF cannot claim complete");
+    if (manifest.quality !== undefined) {
+      const quality = object(manifest.quality);
+      if (quality.schemaVersion !== 1) throw new PdfCaptureError("unsupported-schema", "Unsupported PDF quality schema");
+      if (!Array.isArray(quality.issues) || quality.issues.length > 100_000) invalid("Invalid PDF quality issues");
+      for (const raw of quality.issues as unknown[]) {
+        const issue = object(raw);
+        if (!["reading-order-uncertain", "table-structure-uncertain", "math-structure-uncertain", "ocr-needed"].includes(String(issue.code))) invalid("Unknown PDF quality issue");
+        integer(issue.page, processedPages, 1);
+      }
+      if (quality.issues.length > 0 && manifest.status !== "partial") invalid("Uncertain PDF cannot claim complete");
+    }
+    const sourceDescriptor = descriptor(manifest.source);
+    if (sourceDescriptor.path !== "source.pdf" || object(manifest.source).mimeType !== "application/pdf") invalid("Invalid retained PDF source");
+    const check = async (expected: Descriptor, maximum: number): Promise<PdfBundleFile> => {
+      if (expected.bytes > maximum) throw new PdfCaptureError("limit-exceeded", "PDF artifact exceeds verification byte limit");
+      const actual = await hashRegularFile(root, expected.path, maximum, deadline, "PDF artifact");
+      return { ...actual, path: expected.path, integrity: actual.bytes === expected.bytes && actual.sha256 === expected.sha256 ? "verified" : "mismatch" };
+    };
+    const source = await check(sourceDescriptor, maxSource);
+    let expectedMarkdown: Descriptor | null = null;
+    let markdownPath: string;
+    if (manifest.markdown !== undefined) {
+      expectedMarkdown = descriptor(manifest.markdown);
+      markdownPath = expectedMarkdown.path;
+      if (markdownPath.includes("/") || !markdownPath.endsWith(".md")) invalid("Invalid PDF Markdown path");
+    } else {
+      // Legacy bundles retain their readable Markdown, but its digest is not attested.
+      const directory = await opendir(root.path);
+      const candidates: string[] = [];
+      let entries = 0;
+      try {
+        for await (const entry of directory) {
+          assertAssetVerificationDeadline(deadline);
+          if (++entries > 1000) throw new PdfCaptureError("limit-exceeded", "Legacy PDF directory exceeds entry limit");
+          if (entry.name.endsWith(".md")) candidates.push(entry.name);
+        }
+      } finally { try { await directory.close(); } catch { /* Iteration closes the directory. */ } }
+      if (candidates.length !== 1) invalid("Legacy PDF bundle must contain exactly one Markdown document");
+      markdownPath = candidates[0]!;
+    }
+    const markdownBytes = await readRegularFile(root, markdownPath, maxDocument, "PDF Markdown", deadline);
+    const markdownText = decode(markdownBytes);
+    const markdownDigest = digest(markdownBytes);
+    const markdown: PdfBundleInspection["markdown"] = {
+      path: markdownPath, bytes: markdownBytes.length, sha256: markdownDigest, markdown: markdownText,
+      integrity: expectedMarkdown === null ? "unavailable" : expectedMarkdown.bytes === markdownBytes.length && expectedMarkdown.sha256 === markdownDigest ? "verified" : "mismatch",
+    };
+    const assetReferences = new Map<string, Set<number>>();
+    let currentPage = 0;
+    for (const match of markdownText.matchAll(/<!-- pdf-page: (\d+) -->|!\[[^\]\n]*\]\((assets\/[^)\r\n]+)\)/gu)) {
+      if (match[1] !== undefined) currentPage = integer(Number(match[1]), processedPages, 1);
+      else if (match[2] !== undefined) {
+        const pages = assetReferences.get(match[2]) ?? new Set<number>(); pages.add(currentPage); assetReferences.set(match[2], pages);
+      }
+    }
+    const anchors = new Set<number>();
+    let anchorCount = 0;
+    for (const match of markdownText.matchAll(/<!-- pdf-page: (\d+) -->/gu)) {
+      if (++anchorCount > 100_000) invalid("Too many PDF page anchors");
+      anchors.add(integer(Number(match[1]), processedPages, 1));
+    }
+    if (!Array.isArray(manifest.images) || manifest.images.length > maxAssets) invalid("Invalid PDF image count");
+    const imageIds = new Map<string, string>();
+    const assetsByPath = new Map<string, PdfBundleFile>();
+    const declaredPages = new Map<string, Set<number>>();
+    let totalBytes = 0;
+    for (const raw of manifest.images as unknown[]) {
+      const image = object(raw);
+      if (typeof image.id !== "string" || !/^[a-z0-9][a-z0-9._:-]{0,255}$/u.test(image.id) || imageIds.has(image.id)) invalid("Invalid or duplicate PDF image ID");
+      const page = integer(image.page, processedPages, 1);
+      if (!anchors.has(page)) invalid("PDF image has no corresponding Markdown page anchor");
+      const asset = descriptor(image.asset);
+      if (!/^assets\/[^/]+$/u.test(asset.path)) invalid("PDF image must be a direct assets child");
+      if (!assetReferences.get(asset.path)?.has(page)) invalid("PDF image has no corresponding Markdown asset reference");
+      imageIds.set(image.id, asset.sha256);
+      const pages = declaredPages.get(asset.path) ?? new Set<number>();
+      pages.add(page); declaredPages.set(asset.path, pages);
+      const existing = assetsByPath.get(asset.path);
+      if (existing !== undefined) {
+        if (existing.bytes !== asset.bytes || existing.sha256 !== asset.sha256) invalid("Conflicting PDF asset descriptors");
+      } else {
+        totalBytes += asset.bytes;
+        if (totalBytes > maxTotal) throw new PdfCaptureError("limit-exceeded", "PDF assets exceed total byte limit");
+        const checked = await check(asset, Math.min(maxAsset, maxTotal - (totalBytes - asset.bytes)));
+        totalBytes += checked.bytes - asset.bytes;
+        assetsByPath.set(asset.path, checked);
+      }
+    }
+    for (const [path, pages] of assetReferences) {
+      if (!assetsByPath.has(path)) invalid("Markdown references an undeclared PDF asset");
+      if ([...pages].some(page => !declaredPages.get(path)?.has(page))) invalid("Markdown asset page disagrees with PDF manifest");
+    }
+    const extraction = object(manifest.extraction);
+    if (integer(extraction.imageCount, maxAssets) !== imageIds.size) invalid("PDF image count disagrees with manifest");
+    let annotations: PdfBundleFile | null = null;
+    if (manifest.annotations !== null) {
+      const annotationDescriptor = descriptor(manifest.annotations);
+      if (annotationDescriptor.path !== "annotations.json") invalid("Invalid PDF annotations path");
+      const annotationBytes = await readRegularFile(root, "annotations.json", 16 * 1024 ** 2, "PDF annotations", deadline);
+      const annotationHash = digest(annotationBytes);
+      annotations = { path: annotationDescriptor.path, bytes: annotationBytes.length, sha256: annotationHash, integrity: annotationDescriptor.bytes === annotationBytes.length && annotationDescriptor.sha256 === annotationHash ? "verified" : "mismatch" };
+      let retained: ReturnType<typeof parsePdfImageInterpretations>;
+      try { retained = parsePdfImageInterpretations(parse(annotationBytes)); }
+      catch (error) { if (error instanceof PdfCaptureError) throw error; throw new PdfCaptureError("invalid-input", "Invalid PDF image annotations", { cause: error }); }
+      if (retained.length !== integer(object(manifest.annotations).count, 10_000)) invalid("PDF annotation count disagrees with manifest");
+      for (const annotation of retained) {
+        if (imageIds.get(annotation.id) !== annotation.sha256) invalid("PDF annotation references an unknown image or digest");
+      }
+    }
+    await assertBundleRoot(root, deadline);
+    return { root: root.path, schemaVersion: 1, status: manifest.status, pageCount, processedPages, markdown, source, assets: [...assetsByPath.values()], annotations };
+  } finally { await root.handle.close(); }
+}
+
+/** Missing legacy Markdown provenance is explicit and never counted as verified. */
+export async function verifyPdfCaptureBundle(path: string, options: ReadPdfCaptureBundleOptions = {}): Promise<PdfBundleVerification> {
+  const inspection = await inspectPdfCaptureBundle(path, options);
+  const issues: Array<PdfBundleVerification["issues"][number]> = [];
+  const add = (file: PdfBundleFile, kind: PdfBundleVerification["issues"][number]["kind"]): void => {
+    if (file.integrity !== "verified") issues.push({ kind, path: file.path, integrity: file.integrity });
+  };
+  add(inspection.markdown, "document-integrity"); add(inspection.source, "source-integrity");
+  for (const asset of inspection.assets) add(asset, "asset-integrity");
+  if (inspection.annotations !== null) add(inspection.annotations, "annotation-integrity");
+  return { ok: issues.length === 0, inspection, issues };
+}

package/src/pdf/capture.ts

@@ -8,7 +8,7 @@ import { slugify } from "../clip/lib.js";
 import { sanitizeTerminalText } from "../clip/terminal.js";
 import { inspectPdf } from "./extract.js";
 import {
-  layoutBlocks,
+  analyzePdfLayout,
   parsePdfImageInterpretations,
 } from "./layout.js";
 import {
@@ -183,6 +183,8 @@ export async function runPdfCapture(
       });
     }
     const platforms = embeddedPlatforms(resolvedImages);
+    const layout = analyzePdfLayout(inspection.pages);
+    for (const issue of layout.issues) warnings.push(`Page ${issue.page}: ${issue.code}; consult the retained source PDF.`);
     const status = warnings.length > 0 || unclassifiedImages > 0 || ocrWarningCount > 0
       ? "partial"
       : "complete";
@@ -190,7 +192,7 @@ export async function runPdfCapture(
     const requestedSlug = options.slug ?? inspection.metadata.title ?? filenameTitle;
     const slug = slugify(sanitizeTerminalText(requestedSlug));
     if (slug === "") throw new Error("could not derive a safe PDF capture slug; pass an explicit slug");
-    const blocks = layoutBlocks(inspection.pages);
+    const blocks = layout.blocks;
     const byId = new Map(resolvedImages.map((image) => [image.image.id, image]));
     const capturedAt = (dependencies.now ?? (() => new Date()))().toISOString();
     const built = buildPdfMarkdown({
@@ -233,6 +235,8 @@ export async function runPdfCapture(
     const manifest: PdfCaptureManifest = {
       schemaVersion: PDF_CAPTURE_MANIFEST_SCHEMA_VERSION,
       kind: "pdf",
+      quality: { schemaVersion: 1, issues: layout.issues },
+      markdown: { path: pdfMarkdownFilename(slug), bytes: Buffer.byteLength(built.markdown), sha256: createHash("sha256").update(built.markdown).digest("hex") },
       capturedAt,
       status,
       source: {

package/src/pdf/cli.ts

@@ -1,3 +1,4 @@
+import { PdfCaptureError } from "./errors.js";
 import { lstatSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
@@ -149,7 +150,7 @@ export async function main(
     return 0;
   } catch (error) {
     const message = safe(error instanceof Error ? error.message : String(error));
-    if (arguments_.json) output.stdout(terminalSafeJson({ ok: false, error: message }));
+    if (arguments_.json) output.stdout(terminalSafeJson({ ok: false, error: message, code: error instanceof PdfCaptureError ? error.code : "unknown" }));
     else output.stderr(renderFailure(message, "wordcell doctor", stderrStyle(environment, output)));
     return 1;
   } finally {

package/src/pdf/errors.ts

@@ -0,0 +1,11 @@
+export type PdfCaptureErrorCode = "invalid-input" | "encrypted" | "limit-exceeded" | "tool-unavailable" | "extraction-failed" | "timeout" | "cancelled" | "integrity" | "unsupported-schema" | "unknown";
+
+/** Codes describe observed failures; unknown errors are never classified from their prose. */
+export class PdfCaptureError extends Error {
+  readonly code: PdfCaptureErrorCode;
+  constructor(code: PdfCaptureErrorCode, message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.code = code;
+    this.name = "PdfCaptureError";
+  }
+}

package/src/pdf/extract.ts

@@ -1,3 +1,4 @@
+import { PdfCaptureError } from "./errors.js";
 import { createHash } from "node:crypto";
 import {
   chmodSync,
@@ -43,7 +44,7 @@ export const pdfCaptureDefaults = {
 function positiveBound(value: number | undefined, fallback: number, maximum: number, label: string): number {
   const selected = value ?? fallback;
   if (!Number.isSafeInteger(selected) || selected < 1 || selected > maximum) {
-    throw new Error(`${label} must be an integer from 1 through ${maximum}`);
+    throw new PdfCaptureError("invalid-input", `${label} must be an integer from 1 through ${maximum}`);
   }
   return selected;
 }
@@ -61,10 +62,10 @@ function prepareWorkspace(path: string): string {
   if (existsSync(absolute)) {
     const stats = lstatSync(absolute);
     if (!stats.isDirectory() || stats.isSymbolicLink()) {
-      throw new Error("PDF inspection workspace must be a real directory");
+      throw new PdfCaptureError("invalid-input", "PDF inspection workspace must be a real directory");
     }
     if (readdirSync(absolute).length !== 0) {
-      throw new Error("PDF inspection workspace must be empty");
+      throw new PdfCaptureError("invalid-input", "PDF inspection workspace must be empty");
     }
   } else {
     mkdirSync(absolute, { recursive: false, mode: 0o700 });
@@ -81,15 +82,15 @@ function sourceIdentity(path: string, maxPdfBytes: number): {
   const originalFilename = basename(path);
   const canonical = realpathSync(resolve(path));
   const stats = statSync(canonical);
-  if (!stats.isFile()) throw new Error("PDF input must be a regular file");
-  if (stats.size < 5) throw new Error("PDF input is too small to contain a PDF header");
-  if (stats.size > maxPdfBytes) throw new Error(`PDF input exceeds the ${maxPdfBytes}-byte limit`);
+  if (!stats.isFile()) throw new PdfCaptureError("invalid-input", "PDF input must be a regular file");
+  if (stats.size < 5) throw new PdfCaptureError("invalid-input", "PDF input is too small to contain a PDF header");
+  if (stats.size > maxPdfBytes) throw new PdfCaptureError("limit-exceeded", `PDF input exceeds the ${maxPdfBytes}-byte limit`);
   const descriptor = openSync(canonical, "r");
   try {
     const signature = Buffer.alloc(5);
     const count = readSync(descriptor, signature, 0, signature.length, 0);
     if (count !== signature.length || signature.toString("ascii") !== "%PDF-") {
-      throw new Error("PDF input does not have a valid PDF signature");
+      throw new PdfCaptureError("invalid-input", "PDF input does not have a valid PDF signature");
     }
   } finally {
     closeSync(descriptor);
@@ -155,18 +156,18 @@ function safeGeneratedImage(
 function generatedTreeSize(workspace: string, maximumFiles: number, maximumBytes: number): void {
   const entries = readdirSync(workspace, { withFileTypes: true });
   if (entries.length > maximumFiles) {
-    throw new Error(`PDF extraction created more than ${maximumFiles} files`);
+    throw new PdfCaptureError("limit-exceeded", `PDF extraction created more than ${maximumFiles} files`);
   }
   let totalBytes = 0;
   for (const entry of entries) {
     const path = join(workspace, entry.name);
     const stats = lstatSync(path);
     if (!entry.isFile() || stats.isSymbolicLink()) {
-      throw new Error("PDF extraction created an unexpected non-file output");
+      throw new PdfCaptureError("extraction-failed", "PDF extraction created an unexpected non-file output");
     }
     totalBytes += stats.size;
     if (totalBytes > maximumBytes) {
-      throw new Error(`PDF extraction exceeded the ${maximumBytes}-byte workspace limit`);
+      throw new PdfCaptureError("limit-exceeded", `PDF extraction exceeded the ${maximumBytes}-byte workspace limit`);
     }
   }
 }
@@ -208,7 +209,9 @@ export async function inspectPdf(
     cwd: workspaceDirectory,
   });
   if (info.exitCode !== 0) {
-    throw new Error("pdfinfo could not inspect the input PDF");
+    // Poppler runs in the C locale; only its exact password diagnostic establishes encryption.
+    const encrypted = info.stderr.split(/\r?\n/u).some(line => line.trim() === "Command Line Error: Incorrect password");
+    throw new PdfCaptureError(encrypted ? "encrypted" : "extraction-failed", "pdfinfo could not inspect the input PDF");
   }
   const metadata = parsePdfInfo(info.stdout);
   const processedPageLimit = Math.min(metadata.pageCount, maxPages);
@@ -233,7 +236,7 @@ export async function inspectPdf(
     cwd: workspaceDirectory,
   });
   if (extracted.exitCode !== 0) {
-    throw new Error("pdftohtml could not extract the input PDF");
+    throw new PdfCaptureError("extraction-failed", "pdftohtml could not extract the input PDF");
   }
   generatedTreeSize(
     workspaceDirectory,
@@ -245,7 +248,7 @@ export async function inspectPdf(
   );
   const layoutStats = statSync(layoutPath);
   if (!layoutStats.isFile() || layoutStats.size > pdfCaptureDefaults.maxLayoutBytes) {
-    throw new Error(`Poppler layout XML exceeds the ${pdfCaptureDefaults.maxLayoutBytes}-byte limit`);
+    throw new PdfCaptureError("limit-exceeded", `Poppler layout XML exceeds the ${pdfCaptureDefaults.maxLayoutBytes}-byte limit`);
   }
   const parsed = parsePopplerXml(readFileSync(layoutPath, "utf8"), {
     maxPages: processedPageLimit,