PerchAnton · Nov 7, 2026 · Nov 7, 2026 · Nov 7, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- Fix the public API contract for 1.0 preparation and document alpha.3 upgrade/rollback without changing wire v1. No stable version is published by this change.
+- Check the exact candidate archive against integrity-pinned npm alpha.3 and beta.2: all nine writer/reader pairs, historical and Billetsys vectors, errors, exports and strict TypeScript consumers.
+- Reject canonical-reader regressions for case/whitespace as well as grouping, and verify the documented exception classes across all three packages.
+
 ## 0.1.0-beta.2
 
 - Record the twelve measured tasks from the single-participant manual-entry pilot. In this pilot the participant entered both the existing number and the short alias faster than RefMint.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -12,6 +12,17 @@ For the existing-ID format or comparison, run `pnpm compare` after the build and
 
 The build keeps JSDoc in declarations and removes comments only from emitted JS. Keep the full-root and codec-only size figures separate; include compression costs. After runtime changes, refresh the historical comparison with `pnpm compare:previous PATH_TO_PREVIOUS_DIST FULL_COMMIT_SHA` as described in [comparison methods](docs/comparison.md#before-and-after-optimization). The recorded previous baseline is `daaffe813fd0351752bd158314917267acddc1b6`. Do not compare historical timings collected on different machines as a before/after speedup.
 
+## API compatibility
+
+Preserve the [1.0 preparation contract](docs/stable-contract.md). Run
+`pnpm test:compatibility` to compare the packed candidate against SHA-512-pinned
+alpha.3 and beta.2; `pnpm test:package` runs the same matrix on its exact archive.
+The two historical downloads require network access, fail closed on integrity
+errors, and install offline with ignored scripts and no runtime dependencies.
+Do not replace their pins or regenerate historical vectors to hide a break.
+Keep the TypeScript consumer and both writer/reader directions covered.
+Temporary consumers and archives are removed even after failures.
+
 ## Publishing a prerelease
 
 Use a clean, reviewed commit and verify that its CI passed. Keep the version, changelog and evidence version in sync. A published npm name/version cannot be reused. For the beta candidate, keep both `publishConfig.tag` and the explicit publication tag set to `beta`. Do not move the existing `alpha` or `latest` tags.

diff --git a/README.md b/README.md
@@ -15,6 +15,10 @@ npm install --save-exact refmint@0.1.0-beta.2
 [Beta release and checksum](https://github.com/PerchAnton/refmint/releases/tag/v0.1.0-beta.2) ·
 [API compatibility and frozen v1 format](docs/beta-contract.md) · [Verified npm installation](docs/evidence/release-beta2.json).
 
+[API contract for 1.0 preparation](docs/stable-contract.md) ·
+[Upgrade checks from alpha.3](docs/migration-alpha3-to-1.md). The package remains in beta;
+the compatibility matrix compares published releases with an unpublished archive.
+
 **Try an invoice lookup.** The [sample PDF](https://github.com/PerchAnton/refmint/blob/v0.1.0-beta.2/examples/workflows/sample-invoice.pdf)
 shows `INV-2026-000042`, the short alias `D1042` and the 21-character printed
 reference `INVOICE_1PQP2-UYWU-CW` for the same record. In the

diff --git a/docs/beta-contract.md b/docs/beta-contract.md
@@ -45,6 +45,13 @@ new prerelease, explicit migration notes and regression evidence; never replace
 an existing version. Internal modules, example UI and benchmark timings are outside
 this contract. A stable 1.0 support/deprecation policy is a separate decision.
 
+## Preparing the stable API
+
+The [1.0 API contract](stable-contract.md) and [alpha.3 migration guide](migration-alpha3-to-1.md)
+carry these existing guarantees forward. The installed-archive check now compares
+alpha.3, beta.2 and the unpublished candidate, without changing package version or
+wire v1. Publication and consumer-native acceptance remain separate steps.
+
 ## What beta does not prove
 
 The [existing workflow comparison](workflows.md) is synthetic. The

diff --git a/docs/format-v1.md b/docs/format-v1.md
@@ -58,7 +58,7 @@ After a valid checksum: check namespace; require two header symbols; check versi
 
 ## Compatibility commitment
 
-The v1 layout, canonical encoding and accepted presentation forms defined here are frozen. Changes to that wire contract require a new version and reader; they must not change v1 output. Package APIs may continue to evolve during alpha. Explicit versioning does not authorize removal of v1 readers from deployed applications.
+The v1 layout, canonical encoding and accepted presentation forms defined here are frozen. Changes to that wire contract require a new version and reader; they must not change v1 output. The [API contract for 1.0 preparation](stable-contract.md) is separate from this wire contract. Package version 1.0 does not change wire v1. Explicit versioning does not authorize removal of v1 readers from deployed applications.
 
 The alpha.1 random-reference format remains available through `createReferences`, with its generation, parsing and error-result shapes preserved. Its HRP grammar prohibits underscores. The new HRP requires one, so the formats are structurally disjoint even when the namespace and data lengths happen to match. Each API rejects the other's format. Do not fall back from a failed v1 parse to guessing a legacy ID or another version.
 

diff --git a/docs/migration-alpha3-to-1.md b/docs/migration-alpha3-to-1.md
@@ -0,0 +1,78 @@
+# Preparing an alpha.3 → 1.0 upgrade
+
+There is no published 1.0 in this change. This guide describes the prepared
+[API contract](stable-contract.md) and the checks required before upgrading.
+Keep the consumer's current exact pin until the stable archive and integration
+change have been reviewed. Installing a prerelease does not satisfy a stable-1.0
+requirement, and npm dist-tags must not be used as compatibility evidence.
+
+## Preferred path: keep v1 and the same API
+
+The alpha.3 and beta.2 APIs are unchanged in this preparation. Callers continue
+to use the same imports, factory configuration and result checks:
+
+```ts
+import { createReferenceCodec } from 'refmint/codec';
+
+const tickets = createReferenceCodec({ prefix: 'btk', kind: 'uint64', version: 1 });
+const code = tickets.encode(42n); // btk_1pqp2cy59jf
+const printed = tickets.format(code); // btk_1pqp2-cy59-jf
+const result = tickets.decode(printed);
+if (result.ok) {
+  const existingId: bigint = result.value;
+  // Apply the application's ID bounds and authorization before lookup.
+}
+```
+
+For Billetsys, retain `btk` / uint64 / wire v1 and positive signed Java Long IDs.
+Use exact decimal strings for JSON values beyond Number's safe-integer range;
+converting an already-rounded Number to bigint cannot recover the original ID.
+Keep the normal ticket routes, server permission checks and default-off feature
+flag. The example and frozen application vectors are exercised by the installed
+package compatibility matrix; they do not exercise a live Billetsys server.
+
+1. Inventory previously issued codes and their namespace/kind/version or random
+   prefix/length configuration. Preserve the old package and lockfile. Unknown
+   deployment history is not evidence that no codes were issued.
+2. Check `pnpm test:compatibility` on the exact candidate archive. Both directions
+   matter: old codes must resolve in the candidate, and newly generated v1 codes
+   must resolve in alpha.3 for mixed deployments and rollback. Preserve all old
+   vectors, including boundary IDs and codes copied from synthetic documents.
+3. After a stable version is published and accepted by the consumer's maintainers,
+   update the exact dependency and lockfile in a separate integration PR. No
+   intermediate beta.2 deployment is required. Keep API usage and format settings.
+4. Run the application's existing tests and real permission/lookup checks, test
+   missing/forbidden/wrong-record cases, and exercise old and new frontends together.
+   In Billetsys retain the disabled/enabled bundle tests and lazy-loading behavior.
+5. Test rollback of the package/bundle. With unchanged v1, new codes remain readable
+   by the previous application. Keep ordinary identifier search available.
+
+When those gates pass and format/configuration stay unchanged, there is **no
+database migration, mapping table, backfill, ID replacement or code reissue**.
+Printed/emailed codes keep their identity. Random-reference users must retain
+their existing mapping, uniqueness constraints and namespace length.
+
+## If an incompatible change becomes necessary
+
+An API-only change needs explicit call-site migration or a compatible adapter;
+it need not change stored identifiers. Prefer preserving the alpha.3 calls.
+
+A necessary new wire format must get its own version and specification. Deploy
+readers for both formats while still writing v1, then enable the new writer only
+after consumer approval. Retain v1 readers for the lifetime of already-issued
+references. A failed checksum or unknown version must not trigger fallback guessing.
+After issuing v2, rollback must keep the dual reader: a v1-only binary cannot read
+v2. Switching writers back to v1 does not undo codes already shared with users.
+
+If a prior bug admitted ambiguous or invalid codes, isolate the affected case,
+add a regression and agree a repair path. Never silently choose another record
+or rewrite historical vectors. No such format change is required by this PR.
+
+## Remaining release and integration decisions
+
+Stable publication, release-channel checks, support/deprecation ownership and
+consumer-native acceptance remain [release gates](stability.md). The library owner
+reviews and publishes the package; consumer maintainers choose the pin, target
+branch, timing, rollout and whether to enable the feature. There is no calendar
+release promise here. The [pilot limitations](manual-entry-pilot.md), PDF demo and
+security boundaries continue to apply; compatibility is not a speed claim.
diff --git a/docs/stability.md b/docs/stability.md
@@ -11,6 +11,14 @@ version and reader. This is not a promise that the API, error diagnostics,
 supported environments or support policy will never change. Applications must
 retain the readers needed for references they have already issued.
 
+## API and compatibility preparation
+
+The [1.0 API contract](stable-contract.md) fixes the surface being prepared.
+`pnpm test:package` now compares its exact archive with integrity-pinned alpha.3
+and beta.2 in both directions, including TypeScript consumers and historical
+Billetsys codes. See [upgrade and rollback checks](migration-alpha3-to-1.md).
+This work does not publish 1.0 or complete the remaining gates below.
+
 ## Criteria before a stable release
 
 - Review and freeze the public API and error behavior; document any migration from