From 532530756dd789d1ef8eb12bae34c7097bbc8ca8 Mon Sep 17 00:00:00 2001 From: Anton Pepperok <101743951+PerchAnton@users.noreply.github.com> Date: Wed, 28 Oct 2026 10:01:19 +0200 Subject: [PATCH] Prepare RefMint alpha.3 with PDF and phone lookup evidence --- CHANGELOG.md | 5 ++++- CONTRIBUTING.md | 2 +- README.md | 20 +++++++++++--------- docs/evidence.json | 11 ++++++++--- docs/evidence.md | 7 ++++++- docs/workflows.md | 2 +- package.json | 2 +- 7 files changed, 32 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0bd0b0b..e1a7482 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,9 @@ # Changelog -## Unreleased +## 0.1.0-alpha.3 — 2026-10-28 + +Workflow examples and documentation; runtime JavaScript, public APIs and the +existing-ID v1 wire format are unchanged from alpha.2. - Add a local PDF/phone lookup experiment comparing existing identifiers, a simple alias and RefMint. Record 54 synthetic cases, input lengths and logical lookup calls; diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7a90125..843938d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ The build keeps JSDoc in declarations and removes comments only from emitted JS. 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 a prerelease, keep both `publishConfig.tag` and the explicit publication tag set to `alpha`. -1. Run `pnpm check`, `pnpm test:demo`, `pnpm test:comparison` and `pnpm test:package`; the matching CI must also cover browsers and the supported Node/OS matrix. +1. Run `pnpm check`, `pnpm test:demo`, `pnpm test:comparison`, `pnpm test:workflows` and `pnpm test:package`; the matching CI must also cover browsers, PDF extraction/lookup and the supported Node/OS matrix. 2. Pack with `pnpm pack --pack-destination artifacts`. Record the commit, package SHA-256 and npm SHA-512 integrity. Inspect the file inventory and install this exact archive into an isolated consumer before publication. 3. Authenticate to `https://registry.npmjs.org` with `npm login --auth-type=web`. Enter passwords and second-factor challenges only in npm's login flow. Never commit credentials or put them in an issue/PR. Direct publication requires account 2FA or another authentication method supported by npm; prefer the interactive account flow for the first release. 4. Run `npm publish ./artifacts/refmint-VERSION.tgz --dry-run --ignore-scripts --tag alpha --access public --registry=https://registry.npmjs.org`, substituting the actual version. Inspect the name, version, files and integrity. Then publish the same archive by removing only `--dry-run`. diff --git a/README.md b/README.md index e86a2be..38bf9a4 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,16 @@ [![CI](https://github.com/PerchAnton/refmint/actions/workflows/ci.yml/badge.svg)](https://github.com/PerchAnton/refmint/actions/workflows/ci.yml) ![Status: alpha](https://img.shields.io/badge/status-alpha-d9822b) ![Runtime dependencies: 0](https://img.shields.io/badge/runtime_dependencies-0-087d5d) -[![GitHub prerelease](https://img.shields.io/badge/release-0.1.0--alpha.2-087d5d)](https://github.com/PerchAnton/refmint/releases/tag/v0.1.0-alpha.2) +[![GitHub prerelease](https://img.shields.io/badge/release-0.1.0--alpha.3-087d5d)](https://github.com/PerchAnton/refmint/releases/tag/v0.1.0-alpha.3) [![npm alpha](https://img.shields.io/npm/v/refmint/alpha)](https://www.npmjs.com/package/refmint) RefMint is a small TypeScript library for public ticket, document and order references. It can generate random references or encode existing uint64/UUID values with a namespace and a standard Bech32m checksum. A form can distinguish a mistyped code from a valid reference for a different record type, before querying a database. -**New in alpha.2:** preserve an existing uint64 or UUID with `createReferenceCodec`, inspect invalid input with `diagnose`, and load only the codec with `refmint/codec`. The release includes the optimized implementation and comparison evidence; the tagged source includes the complete comparison form. [Format v1](docs/format-v1.md) · [Comparison and measured trade-offs](docs/comparison.md). +**New in alpha.3:** a PDF/phone lookup experiment comparing existing identifiers, a simple alias and RefMint; 54 selected fixture cases and guidance on when another reference is unnecessary. Runtime JavaScript and the frozen v1 format are unchanged from alpha.2. [Workflow demo](docs/workflows.md) · [When not to use RefMint](docs/when-not-to-use.md). -**Alpha:** APIs may evolve. The existing-ID v1 wire contract is frozen; incompatible formats require a new version. Install the [npm alpha](https://www.npmjs.com/package/refmint), [download the GitHub prerelease](https://github.com/PerchAnton/refmint/releases/tag/v0.1.0-alpha.2), or build from source. The package uses ES modules and includes TypeScript declarations. Node.js 22+ and browsers with Web Crypto are the targets. +**Retained from alpha.2:** preserve an existing uint64 or UUID with `createReferenceCodec`, inspect invalid input with `diagnose`, and load only the codec with `refmint/codec`. The release includes the optimized implementation and comparison evidence; the tagged source includes the complete comparison form. [Format v1](docs/format-v1.md) · [Comparison and measured trade-offs](docs/comparison.md). + +**Alpha:** APIs may evolve. The existing-ID v1 wire contract is frozen; incompatible formats require a new version. Install the [npm alpha](https://www.npmjs.com/package/refmint), [download the GitHub prerelease](https://github.com/PerchAnton/refmint/releases/tag/v0.1.0-alpha.3), or build from source. The package uses ES modules and includes TypeScript declarations. Node.js 22+ and browsers with Web Crypto are the targets. ![Measured checks and the reference lifecycle](docs/assets/evidence.svg) @@ -20,7 +22,7 @@ The image is generated from [recorded evidence](docs/evidence.json). See [measur ## Try it -**Would an extra reference help?** Try the new current-source +**Would an extra reference help?** Try the [PDF/phone lookup experiment](docs/workflows.md): existing number or hostname, five-character alias, and RefMint on the same records. The sample fleet code is 49 printed characters versus an 8-character hostname; the invoice code is 21 versus @@ -33,20 +35,20 @@ Install the current alpha from npm: npm install refmint@alpha ``` -To pin this release, use `npm install --save-exact refmint@0.1.0-alpha.2`. This is a prerelease even when the `latest` registry tag resolves to it; npm availability does not make its API stable. Registry installation does not require an npm account or the URL-dependency flag below. +To pin this release, use `npm install --save-exact refmint@0.1.0-alpha.3`. This is a prerelease even when the `latest` registry tag resolves to it; npm availability does not make its API stable. Registry installation does not require an npm account or the URL-dependency flag below. The GitHub package archive remains available as an alternative: ```sh -npm install --allow-remote=root https://github.com/PerchAnton/refmint/releases/download/v0.1.0-alpha.2/refmint-0.1.0-alpha.2.tgz +npm install --allow-remote=root https://github.com/PerchAnton/refmint/releases/download/v0.1.0-alpha.3/refmint-0.1.0-alpha.3.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; the flag does not change global settings. Alternatively, download the `.tgz` asset and run `npm install ./refmint-0.1.0-alpha.2.tgz`. [npm's URL dependency setting](https://docs.npmjs.com/cli/v12/commands/npm-install/#allow-remote). +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; the flag does not change global settings. Alternatively, download the `.tgz` asset and run `npm install ./refmint-0.1.0-alpha.3.tgz`. [npm's URL dependency setting](https://docs.npmjs.com/cli/v12/commands/npm-install/#allow-remote). The release also includes `SHA256SUMS.txt`, verification metadata and all three measured-evidence reports. To run the local browser demo from the tagged source: ```sh -git clone --branch v0.1.0-alpha.2 https://github.com/PerchAnton/refmint.git +git clone --branch v0.1.0-alpha.3 https://github.com/PerchAnton/refmint.git cd refmint # Install pnpm 11.25.0 if it is not available. npm install -g pnpm@11.25.0 @@ -58,7 +60,7 @@ pnpm demo Open **http://127.0.0.1:4173**. The example runs locally, keeps one sample ticket in memory, and demonstrates three outcomes: found, mistyped and valid-but-unknown. It sends no references to a remote service. -To build your own package archive, run `pnpm pack --pack-destination artifacts`, then install that `.tgz` with your package manager. The npm alpha.2 package updates installation and release documentation; its runtime, TypeScript declarations, package metadata and measured-evidence files are identical to the original GitHub alpha.2 archive. The archives have different checksums because those documentation files differ. +To build your own package archive, run `pnpm pack --pack-destination artifacts`, then install that `.tgz` with your package manager. Alpha.3 uses the same verified package archive for npm and GitHub; registry and release pages confirm publication status. Previous alpha.2 archives remain unchanged. Timing results below were measured for alpha.2 and are retained because runtime hashes are identical; this release makes no new performance claim. ## One namespace, one storage format diff --git a/docs/evidence.json b/docs/evidence.json index 4edb27a..2d8abe3 100644 --- a/docs/evidence.json +++ b/docs/evidence.json @@ -1,6 +1,6 @@ { "generated_at": "2026-10-27T13:21:13.955Z", - "version": "0.1.0-alpha.2", + "version": "0.1.0-alpha.3", "environment": { "node": "v24.19.0", "platform": "darwin", @@ -14,7 +14,7 @@ "checksumLength": 6, "canonicalLength": 27, "expectedCount": 1000000, - "maxCollisionProbability": 1e-9, + "maxCollisionProbability": 1e-09, "collisionUpperBound": 4.2351605011067654e-10, "collisionProbability": 4.235160500209936e-10 }, @@ -109,5 +109,10 @@ "No user study, adoption claim or measured reduction in support time.", "Timing results are machine-specific; generation and parse do different work.", "Collision calculations assume uniform independent sampling; enforce uniqueness in storage." - ] + ], + "measurement_version": "0.1.0-alpha.2", + "carried_forward": { + "reason": "Runtime JavaScript bytes are unchanged; original alpha.2 measurement timestamps, environment and samples are retained.", + "verified_date": "2026-10-28" + } } diff --git a/docs/evidence.md b/docs/evidence.md index 4b6ff79..50379d6 100644 --- a/docs/evidence.md +++ b/docs/evidence.md @@ -4,13 +4,18 @@ Run `pnpm check && pnpm evidence` from a clean checkout after installing the loc ## Correctness +For alpha.3, the timing/size snapshot is carried forward from alpha.2 because all +runtime JavaScript hashes are identical. `measurement_version` identifies the measured +version; `version` identifies the package carrying the evidence. Original timestamps, +environment and samples are retained. This is not a new performance measurement. + Core tests check all 7 valid and 14 invalid generic Bech32m vectors from BIP-350. They compare generated output with a separate implementation (`bech32` 2.0.0) for all payload lengths from 8 through 64 and four prefixes. The planner is checked against exact BigInt pair counts at representative budgets. Type checks demonstrate namespace separation. The boundary suite extends public-API round trips to all 16 prefix lengths × 57 payload lengths = **912 combinations**, including prefixes containing `1`, display normalization, and the raw-input limits of 128/129 characters. Its independent numeric oracle converts each budget's IEEE-754 value into an exact integer ratio. It checks **1,766 distinct count/budget pairs**, including immediately neighboring floating-point values around length transitions, counts up to the largest safe integer, subnormal targets and unattainable budgets. Selected non-string inputs, including an object with throwing access hooks, must be rejected without inspecting or coercing them. The evidence script enumerates 31 alternate symbols at every payload and checksum position for four known references. Their payload lengths are 8, 14, 26 and 64, giving `(14 + 20 + 32 + 70) × 31 = 4,216` substitutions. All must be rejected or the script fails. The core suite additionally checks 3,000 distinct deterministic samples with 2–4 substituted positions (1,000 per count), all single-symbol insertions and deletions in those four bodies, and adjacent swaps of unequal symbols. This is finite test evidence; it is not an exhaustive proof of the standard's error-detection properties. ASCII case folding and valid grouping are deliberately accepted and are not counted as detected errors. Non-ASCII input is rejected before case folding. -Browser tests exercise the actual forms in Chromium, Firefox and WebKit: printed uppercase reference, one typo, unknown valid reference, replacing the sample ticket, a narrow viewport and rejection of a Unicode lookalike. Two additional tests per engine compare the existing-ID forms, both value kinds, all 14 shared cases, raw-input offsets and mobile layout: five tests per engine in total. Hosted results are available in the CI workflow. Local results and hosted results must be identified separately. +Browser tests exercise the actual forms in Chromium, Firefox and WebKit: printed uppercase reference, one typo, unknown valid reference, replacing the sample ticket, a narrow viewport and rejection of a Unicode lookalike. Two tests per engine compare the existing-ID forms, both value kinds, all 14 shared cases, raw-input offsets and mobile layout. Two more cover the PDF/phone workflow form, scope restrictions, another valid code and pasted input: seven tests per engine, 21 in total. Hosted results are available in the CI workflow. Local results and hosted results must be identified separately. `pnpm test:package` seeds a synthetic obsolete module in `dist/`, verifies that the pack build removes it, and checks the archive's exact build-file inventory. It installs the archive offline into a separate consumer with an empty store and checks runtime imports, TypeScript namespace brands, blocked private-module imports, shipped Markdown links and SHA-256 hashes of the measured JavaScript. The package includes the evidence image and documents; builds force LF line endings so the same source produces the same runtime hashes on the tested operating systems. diff --git a/docs/workflows.md b/docs/workflows.md index 045b392..a14f7ed 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -27,7 +27,7 @@ complete valid code. The form supports manual input as well as preset cases. [Demo source](https://github.com/PerchAnton/refmint/tree/main/examples/workflows) · [Sample PDF](https://github.com/PerchAnton/refmint/blob/main/examples/workflows/sample-invoice.pdf) · [All recorded outcomes](workflow-results.md) · [Raw evidence and source hashes](workflows.json). -The example is newer than the alpha.2 source tag and is not part of the npm runtime. +The example is included in the alpha.3 tagged source and is not part of the npm runtime. ## What is compared diff --git a/package.json b/package.json index 35357a7..414acce 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "refmint", - "version": "0.1.0-alpha.2", + "version": "0.1.0-alpha.3", "description": "Generate public references or encode existing IDs with strict input diagnostics and a Bech32m checksum.", "type": "module", "license": "MIT OR Apache-2.0",