[PerchAnton]

The existing golden-vector tests checked the current build, but did not compare its public API and identifiers with packages already used by consumers. This prepares the RefMint 1.0 API contract and adds an installed-package compatibility gate, including the alpha.3 integration in Billetsys #207.

The contract fixes public ESM imports, factories, types, results, error precedence, exception classes, normalization and versioning rules. The migration guide keeps existing-ID v1 and legacy random formats and explains direct upgrades from alpha.3 and rollback. Runtime sources and the original 23 frozen vectors are unchanged. The package remains beta.2; stable publication and the Billetsys dependency update are separate steps.

pnpm test:compatibility verifies SHA-512-pinned npm alpha.3/beta.2 archives, installs them and the exact packed candidate in an isolated offline consumer, and checks all nine writer/reader pairs. Coverage includes 23 original vectors, five synthetic Billetsys IDs, malformed payloads with valid checksums, errors/diagnostics, imports and the same strict TypeScript consumer against each archive. test:package runs this on its exact archive in the existing Node/OS CI matrix. Temporary consumers are removed on success and failure.

Canonical readers now reject each presentation that human-input readers may normalize: uppercase, leading/trailing ASCII whitespace and grouping are tested separately. Exception tests distinguish TypeError from RangeError instead of accepting any thrown error. These close two gaps found during review of the compatibility gate.

Validation on macOS ARM / Node 26.13.0 / pnpm 11.25.0, head 5b1e729:

• pnpm check: 39 tests and TypeScript passed.
• pnpm test:package: installed archive, documentation and 21 compatibility tests passed; all three declaration sets compiled with TypeScript 5.9.3.
• Controlled mutations of temporary archives: the previous compatibility gate accepted canonical readers that lowercased or trimmed input, and accepted a generic Error instead of RangeError for out-of-range uint64. The updated gate rejects all three; the correct packages pass. No altered archive was committed or published.
• git diff --check passed. All seven CI checks passed on this head: Node 22/24/26 Linux, Node 24 Windows/macOS, Chromium/Firefox/WebKit and PDF extraction/lookup. Live Billetsys backend authorization is outside this PR.