RefMint 0.1.0-alpha.3 — lookup workflows and PDF example

RefMint 0.1.0-alpha.3 — evaluate the lookup workflow

This alpha adds a concrete way to evaluate an extra reference before adopting it.
Runtime JavaScript and TypeScript APIs are unchanged from alpha.2; the existing-ID v1
wire contract remains frozen. There are still zero runtime dependencies.

• Compare existing hostname/invoice-number lookup, a five-character local alias and
  RefMint on the same records, including partial input, typos and another valid code.
• Download the sample PDF and use its three identifiers in the local lookup form.
  Verification extracts the text from the PDF itself and resolves the same invoice.
  Original invoice numbering, leading zeros and regulated identifiers stay separate.
• Inspect all 54 selected synthetic cases (2 workflows × 3 routes × 9 cases), including
  costs that favor current identifiers. Fleet codes in this sample have 49 printed
  characters versus an 8-character hostname or 5-character alias; the invoice code has
  21 versus a 15-character number or 5-character alias.
• Read when RefMint is unnecessary and how alpha API status differs from a frozen wire
  format. A checksum does not authenticate, authorize, or prove the intended record.

These fixtures are not real support data, a human-entry study, or an upstream integration.
No reduction in support time or new performance improvement is claimed. Existing size
and timing reports retain their original alpha.2 date/environment because runtime hashes
are unchanged; the carried-forward measurement version is explicit.

npm install refmint@alpha
# Pin exactly:
npm install --save-exact refmint@0.1.0-alpha.3

The same verified .tgz is published on npm and attached here. alpha is the intended
installation tag; no stable version is being declared. Node.js 22+ and ES modules are
required for Node consumers. The npm package includes runtime, declarations and docs;
forms, tests and PDF-generation tools live in the tagged source.

To run the workflow from the tagged source:

pnpm install --frozen-lockfile --ignore-scripts
pnpm build
pnpm test:workflows
pnpm demo

Open http://127.0.0.1:4173/workflows/ and download the sample PDF from the form.

Validation: 39 Node tests, TypeScript, 54 fixture cases, existing Bech32m comparison
(28 scenarios and 1,576 mutations per adapter), two HTTP tests, offline package
installation, 21 Chromium/Firefox/WebKit tests, and PDF extraction/lookup in CI.
CI covers Node 22/24/26 and Linux/Windows/macOS. A fresh npm installation and archive
integrity are checked after publication. SHA256SUMS.txt covers all attached artifacts.

npm ·
Workflow and limits ·
All outcomes ·
When not to use RefMint

Release commit: 0a16b09cf3e95a40a88219ccfdde0cd738d53924. All seven CI jobs passed.

Published and verified on 28 October 2026. The fresh npm install, public imports, eight existing-ID round trips and archive hash checks passed; details are in verification.json. The alpha dist-tag points to this release; the existing latest tag was left unchanged.

RefMint v0.1.0-alpha.2

RefMint v0.1.0-alpha.2

This alpha adds reversible references for existing uint64 and UUID values, detailed input diagnostics and a versioned format. Random references from alpha.1 keep their existing behavior. No alias table or second random ID is required for the existing-ID workflow.

• Use createReferenceCodec from refmint or the smaller refmint/codec entry. Both export the same implementation and TypeScript brands.
• diagnose reports raw-input character positions and expected/actual lengths without guessing a corrected reference.
• The existing-ID v1 wire format is documented and frozen, with compatibility vectors. Package APIs remain experimental during alpha.
• The tagged source includes a complete return-lookup form and an independent bech32@2.0.0 Bech32m adapter using identical inputs, records and validation rules.

Measured improvements

All sizes below include the application adapter. They are unminified JavaScript module totals, not install-archive or bundle sizes.

Measurement	Previous RefMint	RefMint alpha.2	Bech32m + adapter
Form JS bytes	15,255	8,773 (codec-only import)	9,327
Summed per-file gzip bytes	5,791	3,353	3,160
Median diagnostic checks/s	556,352	1,779,391	822,457

The complete RefMint root import is 14,147 bytes with its adapter, 7.3% smaller than before. The codec-only form loads 42.5% less JS than the previous form. RefMint removes implementation comments from shipped JS while preserving source and declaration documentation. Bech32m remains smaller after gzip.

The three-way timing run used the same 28 cases in one process on Node 24.19.0 / Apple M3: nine rotated-order rounds with warmup and consumed results. It measured 3.20× the previous RefMint and 2.16× this Bech32m adapter for this workload. This is not a general speed guarantee, browser benchmark or human-entry study. Reference lengths and checksum behavior are the same in both form implementations.

Methods and reproduction · Format v1

Validation

• 36 core tests, including standard vectors, an independent checksum oracle, integer/UUID boundaries and ASCII input-error precedence.
• All 123,146 differential comparisons against the previous build matched.
• Both adapters matched all 28 shared scenarios and rejected all 1,576 selected single-symbol mutations.
• TypeScript checks, two HTTP-server tests, evidence hashes and offline installation of the package with both public import paths.
• 15 Chromium/Firefox/WebKit tests in hosted CI, including verification that the comparison form does not load the full root module.

All six release-preparation CI jobs passed. Release commit: 6c89051; its tree is identical to the tested preparation commit. The merge preserves the baseline commit for benchmark reproduction. Browser CI uses a pinned Playwright image with preinstalled engines and system dependencies.

CI on the merged main commit also passed.

Install

Published on npm on 2026-10-28: refmint@0.1.0-alpha.2.

npm install refmint@alpha

To pin this release: npm install --save-exact refmint@0.1.0-alpha.2. npm also assigned the first published version to latest, so npm install refmint currently installs this same alpha. Both commands were tested in fresh consumers; the public registry archive matches the verified npm package.

The npm archive updates only README, changelog and contributor documentation. All 21 other files (runtime, declarations, package metadata, evidence and remaining documents) are identical to the original GitHub alpha.2 archive. The original tag and attached archive are unchanged. npm archive SHA-256: 582c57f77265722e94497f934f8bcaf8857c1fc21b0125734aea63567420a6f4.

Alternatively, download the attached GitHub .tgz and install it:

npm install ./refmint-0.1.0-alpha.2.tgz

Or, with npm 12:

npm install --allow-remote=root https://github.com/PerchAnton/refmint/releases/download/v0.1.0-alpha.2/refmint-0.1.0-alpha.2.tgz

This remains an alpha prerelease. RefMint 0.1.0-alpha.2 is also published on npm. Node.js 22+ and ES modules are required for Node consumers. The archive includes JavaScript, TypeScript declarations, documentation and licenses. Run the forms and benchmark scripts from the tagged source checkout.

Assets include evidence.json, comparison.json, optimization.json, verification.json and SHA256SUMS.txt. The comparison reports retain their measurement timestamps, environment and source hashes.

Checksums are public error detection, not authentication. Existing-ID encoding is reversible, including sequential IDs; authorize lookups in the application. License: MIT OR Apache-2.0, with retained third-party notices.

Full changes · PR #4

RefMint 0.1.0-alpha.1 — public reference codes

RefMint's first experimental release is for public ticket, document and order references that people need to enter or read back. Generate a code, format it for display, and check it before a database lookup.

What it provides

• Web Crypto generation, a record-type prefix and a standard Bech32m checksum.
• Payload length planning from a lifetime issuance count and collision budget.
• Strict canonical storage keys, documented display normalization and TypeScript namespace brands.
• Zero runtime dependencies, ES modules and included TypeScript declarations.
• A local ticket-lookup demo that distinguishes found, mistyped and valid-but-unknown references.

Install

Requires Node.js 22+ for Node applications. Browser applications need Web Crypto and an ES-module build setup.

npm install --allow-remote=root https://github.com/PerchAnton/refmint/releases/download/v0.1.0-alpha.1/refmint-0.1.0-alpha.1.tgz

npm 12 requires explicit permission for URL dependencies. Pass --allow-remote=root on later npm install / npm ci runs for a project that keeps this URL dependency, too. This does not change global npm settings. Alternatively, download the .tgz asset and run npm install ./refmint-0.1.0-alpha.1.tgz. See npm's URL dependency setting.

The command above was verified with npm 12.2.1 against the published release. The published archive's README shows the original command without this npm 12 flag; the package itself and its checksums are unchanged.

import { createReferences } from 'refmint'

const tickets = createReferences({ prefix: 'ticket' })
const id = tickets.generate()
const printed = tickets.format(id).toUpperCase()
const result = tickets.parse(printed)

if (result.ok) console.log(result.id) // canonical key for an authorized lookup

This is a GitHub-distributed package. It is not yet published to the npm registry; use the archive URL above.

Verification

The release includes the package archive, SHA256SUMS.txt, verification.json and evidence.json. The verification manifest identifies the released commit and CI run.

Released commit: 31abd3f. Release CI.

• 25 core tests, TypeScript checks, 2 HTTP integration tests and 9 browser tests.
• Node 22/24/26; Linux, Windows and macOS; Chromium, Firefox and WebKit.
• 912 prefix/payload length combinations and 1,766 exact count/budget boundary cases.
• 21 standard Bech32m vectors and 4,216 enumerated single-symbol substitutions, plus additional finite mutation cases.

These are software checks, not evidence of a lower human error rate or a speed advantage over other libraries.

Alpha scope

The API and reference format may change. References are public identifiers: the checksum is not authentication or proof that a record exists. Keep a UNIQUE storage constraint, bounded collision retries and authorization for lookups. Preserve a namespace's prefix and payload length with your schema.

Original code is licensed MIT OR Apache-2.0; standard checksum and test-vector attribution is included in the package.

Read the guide · Report a concrete use case or bug