@pipeworx/mcp-guam-code 0.1.0 → 0.1.2

package/src/server.ts

@@ -7,9 +7,11 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import pack from './index.js';
+import * as bakedIndexModule from './gu-baked-data.js';
+const bakedIndex = Object.fromEntries(Object.entries(bakedIndexModule));
 
 const server = new Server(
-  { name: '@pipeworx/mcp-guam-code', version: '0.1.0' },
+  { name: '@pipeworx/mcp-guam-code', version: '0.1.2' },
   { capabilities: { tools: {} } },
 );
 
@@ -24,7 +26,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   try {
-    const result = await pack.callTool(name, (args ?? {}) as Record<string, unknown>);
+    const callArgs = { ...((args ?? {}) as Record<string, unknown>) };
+    callArgs._bakedIndex = bakedIndex;
+    const result = await pack.callTool(name, callArgs);
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   } catch (err) {
     return {

package/src/gu-pdf-extract.ts

@@ -1,652 +0,0 @@
-/**
- * PACK-LOCAL FORK of shared/src/pdf-text.ts (fleet #2888), NOT a re-export.
- *
- * Guam's chapter PDFs (col.guamcourts.gov) defeat the shared extractor in a
- * way the shared file does not yet handle, and this pack was built the same
- * week another pack (#2884, New Mexico) was independently editing that
- * shared file — so rather than risk a collision on a file two packs touch at
- * once, the fix lives here, pack-local, with a loud note for whoever next
- * works on the shared extractor to fold it in.
- *
- * THE BUG, AND THE FIX (search "FORK FIX" below for the two call sites):
- * Guam's PDF producer (Neevia Document Converter, driven from Word) writes
- * most runs of text as parenthesized LITERAL strings, e.g. `(abc)Tj` — even
- * for its several embedded TrueType font subsets that declare NO
- * `/Encoding` and use a tiny code space (one font had only 2 defined glyphs)
- * whose codes have no relationship to any standard code page and are only
- * resolvable through that font's own `/ToUnicode` CMap. The shared
- * extractor already has that CMap-lookup machinery (`fontDecoderFor`'s
- * `mapped1` branch, built for North Dakota's similarly-shaped subset fonts)
- * — but it is wired ONLY to the HEX-string (`<...>`) decode path. A literal
- * (parenthesized) string is decoded by `decodeRun` as though its raw bytes
- * were ALREADY the correct windows-1252 text, with no font lookup at all.
- * North Dakota and Kentucky never tripped this because their own non-WinAnsi
- * runs happen to be hex-encoded in their content streams; Guam's producer
- * encodes the SAME font shape as literal strings instead. Confirmed live
- * (9gc016.pdf, Criminal Homicide): unfixed, `§ 16.10` extracts as line-noise
- * control characters; with literal strings routed through the current
- * font's decoder exactly like a hex run, it reads correctly ("As used in
- * this Chapter: (a) Human Being means a person who has been born...").
- *
- * SECOND, SMALLER FIX: one embedded symbol font per chapter PDF
- * (`...+WPTypographicSymbols`, used only for the chapter's curly quote
- * marks) carries a `/ToUnicode` CMap that is ITSELF wrong in the source
- * file — code 1 (meant to be a left double curly quote) maps to U+0041
- * ('A') and code 2 (right curly quote) maps to U+0040 ('@'), confirmed by
- * eye against surrounding text: "ADirector of Public Safety@" is exactly
- * what you get if you substitute back U+201C/U+201D for those two codes —
- * "“Director of Public Safety”" — which is unmistakably the intended
- * reading. This is a defect in Guam's own published PDF (any PDF reader's
- * copy-paste reproduces it too), not something a general-purpose extractor
- * can detect from first principles, so it is special-cased by font name
- * rather than generalized.
- *
- * Everything below this point is otherwise IDENTICAL to
- * shared/src/pdf-text.ts as of this pack's build — same ObjStm/indirect-
- * Length/Type0/mapped1 support, same caveats (no encryption, no OCR, no
- * custom `/Differences` encodings). If you are touching the shared file for
- * another pack, consider porting these two fixes upstream and deleting this
- * fork; nothing about them is Guam-specific except the WPTypographicSymbols
- * font-name match.
- *
- * ORIGINAL HEADER, UNCHANGED, FOR CONTEXT ON EVERYTHING ELSE THIS DOES:
- *
- * Minimal text extractor for simple, text-based PDFs — the kind a
- * mail-merge/print pipeline produces (Word or LibreOffice "export to PDF"),
- * not a scanned image. Built for Kentucky's per-statute PDFs
- * (apps.legislature.ky.gov/law/statutes/statute.aspx?id=...), which ARE
- * exactly that shape: one object tree, FlateDecode content streams, standard
- * TrueType fonts. This is the capability the state-law survey flagged as
- * "the largest single win available" (docs/state-law-probe.md) — several
- * state statute sites serve text ONLY as a per-section PDF, with no HTML
- * fallback, and until now this repo had no way to read one.
- *
- * WHAT THIS DOES NOT DO: parse a general PDF. No encryption, no cross-
- * reference recovery for a damaged file, no image/OCR, no custom
- * `/Differences` glyph encodings, no LZW or RunLength filters, no multi-byte
- * codespaces other than the 2-byte one every sampled font used. Most objects
- * this needs — Catalog, Pages, a leaf Page, its Resources/Font dict, its
- * Contents stream(s), a Type0 font's ToUnicode CMap — are found by scanning
- * for `N 0 obj ... endobj` directly in the file bytes. If a producer moves
- * one into a compressed object stream and this extractor still cannot find
- * it (see the next paragraph for what IS handled), extraction degrades to
- * `pages_found: 0` / empty text rather than silently returning garbage —
- * check `warnings` before trusting a thin result.
- *
- * COMPRESSED OBJECT STREAMS (`/Type/ObjStm`) ARE SUPPORTED (fleet #2744,
- * added for Wyoming's statute PDFs, which — unlike Kentucky's — are
- * cross-reference-STREAM files whose Catalog and Pages root are themselves
- * compressed into an ObjStm: `5205 0 obj` never appears literally in the
- * file; it exists only as entry in a decompressed `/Type/ObjStm` stream).
- * Every direct `/Type/ObjStm` object found in the file is inflated up front;
- * its header (`/N` object pairs starting at byte `/First`) is parsed into a
- * `(object number -> dict text)` map, and `getObject` falls back to that map
- * whenever the direct byte-scan finds nothing. Per the PDF spec a compressed
- * object can never itself contain a stream (Contents, ToUnicode CMaps, and
- * ObjStm/XRef streams are therefore always direct objects, found the
- * original way) — so this fallback only ever needs to resolve plain
- * dictionaries/arrays (Catalog, Pages, Font, sometimes Page), which is
- * exactly what Wyoming's shape needs. An ObjStm nested inside another
- * ObjStm via `/Extends` is NOT walked — not observed in any file tested.
- *
- * ALSO FIXED HERE: the Catalog/Pages discovery no longer requires `/Type`
- * to be the first thing found after `<<` in a Catalog's own dictionary text
- * — the original `<<[^>]*\/Type\s*\/Catalog` regex broke the moment any
- * NESTED dict (e.g. `/MarkInfo<</Marked true>>`) appeared earlier in the
- * same object, because `[^>]*` cannot cross that inner `>>`. Wyoming's real
- * Catalog objects are exactly this shape (`/Lang(...)/MarkInfo<<...>>
- * /Metadata .../Pages .../Type/Catalog/ViewerPreferences<<...>>`, `/Type`
- * nowhere near the start). Discovery now finds `/Type/Catalog` (or
- * `/Type/Pages`) as plain text anywhere — direct or inside a decompressed
- * ObjStm — and locates its OWN object number by nearest preceding
- * `N 0 obj` marker, which works regardless of what else is in the dict.
- *
- * TWO FONT SHAPES, BOTH NEEDED (confirmed against real KRS statute PDFs,
- * fleet #2734):
- *   - Simple TrueType/Type1 with `/Encoding/WinAnsiEncoding` — the common
- *     case. WinAnsiEncoding is BY DESIGN identical to Windows code page 1252
- *     (that is what "WinAnsi" means), so the raw string-literal bytes decode
- *     directly via `TextDecoder('windows-1252')` with no per-glyph table of
- *     our own to get wrong.
- *   - Type0/CIDFontType2 with `/Encoding/Identity-H` — seen even inside an
- *     otherwise-simple statute, apparently whenever the PDF producer's text
- *     shaping fell back to a subset-embedded font for one run (KRS 532.025's
- *     closing sentence, which includes a curly apostrophe, was entirely in
- *     this font while the rest of the document used WinAnsi). Each character
- *     is a 2-byte CID with NO inherent meaning; the `/ToUnicode` CMap
- *     attached to the font is the only place the real Unicode value lives
- *     (`beginbfchar`/`beginbfrange` blocks). Skipping this font shape would
- *     have truncated or corrupted exactly the statutes that happen to use a
- *     special character — not a rare edge case, a silent one.
- *
- * Verified end-to-end against two real KRS statutes during this pack's
- * build: a single-page WinAnsi-only PDF (507.020, Murder) and a four-page PDF
- * mixing both font shapes (532.025, including the CID-encoded sentence
- * naming "Kimber's Law") — both reproduced the statute's true text exactly,
- * eyeballed against the rendered PDF.
- *
- * INDIRECT /Length (fleet #2743): extended for North Dakota's Century Code
- * chapter PDFs (ndlegis.gov/cencode/t*.pdf), whose content streams all write
- * `/Length` as an indirect reference ("/Length 3 0 R") rather than inlining
- * the literal integer the way every sampled KRS PDF did. The referenced
- * object is resolved (it is always a bare integer object, never itself a
- * stream) rather than falling back to scanning for the "endstream" keyword —
- * that fallback slices in the EOL bytes between the compressed data and the
- * keyword, which this repo's own Node zlib rejects as "trailing junk" even
- * though the compressed payload is intact (Workers' DecompressionStream may
- * be more lenient, but Node is what `prepush-tests.mjs` runs, so the bug was
- * real either way). Verified against ND Century Code chapter 12.1-16
- * (Homicide, t12-1c16.pdf) — every content stream in that 9-page PDF uses
- * the indirect form.
- */
-
-export interface GuPdfExtractResult {
-  /** Extracted text, pages joined with a blank line. Empty string if nothing
-   *  could be read — check `warnings`, not just truthiness, before deciding
-   *  that means the document has no text. */
-  text: string;
-  /** Number of leaf /Type/Page objects found via the Pages tree. */
-  pages: number;
-  /** Non-fatal problems found while extracting (unknown font, missing
-   *  ToUnicode, etc). A non-empty array does not mean the text is wrong, but
-   *  it means something was guessed rather than read. */
-  warnings: string[];
-}
-
-type FontDecoder =
-  | { kind: 'winansi' }
-  | { kind: 'cid'; map: Map<number, number> }
-  // Simple (1-byte-code) font decoded via its own /ToUnicode CMap rather than
-  // WinAnsi — see fontDecoderFor's comment on North Dakota's subsetted fonts.
-  | { kind: 'mapped1'; map: Map<number, number> };
-
-/** Inflate one `/FlateDecode` stream using the platform's own zlib — no
- *  dependency, works identically in the Workers runtime and in Node (used by
- *  this repo's prepush tests), because both implement the standard
- *  CompressionStream/DecompressionStream API over the zlib wire format PDF's
- *  FlateDecode filter already uses. */
-async function inflate(bytes: Uint8Array): Promise<Uint8Array> {
-  const ds = new DecompressionStream('deflate');
-  const writer = ds.writable.getWriter();
-  // FORK FIX 3/3 (not described in the file header's list of two — this one
-  // is a crash, not a decode-quality bug): malformed FlateDecode data (seen
-  // across several real Guam chapter PDFs, not a single outlier) rejects
-  // the writer side of the stream. The upstream code left those two writes
-  // fire-and-forget (`void writer.write(...)`), so that rejection became an
-  // UNHANDLED promise rejection — invisible to any try/catch wrapped around
-  // this function's caller, and fatal to the whole Node process (confirmed:
-  // crashed scripts/bake-sections.mjs outright, mid-run, with no chapter
-  // name in the trace). Attaching a no-op .catch() here does not hide a
-  // real failure — the SAME error still surfaces through `reader.read()`
-  // below, which the caller already catches; this only stops the detached
-  // write promise from also rejecting on its own.
-  const writeDone = writer.write(bytes).catch(() => {});
-  const closeDone = writer.close().catch(() => {});
-  void writeDone;
-  void closeDone;
-  const chunks: Uint8Array[] = [];
-  const reader = ds.readable.getReader();
-  for (;;) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    chunks.push(value);
-  }
-  const total = chunks.reduce((n, c) => n + c.length, 0);
-  const out = new Uint8Array(total);
-  let offset = 0;
-  for (const c of chunks) {
-    out.set(c, offset);
-    offset += c.length;
-  }
-  return out;
-}
-
-/**
- * Undo PDF string-literal escaping — `\(`, `\)`, `\\`, `\n`/`\r`/`\t`,
- * octal `\ddd`, and a trailing backslash-newline line continuation — on a
- * windows-1252-decoded slice. Safe to run on the decoded string rather than
- * raw bytes: every character this function inspects or produces (backslash,
- * parens, digits, the letters n/r/t/b/f) is plain ASCII, which windows-1252
- * never remaps, so the 1-byte-per-character alignment this relies on holds
- * throughout.
- */
-function unescapePdfLiteral(s: string): string {
-  let out = '';
-  for (let i = 0; i < s.length; i++) {
-    const c = s[i];
-    if (c !== '\\') { out += c; continue; }
-    const next = s[i + 1];
-    if (next === undefined) continue;
-    if (next === 'n') { out += '\n'; i++; }
-    else if (next === 'r') { out += '\r'; i++; }
-    else if (next === 't') { out += '\t'; i++; }
-    else if (next === 'b' || next === 'f') { i++; }
-    else if (next === '(' || next === ')' || next === '\\') { out += next; i++; }
-    else if (next >= '0' && next <= '7') {
-      let oct = next, j = i + 1, k = 0;
-      while (k < 2 && s[j + 1] >= '0' && s[j + 1] <= '7') { j++; oct += s[j]; k++; }
-      out += String.fromCharCode(parseInt(oct, 8) & 0xff);
-      i = j;
-    } else if (next === '\n') { i++; }
-    else if (next === '\r') { i++; if (s[i + 1] === '\n') i++; }
-    else { out += next; i++; }
-  }
-  return out;
-}
-
-interface RawObject {
-  dict: string;
-  streamBytes: Uint8Array | null;
-}
-
-/** Extract readable text from a simple, non-encrypted, non-scanned PDF. */
-export async function extractGuamPdfText(buf: ArrayBuffer): Promise<GuPdfExtractResult> {
-  const bytes = new Uint8Array(buf);
-  // windows-1252 decode is total (every byte maps to exactly one UTF-16 code
-  // unit) and length-preserving, so a match index found in `scan` is also a
-  // valid BYTE offset into `bytes` — used below to slice stream data without
-  // ever routing binary bytes through a lossy string round-trip.
-  const scan = new TextDecoder('windows-1252').decode(bytes);
-  const warnings: string[] = [];
-  const objCache = new Map<number, RawObject | null>();
-
-  // Byte offset of every DIRECT "N 0 obj" marker, sorted, for two uses: (1)
-  // the object-lookup fallback stays regex-per-object the same as before;
-  // (2) `objNumBefore` below answers "which object's text is this index
-  // inside", which is how Catalog/Pages/ObjStm discovery works regardless of
-  // what else that object's dictionary contains — see the file header.
-  const objStarts: { index: number; num: number }[] = [];
-  {
-    const re = /(\d+)\s+0\s+obj\b/g;
-    let m: RegExpExecArray | null;
-    while ((m = re.exec(scan))) objStarts.push({ index: m.index, num: parseInt(m[1], 10) });
-  }
-  function objNumBefore(markerIndex: number): number | null {
-    let lo = 0, hi = objStarts.length - 1, ans: number | null = null;
-    while (lo <= hi) {
-      const mid = (lo + hi) >> 1;
-      if (objStarts[mid].index <= markerIndex) { ans = objStarts[mid].num; lo = mid + 1; }
-      else hi = mid - 1;
-    }
-    return ans;
-  }
-
-  function getDirectObject(n: number): RawObject | null {
-    if (objCache.has(n)) return objCache.get(n) ?? null;
-    const re = new RegExp(`(?:^|\\D)${n}\\s+0\\s+obj`);
-    const m = re.exec(scan);
-    if (!m) { objCache.set(n, null); return null; }
-    const objStart = m.index + m[0].length;
-    const endobjIdx = scan.indexOf('endobj', objStart);
-    const streamIdx = scan.indexOf('stream', objStart);
-    let dict: string;
-    let streamBytes: Uint8Array | null = null;
-    if (streamIdx !== -1 && (endobjIdx === -1 || streamIdx < endobjIdx)) {
-      dict = scan.slice(objStart, streamIdx);
-      let dataStart = streamIdx + 'stream'.length;
-      if (bytes[dataStart] === 0x0d) dataStart++;
-      if (bytes[dataStart] === 0x0a) dataStart++;
-      // Matches EITHER "/Length 428" (literal) or "/Length 12 0 R"
-      // (indirect) — group 2 is present only for the indirect form. Written
-      // this way ON PURPOSE instead of the more obvious
-      // `/\/Length\s+(\d+)(?!\s+0\s+R)/` for a literal: that negative
-      // lookahead is a backtracking trap for any MULTI-DIGIT indirect
-      // reference. On "/Length 12 0 R", a greedy `(\d+)` first tries "12",
-      // the lookahead correctly forbids it (followed by " 0 R") — but the
-      // engine then backtracks `\d+` down to "1", at which point the
-      // lookahead is checked against "2 0 R", which does NOT start with
-      // whitespace, so the forbidden pattern no longer matches and the
-      // lookahead (wrongly) PASSES. The match silently becomes "1" instead
-      // of failing, so this object's /Length reads as the literal integer 1
-      // instead of as a reference to resolve — exactly the shape of North
-      // Dakota's Century Code chapter PDFs (fleet #2743), whose indirect
-      // Length refs are almost all two or more digits. An explicit optional
-      // group has nothing to backtrack: `(\d+)` greedily keeps "12" and the
-      // optional `(\s+0\s+R)?` either matches right after it or doesn't.
-      const lenDictMatch = /\/Length\s+(\d+)(\s+0\s+R)?/.exec(dict);
-      let dataEnd = -1;
-      if (lenDictMatch) {
-        if (!lenDictMatch[2]) {
-          dataEnd = dataStart + parseInt(lenDictMatch[1], 10);
-        } else {
-          // Indirect reference. The referenced object is a bare integer
-          // ("12 0 obj\n4541\nendobj"), never itself a stream, so resolving
-          // it through the same getObject() is safe (no recursion risk back
-          // onto object n). Falling back to scanning for the "endstream"
-          // keyword instead — which the pre-fix code did unconditionally
-          // here — slices in the EOL bytes PDF producers place between the
-          // compressed data and that keyword, which Node's strict zlib
-          // rejects as "trailing junk" even though the compressed payload
-          // itself is intact.
-          const lenObj = getObject(parseInt(lenDictMatch[1], 10));
-          const lenVal = lenObj ? parseInt(lenObj.dict.trim(), 10) : NaN;
-          if (Number.isFinite(lenVal) && lenVal >= 0) dataEnd = dataStart + lenVal;
-        }
-      }
-      if (dataEnd === -1) dataEnd = scan.indexOf('endstream', dataStart);
-      streamBytes = bytes.slice(dataStart, dataEnd);
-    } else {
-      dict = scan.slice(objStart, endobjIdx === -1 ? scan.length : endobjIdx);
-    }
-    const result = { dict, streamBytes };
-    objCache.set(n, result);
-    return result;
-  }
-
-  // Compressed objects (inside a /Type/ObjStm) — object number -> dict text.
-  // Populated below, before any Catalog/Pages/Font lookup runs, because a
-  // compressed Catalog or Pages root (Wyoming's shape) must resolve exactly
-  // like a direct one from that point on. Never holds a stream: the PDF spec
-  // forbids a compressed object from containing one.
-  const compressedObjects = new Map<number, string>();
-  {
-    const objStmNums: number[] = [];
-    const re = /\/Type\s*\/ObjStm\b/g;
-    let m: RegExpExecArray | null;
-    while ((m = re.exec(scan))) {
-      const n = objNumBefore(m.index);
-      if (n !== null) objStmNums.push(n);
-    }
-    for (const n of objStmNums) {
-      const obj = getDirectObject(n);
-      if (!obj || !obj.streamBytes) { warnings.push(`ObjStm ${n} has no stream data`); continue; }
-      let data: Uint8Array;
-      if (/\/Filter\s*\/FlateDecode/.test(obj.dict)) {
-        try {
-          data = await inflate(obj.streamBytes);
-        } catch (e) {
-          warnings.push(`inflate failed for ObjStm ${n}: ${e instanceof Error ? e.message : String(e)}`);
-          continue;
-        }
-      } else {
-        data = obj.streamBytes;
-      }
-      const nMatch = /\/N\s+(\d+)/.exec(obj.dict);
-      const firstMatch = /\/First\s+(\d+)/.exec(obj.dict);
-      if (!nMatch || !firstMatch) { warnings.push(`ObjStm ${n} missing /N or /First`); continue; }
-      const count = parseInt(nMatch[1], 10);
-      const first = parseInt(firstMatch[1], 10);
-      const header = new TextDecoder('latin1').decode(data.slice(0, first)).trim().split(/\s+/).map((x) => parseInt(x, 10));
-      const entries: { num: number; offset: number }[] = [];
-      for (let i = 0; i + 1 < header.length && entries.length < count; i += 2) {
-        entries.push({ num: header[i], offset: header[i + 1] });
-      }
-      const body = new TextDecoder('windows-1252').decode(data);
-      for (let i = 0; i < entries.length; i++) {
-        const start = first + entries[i].offset;
-        const end = i + 1 < entries.length ? first + entries[i + 1].offset : data.length;
-        if (start < 0 || end > data.length || start > end) {
-          warnings.push(`ObjStm ${n} entry ${entries[i].num} has an out-of-range offset, skipped`);
-          continue;
-        }
-        compressedObjects.set(entries[i].num, body.slice(start, end));
-      }
-    }
-  }
-
-  // The lookup every caller below actually uses: direct object text, falling
-  // back to a compressed one. Never both — a given object number is either
-  // found literally in the file or inside exactly one ObjStm, not both.
-  function getObject(n: number): RawObject | null {
-    const direct = getDirectObject(n);
-    if (direct) return direct;
-    const compressed = compressedObjects.get(n);
-    if (compressed !== undefined) return { dict: compressed, streamBytes: null };
-    return null;
-  }
-
-  async function decompressedStream(n: number): Promise<Uint8Array | null> {
-    const obj = getObject(n);
-    if (!obj || !obj.streamBytes) return null;
-    if (/\/FlateDecode/.test(obj.dict)) {
-      // FORK FIX (crash-adjacent, found while baking the section index — see
-      // bake-sections.mjs's header for how this surfaced): several real
-      // Guam chapter PDFs ("MS Word for Windows Document" producer, an
-      // older shape than the Neevia-converted ones this file's main header
-      // documents) store a /Length that is off by a small number of bytes
-      // from the TRUE deflate stream length — confirmed on 21gc033.pdf
-      // object 2: /Length says 96, the deflate stream is complete at byte
-      // 95, and the 96th byte is one stray trailing byte. Python's zlib
-      // tolerates trailing garbage by default; the Workers/Node
-      // DecompressionStream used here does not and throws
-      // ERR_TRAILING_JUNK_AFTER_STREAM_END. Rather than fail the whole page
-      // (or, before an earlier fix in this same fork, crash the process via
-      // an unhandled rejection), retry with the slice trimmed one byte
-      // shorter a few times — the true stream length is always <= the
-      // declared one in every sample seen, never longer.
-      for (let trim = 0; trim <= 4 && trim < obj.streamBytes.length; trim++) {
-        try {
-          return await inflate(trim === 0 ? obj.streamBytes : obj.streamBytes.subarray(0, obj.streamBytes.length - trim));
-        } catch (e) {
-          if (trim === 4) {
-            warnings.push(`inflate failed for object ${n} even after trimming trailing bytes: ${e instanceof Error ? e.message : String(e)}`);
-            return null;
-          }
-        }
-      }
-      return null;
-    }
-    return obj.streamBytes;
-  }
-
-  // Catalog -> Pages -> Kids, walked in document order. Falls back to the
-  // first /Type/Pages object if no /Type/Catalog is found. Both searches
-  // look for the TYPE MARKER as plain text first (direct text, or inside any
-  // decompressed ObjStm body) and then find which object that text belongs
-  // to — see the file header for why this replaced a single greedy regex.
-  let pagesRef: number | null = null;
-  function findObjWithType(typeName: string): number | null {
-    const directIdx = scan.search(new RegExp(`/Type\\s*/${typeName}\\b`));
-    if (directIdx !== -1) {
-      const n = objNumBefore(directIdx);
-      if (n !== null) return n;
-    }
-    const typeRe = new RegExp(`/Type\\s*/${typeName}\\b`);
-    for (const [num, text] of compressedObjects) {
-      if (typeRe.test(text)) return num;
-    }
-    return null;
-  }
-  const catNum = findObjWithType('Catalog');
-  if (catNum !== null) {
-    const catObj = getObject(catNum);
-    const pm = catObj ? /\/Pages\s+(\d+)\s+0\s+R/.exec(catObj.dict) : null;
-    if (pm) pagesRef = parseInt(pm[1], 10);
-  }
-  if (pagesRef === null) {
-    pagesRef = findObjWithType('Pages');
-  }
-
-  const leafPages: number[] = [];
-  function walkPages(n: number, depth: number): void {
-    if (depth > 12) { warnings.push('Pages tree exceeded depth 12, stopped walking'); return; }
-    const obj = getObject(n);
-    if (!obj) return;
-    if (/\/Type\s*\/Page\b(?!s)/.test(obj.dict)) { leafPages.push(n); return; }
-    const kidsMatch = /\/Kids\s*\[([^\]]*)\]/.exec(obj.dict);
-    if (!kidsMatch) return;
-    for (const km of kidsMatch[1].matchAll(/(\d+)\s+0\s+R/g)) walkPages(parseInt(km[1], 10), depth + 1);
-  }
-  if (pagesRef !== null) walkPages(pagesRef, 0);
-  else warnings.push('no /Type/Catalog or /Type/Pages object found');
-
-  /** Parse a /ToUnicode CMap stream's `beginbfchar`/`beginbfrange` blocks into
-   *  a code -> Unicode-codepoint map. Shared between Type0's 2-byte CIDs and
-   *  a simple font's 1-byte codes — the CMap text format is identical either
-   *  way; only how the caller SLICES its hex string differs (see decodeRun). */
-  async function parseToUnicodeCMap(cmapObjNum: number): Promise<Map<number, number>> {
-    const cmapBytes = await decompressedStream(cmapObjNum);
-    const cmapText = cmapBytes ? new TextDecoder('latin1').decode(cmapBytes) : '';
-    const map = new Map<number, number>();
-    for (const block of cmapText.matchAll(/beginbfchar([\s\S]*?)endbfchar/g)) {
-      for (const pair of block[1].matchAll(/<([0-9A-Fa-f]+)>\s*<([0-9A-Fa-f]+)>/g)) {
-        map.set(parseInt(pair[1], 16), parseInt(pair[2].slice(0, 4), 16));
-      }
-    }
-    for (const block of cmapText.matchAll(/beginbfrange([\s\S]*?)endbfrange/g)) {
-      for (const triple of block[1].matchAll(/<([0-9A-Fa-f]+)>\s*<([0-9A-Fa-f]+)>\s*<([0-9A-Fa-f]+)>/g)) {
-        const lo = parseInt(triple[1], 16), hi = parseInt(triple[2], 16), base = parseInt(triple[3].slice(0, 4), 16);
-        for (let c = lo; c <= hi && c - lo < 65536; c++) map.set(c, base + (c - lo));
-      }
-    }
-    return map;
-  }
-
-  async function fontDecoderFor(fontObjNum: number): Promise<FontDecoder> {
-    const obj = getObject(fontObjNum);
-    if (!obj) return { kind: 'winansi' };
-    if (/\/Subtype\s*\/Type0\b/.test(obj.dict)) {
-      const tuMatch = /\/ToUnicode\s+(\d+)\s+0\s+R/.exec(obj.dict);
-      if (!tuMatch) {
-        warnings.push(`Type0 font object ${fontObjNum} has no /ToUnicode; its text will show as U+FFFD`);
-        return { kind: 'cid', map: new Map() };
-      }
-      const map = await parseToUnicodeCMap(parseInt(tuMatch[1], 10));
-      return { kind: 'cid', map };
-    }
-    // Simple font. Every KRS sample used /WinAnsiEncoding, which decodes
-    // directly as windows-1252 bytes below — unchanged. North Dakota's
-    // Century Code PDFs (fleet #2743) use simple TrueType fonts that declare
-    // NO /Encoding at all: their embedded subsets number glyphs 0, 1, 2... in
-    // whatever order the subsetter emitted them, with no relationship to any
-    // standard code page — reading code 0x01 as the WinAnsi byte 0x01 (a
-    // control character) produces blank/garbled output, not a wrong letter.
-    // Those fonts DO carry a /ToUnicode CMap (the same mechanism Type0 fonts
-    // use above, just keyed by a 1-byte code instead of a 2-byte CID), which
-    // is the only place the real character is recorded — use it whenever the
-    // font isn't declared WinAnsi rather than guessing.
-    if (!/\/Encoding\s*\/WinAnsiEncoding\b/.test(obj.dict)) {
-      const tuMatch = /\/ToUnicode\s+(\d+)\s+0\s+R/.exec(obj.dict);
-      if (tuMatch) {
-        const map = await parseToUnicodeCMap(parseInt(tuMatch[1], 10));
-        // FORK FIX 2/2: Guam's embedded "...+WPTypographicSymbols" font (used
-        // only for curly quote marks) carries a /ToUnicode CMap that is
-        // itself wrong in the source PDF — code 1 (left curly quote) maps to
-        // U+0041 ('A') and code 2 (right curly quote) maps to U+0040 ('@').
-        // Confirmed by eye: "ADirector of Public Safety@" in the raw
-        // extraction is exactly "“Director of Public Safety”" with
-        // those two codes substituted back — the intended reading, not a
-        // coincidence. See this file's header. Any PDF viewer's copy-paste
-        // reproduces the same wrong codes, so this is a defect in Guam's own
-        // published file, overridden here by font name rather than trusted.
-        if (/WPTypographicSymbols/.test(obj.dict)) {
-          const fixed = new Map(map);
-          fixed.set(1, 0x201c);
-          fixed.set(2, 0x201d);
-          return { kind: 'mapped1', map: fixed };
-        }
-        if (map.size) return { kind: 'mapped1', map };
-      }
-      warnings.push(`font object ${fontObjNum} has a non-WinAnsi simple encoding and no usable /ToUnicode; decoded as WinAnsi anyway`);
-    }
-    return { kind: 'winansi' };
-  }
-
-  const TOKEN_RE =
-    /\/(\S+)\s+[\d.]+\s+Tf|\[((?:\\.|[^\]])*)\]\s*TJ|<([0-9A-Fa-f\s]*)>\s*Tj|\(((?:\\.|[^()])*)\)\s*Tj|1\s+0\s+0\s+1\s+[\d.-]+\s+([\d.-]+)\s+Tm/g;
-  const TJ_PIECE_RE = /\(((?:\\.|[^()])*)\)|<([0-9A-Fa-f\s]*)>/g;
-
-  function decodeRun(dec: FontDecoder, literal: string | undefined, hex: string | undefined): string {
-    if (literal !== undefined) {
-      const unescaped = unescapePdfLiteral(literal);
-      // FORK FIX 1/2: a WinAnsi run's literal-string bytes ARE already the
-      // correct windows-1252 text (unchanged from upstream) — but Guam's
-      // producer also writes its non-WinAnsi subset fonts' text as literal
-      // strings rather than hex, so a 'mapped1'/'cid' run must be resolved
-      // through the SAME font decoder a hex run below uses, not passed
-      // through as if the raw byte were already the character. See this
-      // file's header for how this was confirmed live.
-      if (dec.kind === 'winansi') return unescaped;
-      let out = '';
-      for (let i = 0; i < unescaped.length; i++) {
-        const code = unescaped.charCodeAt(i) & 0xff;
-        out += String.fromCodePoint(dec.map.get(code) ?? 0xfffd);
-      }
-      return out;
-    }
-    const cleaned = (hex ?? '').replace(/\s+/g, '');
-    let out = '';
-    if (dec.kind === 'mapped1') {
-      // 1-byte code per glyph (a simple font's code space), unlike Type0's
-      // 2-byte CIDs below — see fontDecoderFor.
-      for (let i = 0; i + 2 <= cleaned.length; i += 2) {
-        const code = parseInt(cleaned.slice(i, i + 2), 16);
-        out += String.fromCodePoint(dec.map.get(code) ?? 0xfffd);
-      }
-      return out;
-    }
-    for (let i = 0; i + 4 <= cleaned.length; i += 4) {
-      const cid = parseInt(cleaned.slice(i, i + 4), 16);
-      if (dec.kind === 'cid') out += String.fromCodePoint(dec.map.get(cid) ?? 0xfffd);
-      else out += String.fromCharCode(cid & 0xff);
-    }
-    return out;
-  }
-
-  const pageTexts: string[] = [];
-  for (const pn of leafPages) {
-    const page = getObject(pn);
-    if (!page) continue;
-
-    let resourcesDict = page.dict;
-    const resRef = /\/Resources\s+(\d+)\s+0\s+R/.exec(page.dict);
-    if (resRef) {
-      const ro = getObject(parseInt(resRef[1], 10));
-      if (ro) resourcesDict = ro.dict;
-    }
-    // /Font is usually inline in Resources, but North Dakota's Century Code
-    // PDFs (fleet #2743) write it as an indirect reference ("/Font 18 0 R")
-    // to a separate dict object — resolve that one hop before giving up.
-    let fontDictBody: string | null = null;
-    const inlineFontMatch = /\/Font\s*<<([^>]*)>>/.exec(resourcesDict);
-    if (inlineFontMatch) {
-      fontDictBody = inlineFontMatch[1];
-    } else {
-      const fontRefMatch = /\/Font\s+(\d+)\s+0\s+R/.exec(resourcesDict);
-      if (fontRefMatch) {
-        const fontObj = getObject(parseInt(fontRefMatch[1], 10));
-        if (fontObj) fontDictBody = fontObj.dict;
-      }
-    }
-    const fontMap = new Map<string, FontDecoder>();
-    if (fontDictBody) {
-      for (const fm of fontDictBody.matchAll(/\/(\S+?)\s+(\d+)\s+0\s+R/g)) {
-        fontMap.set(fm[1], await fontDecoderFor(parseInt(fm[2], 10)));
-      }
-    }
-
-    const contentsMatch = /\/Contents\s*(\[[^\]]*\]|\d+\s+0\s+R)/.exec(page.dict);
-    const contentRefs = contentsMatch
-      ? [...contentsMatch[1].matchAll(/(\d+)\s+0\s+R/g)].map((m) => parseInt(m[1], 10))
-      : [];
-    let raw = '';
-    for (const cr of contentRefs) {
-      const dec = await decompressedStream(cr);
-      if (dec) raw += new TextDecoder('latin1').decode(dec) + '\n';
-    }
-
-    let out = '';
-    let currentFont: string | null = null;
-    let lastY: number | null = null;
-    for (const m of raw.matchAll(TOKEN_RE)) {
-      if (m[1] !== undefined) { currentFont = m[1]; continue; }
-      if (m[5] !== undefined) {
-        const y = parseFloat(m[5]);
-        if (lastY !== null && Math.abs(y - lastY) > 1) out += '\n';
-        lastY = y;
-        continue;
-      }
-      const dec = (currentFont && fontMap.get(currentFont)) || { kind: 'winansi' as const };
-      if (m[2] !== undefined) {
-        for (const piece of m[2].matchAll(TJ_PIECE_RE)) out += decodeRun(dec, piece[1], piece[2]);
-      } else if (m[3] !== undefined) {
-        out += decodeRun(dec, undefined, m[3]);
-      } else if (m[4] !== undefined) {
-        out += decodeRun(dec, m[4], undefined);
-      }
-    }
-    pageTexts.push(out.trim());
-  }
-
-  return { text: pageTexts.join('\n\n'), pages: leafPages.length, warnings };
-}