@normativepdf/recover

Reads a PDF as far as it can when the cross-reference table does not follow ISO 32000-2 §7.5.

It walks startxref → /Prev. When a link cannot be followed it falls back to an earlier startxref. When no section can be read at all it scans the file for N G obj and rebuilds the table. Whatever it does, it returns how far it got.

🔴 This package does not judge conformance. DocumentScope and ReadingScope answer "how much was read", not "does this conform". Conformance is the caller's decision.

Why this is not part of the core

normativepdf reads §7.5 as written and throws on a document that violates it. That is the right behaviour for a library. But documents that arrive for auditing are usually the damaged ones, and refusing them means nobody ever sees what is inside.

This package sits outside the core. The core says "this violates the clause, so I will not accept it"; this package decides what to do with the documents it refused. Re-reading involves guesswork — trying an earlier startxref, detecting cycles, rebuilding the table — so it does not belong in a core whose 2,907-specimen gate asserts that it reads exactly what the clause says. The reasoning is in ADR-0010.

Install

npm install @normativepdf/recover

normativepdf is the only dependency.

Usage

import { openDocument, toReadingScope } from '@normativepdf/recover';

const { doc, scope } = await openDocument(bytes);

if (scope.reconstructed) {
  // The cross-reference table here was rebuilt by this package. It is not the
  // one the file carries, and a reader of the report needs to be told so.
}

// The shape meant for output (COS dictionaries dropped)
const declared = toReadingScope(scope);

openDocument works in two steps.

1. Hand the bytes to parsePdf. If that succeeds, use the result unchanged.
2. If it refuses, re-read using the recovery steps below and assemble a document.

Across pdf-verify-mcp's 2,947 specimens, 2,930 succeed at step 1. Only the remaining 17 reach step 2, and only those 17 stop being "what the library read". scope.recovered records which path a document took.

The four recovery steps

1. If the last startxref is unreadable, try earlier ones in turn (recorded in newestSectionUnreadable).
2. If /Prev is not a positive integer, stop following it — and do not claim the chain was walked to the end.
3. Stop on a cycle, and at 200 revisions.
4. Fold the two sections of a linearised file (Annex F) into one revision.

Why the walk stopped is in scope.chainStop.kind, using the same five values as normativepdf (complete / prev-zero / unreadable / cyclic / malformed). "Reached the end" and "could not go further" are different values.

Debug output

Nothing is written anywhere by default. Pass a function if you want output.

await openDocument(bytes, {
  onDebug: (context, message) => process.stderr.write(`[${context}] ${message}\n`),
});

🔴 Do not pass a function that writes to stdout. The first consumer of this package is an MCP server, where bytes on stdout are read as JSON-RPC messages and fail to parse.

What is in it

| File | Contents | |---|---| | cos.ts | Functions for reading COS (asDict, asRef, tryResolve, enumerateObjects, decodedBytes, …). No judgement is written here | | xref-walk.ts | walkXrefChain and reconstructXref, plus the four steps above. Also byte-level helpers such as findOrigin and readToken | | document.ts | openDocument / DocumentScope / toReadingScope |

These 1,189 lines were moved unchanged out of pdf-verify-mcp 0.21.1's src/services/. That the move changed no output was checked over 2,950 specimens × 7 tools = 20,650 calls, with zero differences.

日本語版は README.ja.md。

License

MIT