From 8fd2009bef746cc5e79d72cbda3ec25253ab49fe Mon Sep 17 00:00:00 2001 From: Anton Pepperok <101743951+PerchAnton@users.noreply.github.com> Date: Wed, 4 Nov 2026 21:21:46 +0200 Subject: [PATCH 1/2] Clarify beta status and record the exploratory manual-entry pilot --- SECURITY.md | 2 +- docs/evidence/manual-entry-pilot.json | 325 ++++++++++++++++++++++++++ docs/manual-entry-pilot.md | 53 +++++ docs/manual-entry-study.md | 4 + docs/when-not-to-use.md | 16 +- 5 files changed, 393 insertions(+), 7 deletions(-) create mode 100644 docs/evidence/manual-entry-pilot.json create mode 100644 docs/manual-entry-pilot.md diff --git a/SECURITY.md b/SECURITY.md index 456429c..dedb161 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,4 +6,4 @@ Keep a unique database constraint, retry conflicts with a limit, authorize looku Do not attempt to repair an invalid code automatically: a guessed correction can select the wrong record. The parser only normalizes the presentation differences documented in SPEC.md. -For a potential vulnerability, use GitHub's private vulnerability reporting if available, or contact the repository owner through their GitHub profile without disclosing exploit details in a public issue. Ordinary reproducible bugs belong in issues. This alpha has not had an independent security audit. +For a potential vulnerability, use GitHub's private vulnerability reporting if available, or contact the repository owner through their GitHub profile without disclosing exploit details in a public issue. Ordinary reproducible bugs belong in issues. The current beta has not had an independent security audit. See the [beta scope](docs/beta-contract.md) and [stability criteria](docs/stability.md); a beta label is not a security assurance. diff --git a/docs/evidence/manual-entry-pilot.json b/docs/evidence/manual-entry-pilot.json new file mode 100644 index 0000000..dcc03a7 --- /dev/null +++ b/docs/evidence/manual-entry-pilot.json @@ -0,0 +1,325 @@ +{ + "participantCount": 1, + "practiceExcluded": 4, + "measuredTasks": 12, + "eligibleTasks": 12, + "summary": [ + { + "mode": "manual", + "route": "number", + "started": 2, + "eligible": 2, + "excluded": 0, + "succeeded": 2, + "median_success_ms": 8733.5, + "incorrect_queries": 0, + "first_query_trials": 2, + "first_query_failures": 0, + "interrupted": 0, + "deviations": 0, + "timeouts": 0, + "skipped": 0, + "wrong_confirmations": 0 + }, + { + "mode": "manual", + "route": "uuid", + "started": 2, + "eligible": 2, + "excluded": 0, + "succeeded": 2, + "median_success_ms": 33908.5, + "incorrect_queries": 1, + "first_query_trials": 2, + "first_query_failures": 1, + "interrupted": 0, + "deviations": 0, + "timeouts": 0, + "skipped": 0, + "wrong_confirmations": 0 + }, + { + "mode": "manual", + "route": "alias", + "started": 2, + "eligible": 2, + "excluded": 0, + "succeeded": 2, + "median_success_ms": 5126.0, + "incorrect_queries": 0, + "first_query_trials": 2, + "first_query_failures": 0, + "interrupted": 0, + "deviations": 0, + "timeouts": 0, + "skipped": 0, + "wrong_confirmations": 0 + }, + { + "mode": "manual", + "route": "refmint", + "started": 2, + "eligible": 2, + "excluded": 0, + "succeeded": 2, + "median_success_ms": 13057.0, + "incorrect_queries": 0, + "first_query_trials": 2, + "first_query_failures": 0, + "interrupted": 0, + "deviations": 0, + "timeouts": 0, + "skipped": 0, + "wrong_confirmations": 0 + }, + { + "mode": "paste", + "route": "number", + "started": 1, + "eligible": 1, + "excluded": 0, + "succeeded": 1, + "median_success_ms": 4407, + "incorrect_queries": 0, + "first_query_trials": 1, + "first_query_failures": 0, + "interrupted": 0, + "deviations": 0, + "timeouts": 0, + "skipped": 0, + "wrong_confirmations": 0 + }, + { + "mode": "paste", + "route": "uuid", + "started": 1, + "eligible": 1, + "excluded": 0, + "succeeded": 1, + "median_success_ms": 4570, + "incorrect_queries": 0, + "first_query_trials": 1, + "first_query_failures": 0, + "interrupted": 0, + "deviations": 0, + "timeouts": 0, + "skipped": 0, + "wrong_confirmations": 0 + }, + { + "mode": "paste", + "route": "alias", + "started": 1, + "eligible": 1, + "excluded": 0, + "succeeded": 1, + "median_success_ms": 3398, + "incorrect_queries": 0, + "first_query_trials": 1, + "first_query_failures": 0, + "interrupted": 0, + "deviations": 0, + "timeouts": 0, + "skipped": 0, + "wrong_confirmations": 0 + }, + { + "mode": "paste", + "route": "refmint", + "started": 1, + "eligible": 1, + "excluded": 0, + "succeeded": 1, + "median_success_ms": 7047, + "incorrect_queries": 0, + "first_query_trials": 1, + "first_query_failures": 0, + "interrupted": 0, + "deviations": 0, + "timeouts": 0, + "skipped": 0, + "wrong_confirmations": 0 + } + ], + "limitations": [ + "One owner participant after coached practice and clarified instructions.", + "Synthetic visible-card transcription; fixed partially counterbalanced order, no blinding.", + "Two manual tasks and one paste task per format; no inferential statistics.", + "RefMint encodes numeric IDs with alpha.3 invoice/v1; this does not test its UUID codec.", + "First practice number timed out while instructions were unclear; excluded from comparative measurements.", + "No statistically established speedup, human-error reduction or production benefit." + ], + "observation": "Within this pilot, RefMint took longer than number and alias for both modes; manual UUID took longer and had one not-found query. Zero wrong records confirmed; no RefMint checksum error was entered, so human checksum benefit was not measured.", + "date": "2026-11-04", + "refmint": "0.1.0-alpha.3 uint64 / invoice v1", + "rows": [ + { + "route": "alias", + "mode": "manual", + "printed_characters": 5, + "first_query_ms": 4234, + "first_query_correct": true, + "first_correct_lookup_ms": 4234, + "elapsed_ms": 5585, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 0, + "paste_events": 0, + "outcome": "success" + }, + { + "route": "refmint", + "mode": "manual", + "printed_characters": 21, + "first_query_ms": 12098, + "first_query_correct": true, + "first_correct_lookup_ms": 12098, + "elapsed_ms": 14033, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 0, + "paste_events": 0, + "outcome": "success" + }, + { + "route": "number", + "mode": "manual", + "printed_characters": 15, + "first_query_ms": 8550, + "first_query_correct": true, + "first_correct_lookup_ms": 8550, + "elapsed_ms": 9517, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 0, + "paste_events": 0, + "outcome": "success" + }, + { + "route": "uuid", + "mode": "manual", + "printed_characters": 36, + "first_query_ms": 28286, + "first_query_correct": true, + "first_correct_lookup_ms": 28286, + "elapsed_ms": 29233, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 1, + "paste_events": 0, + "outcome": "success" + }, + { + "route": "uuid", + "mode": "manual", + "printed_characters": 36, + "first_query_ms": 30569, + "first_query_correct": false, + "first_correct_lookup_ms": 37284, + "elapsed_ms": 38584, + "incorrect_queries": 1, + "not_found_queries": 1, + "delete_actions": 2, + "paste_events": 0, + "outcome": "success" + }, + { + "route": "number", + "mode": "manual", + "printed_characters": 15, + "first_query_ms": 7164, + "first_query_correct": true, + "first_correct_lookup_ms": 7164, + "elapsed_ms": 7950, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 0, + "paste_events": 0, + "outcome": "success" + }, + { + "route": "refmint", + "mode": "manual", + "printed_characters": 21, + "first_query_ms": 11283, + "first_query_correct": true, + "first_correct_lookup_ms": 11283, + "elapsed_ms": 12081, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 0, + "paste_events": 0, + "outcome": "success" + }, + { + "route": "alias", + "mode": "manual", + "printed_characters": 5, + "first_query_ms": 4084, + "first_query_correct": true, + "first_correct_lookup_ms": 4084, + "elapsed_ms": 4667, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 0, + "paste_events": 0, + "outcome": "success" + }, + { + "route": "refmint", + "mode": "paste", + "printed_characters": 21, + "first_query_ms": 6214, + "first_query_correct": true, + "first_correct_lookup_ms": 6214, + "elapsed_ms": 7047, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 0, + "paste_events": 1, + "outcome": "success" + }, + { + "route": "alias", + "mode": "paste", + "printed_characters": 5, + "first_query_ms": 2781, + "first_query_correct": true, + "first_correct_lookup_ms": 2781, + "elapsed_ms": 3398, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 0, + "paste_events": 1, + "outcome": "success" + }, + { + "route": "uuid", + "mode": "paste", + "printed_characters": 36, + "first_query_ms": 3835, + "first_query_correct": true, + "first_correct_lookup_ms": 3835, + "elapsed_ms": 4570, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 0, + "paste_events": 1, + "outcome": "success" + }, + { + "route": "number", + "mode": "paste", + "printed_characters": 15, + "first_query_ms": 3365, + "first_query_correct": true, + "first_correct_lookup_ms": 3365, + "elapsed_ms": 4407, + "incorrect_queries": 0, + "not_found_queries": 0, + "delete_actions": 0, + "paste_events": 1, + "outcome": "success" + } + ] +} diff --git a/docs/manual-entry-pilot.md b/docs/manual-entry-pilot.md new file mode 100644 index 0000000..bfad6bd --- /dev/null +++ b/docs/manual-entry-pilot.md @@ -0,0 +1,53 @@ +# Manual-entry pilot — 4 November 2026 + +This small pilot **does not establish a practical advantage for RefMint**. One +participant, the project owner, completed two manual tasks and one copy/paste task +per format. RefMint was slower than the existing number and short alias in both +modes. The raw per-task times used for the table are in the +[de-identified numeric record](evidence/manual-entry-pilot.json). + +| Format | Characters shown | Manual: confirmed lookup median | Incorrect manual queries | Paste: confirmed lookup time | Incorrect paste queries | +| --- | ---: | ---: | ---: | ---: | ---: | +| Number | 15 | 8.7 s (2 tasks) | 0 | 4.4 s (1 task) | 0 | +| UUID | 36 | 33.9 s (2 tasks) | 1 | 4.6 s (1 task) | 0 | +| Alias | 5 | 5.1 s (2 tasks) | 0 | 3.4 s (1 task) | 0 | +| RefMint | 21 | 13.1 s (2 tasks) | 0 | 7.0 s (1 task) | 0 | + +All twelve measured tasks were completed without interruption or a protocol +violation. The UUID error was a correctly shaped code with no matching record; +no wrong record was confirmed. Zero RefMint errors in two manual tasks does not +establish fewer mistakes or measure the benefit of its checksum. + +## Method and limits + +The source card stayed visible. The participant entered its code, searched the +same in-memory set of 120 synthetic records and confirmed the record name. Timing +ran from showing the card to confirmation, including reading, input, local lookup +and the confirmation click. These are workflow times, not codec benchmarks. + +The number used `INV-2026-` plus six digits; UUID used its 36-character display; +the alias used five characters. RefMint used alpha.3's uint64 codec, namespace +`invoice`, wire version 1, a three-digit numeric ID and formatted 21-character +output. RefMint did **not** encode the UUID, so this comparison cannot establish +an advantage for UUID-derived references. The routes and record lengths are fixed. + +Four practice tasks were excluded. During the first practice task, unclear wording +led the participant to search by the record's label instead of its full code and +the task timed out. The instructions were clarified before any measured task; +the remaining twelve targets and their order were unchanged. This was a coached +single-person pilot, not a blinded or independent study. + +Manual order: alias / RefMint / number / UUID, then UUID / number / RefMint / alias. +Paste order: RefMint / alias / UUID / number. This partial order reversal does not +remove learning, fatigue, code-length or order effects. Corrections before a query +were not fully observed; deletion actions are not a count of typos. The very small +sample supports description only, without significance tests or population claims. + +## Decision + +Keep an existing number or alias when it serves the task. This pilot provides no +reason to add RefMint to that workflow and no copy/paste speed advantage. Test a +specific unmet need before integration; source ownership, migration, lookup fields +and authorization remain costs even if a later study finds an input advantage. +The [study protocol](manual-entry-study.md), [PDF demo](workflows.md) and existing +synthetic comparisons remain separate evidence with their original scope. diff --git a/docs/manual-entry-study.md b/docs/manual-entry-study.md index c2a5cb0..8fe7986 100644 --- a/docs/manual-entry-study.md +++ b/docs/manual-entry-study.md @@ -1,5 +1,9 @@ # Measure manual-entry value before claiming it +A [first exploratory pilot](manual-entry-pilot.md) is now recorded. Its four practice +tasks are excluded and its twelve measured tasks do not establish a practical +advantage. The protocol below remains the basis for a broader study. + **Status: no human-entry benefit is established by this repository's evidence.** The current [workflow results](workflow-results.md) are synthetic selected cases. Codec throughput, mutation detection and automated browser actions are not human diff --git a/docs/when-not-to-use.md b/docs/when-not-to-use.md index 2a7cc5d..c2c525b 100644 --- a/docs/when-not-to-use.md +++ b/docs/when-not-to-use.md @@ -18,19 +18,23 @@ RefMint codec; working ObjectId search does not by itself call for a new alias. RefMint is worth evaluating when people repeatedly enter a **public** reference and the application benefits from consistent namespaces, display forms and diagnostics. -There is no demonstrated human-entry speedup, reduced support cost, or confirmed need -in Octofleet/Invoice Builder from the current synthetic demo. +The [single-participant pilot](manual-entry-pilot.md) found no advantage over the +existing number or short alias. It does not establish a general human-entry speedup +or fewer mistakes. The synthetic demo does not establish reduced support cost or +a confirmed need in Octofleet/Invoice Builder. ## npm availability and compatibility are separate -The package is **alpha**, even when `npm install refmint` resolves to it. Registry tags -are distribution pointers; they do not certify stability. Pin the reviewed version and -check your organization's policy before adopting it. +The current prerelease is **0.1.0-beta.1**, available through `refmint@beta` or its +exact version. As checked on 4 November 2026, npm `latest` intentionally still points +to **0.1.0-alpha.2**, so plain `npm install refmint` selects that older alpha. +Registry tags are distribution pointers; they do not certify stability. Pin the +reviewed version and check your organization's policy before adopting it. The existing-ID **v1 wire contract is already frozen**: canonical encoding and accepted presentation forms must remain compatible; incompatible formats require a new version and reader. That commitment is described in [format-v1.md](format-v1.md) and checked -with frozen vectors. It does not promise a stable alpha API, operational support, or +with frozen vectors. It does not promise a stable API beyond the [beta contract](beta-contract.md), operational support, or that an application can safely remove old readers. Keep version/kind/namespace choices with your schema and test migrations. npm publication alone adds no compatibility promise. From 771702f202d0ff1fa614b1063aefa92d892b9fc8 Mon Sep 17 00:00:00 2001 From: Anton Pepperok <101743951+PerchAnton@users.noreply.github.com> Date: Thu, 5 Nov 2026 01:11:20 +0200 Subject: [PATCH 2/2] Prepare RefMint beta.2 with the manual lookup pilot --- CHANGELOG.md | 5 +++++ README.md | 14 +++++++------- docs/beta-contract.md | 2 +- docs/evidence.json | 4 ++-- docs/evidence.md | 2 +- docs/when-not-to-use.md | 3 +-- package.json | 2 +- 7 files changed, 18 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ba01aa5..2386f7a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 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. +- Explain the beta API, frozen v1 identifiers and npm distribution tags separately. See [when to use an existing identifier](docs/when-not-to-use.md) and the [pilot results](docs/manual-entry-pilot.md). + ## [0.1.0-beta.1](https://github.com/PerchAnton/refmint/releases/tag/v0.1.0-beta.1) - Define the beta API and unchanged wire-format contract, migration checks and dependency approval boundaries. diff --git a/README.md b/README.md index 7621ed2..4ee6e3c 100644 --- a/README.md +++ b/README.md @@ -6,16 +6,16 @@ generate random references. It works in Node.js 22+ and browsers with Web Crypto [![CI](https://github.com/PerchAnton/refmint/actions/workflows/ci.yml/badge.svg)](https://github.com/PerchAnton/refmint/actions/workflows/ci.yml) ![Runtime dependencies: 0](https://img.shields.io/badge/runtime_dependencies-0-087d5d) -[![npm beta](https://img.shields.io/npm/v/refmint/beta)](https://www.npmjs.com/package/refmint/v/0.1.0-beta.1) +[![npm beta](https://img.shields.io/npm/v/refmint/beta)](https://www.npmjs.com/package/refmint/v/0.1.0-beta.2) ```sh -npm install --save-exact refmint@0.1.0-beta.1 +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.1) · +[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). -**Try an invoice lookup.** The [sample PDF](https://github.com/PerchAnton/refmint/blob/v0.1.0-beta.1/examples/workflows/sample-invoice.pdf) +**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 [lookup demo](docs/workflows.md#try-the-workflow), compare the one-symbol change @@ -56,15 +56,15 @@ If people already find records reliably with your current search, keep it. 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-beta.1/refmint-0.1.0-beta.1.tgz +npm install --allow-remote=root https://github.com/PerchAnton/refmint/releases/download/v0.1.0-beta.2/refmint-0.1.0-beta.2.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-beta.1.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-beta.2.tgz`. [npm's URL dependency setting](https://docs.npmjs.com/cli/v12/commands/npm-install/#allow-remote). The release also includes `SHA256SUMS`, package verification and a registry consumer check. To run the tagged browser demo with Node.js 22+ and pnpm 11.25.0: ```sh -git clone --branch v0.1.0-beta.1 https://github.com/PerchAnton/refmint.git +git clone --branch v0.1.0-beta.2 https://github.com/PerchAnton/refmint.git cd refmint pnpm install --frozen-lockfile --ignore-scripts pnpm check diff --git a/docs/beta-contract.md b/docs/beta-contract.md index 2e367a0..639de7b 100644 --- a/docs/beta-contract.md +++ b/docs/beta-contract.md @@ -25,7 +25,7 @@ database migration, search endpoint or regulated invoice-number replacement occu ## Upgrade checks -Pin `refmint@0.1.0-beta.1` to evaluate this release. Existing alpha.2/alpha.3 callers and identifiers need no +Pin `refmint@0.1.0-beta.2` to evaluate this release. Existing alpha.2/alpha.3 callers and identifiers need no API or data migration. Keep the prior reader during application rollout and rerun the application's native lookup/permission tests on the exact installed archive. diff --git a/docs/evidence.json b/docs/evidence.json index e3acb61..306078a 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-beta.1", + "version": "0.1.0-beta.2", "environment": { "node": "v24.19.0", "platform": "darwin", @@ -113,6 +113,6 @@ "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" + "verified_date": "2026-11-05" } } diff --git a/docs/evidence.md b/docs/evidence.md index be24658..59403d7 100644 --- a/docs/evidence.md +++ b/docs/evidence.md @@ -4,7 +4,7 @@ Run `pnpm check && pnpm evidence` from a clean checkout after installing the loc ## Correctness -For alpha.3 and the beta.1 candidate, the timing/size snapshot is carried forward from alpha.2 because all +For alpha.3, beta.1 and beta.2, 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. diff --git a/docs/when-not-to-use.md b/docs/when-not-to-use.md index c2c525b..c2cbf63 100644 --- a/docs/when-not-to-use.md +++ b/docs/when-not-to-use.md @@ -25,8 +25,7 @@ a confirmed need in Octofleet/Invoice Builder. ## npm availability and compatibility are separate -The current prerelease is **0.1.0-beta.1**, available through `refmint@beta` or its -exact version. As checked on 4 November 2026, npm `latest` intentionally still points +Pin **0.1.0-beta.2** for this release, or select the current beta with `refmint@beta`. As checked on 4 November 2026, npm `latest` intentionally still points to **0.1.0-alpha.2**, so plain `npm install refmint` selects that older alpha. Registry tags are distribution pointers; they do not certify stability. Pin the reviewed version and check your organization's policy before adopting it. diff --git a/package.json b/package.json index ccbaedc..d786813 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "refmint", - "version": "0.1.0-beta.1", + "version": "0.1.0-beta.2", "description": "Generate public references or encode existing IDs with strict input diagnostics and a Bech32m checksum.", "type": "module", "license": "MIT OR Apache-2.0",