diff --git a/CHANGELOG.md b/CHANGELOG.md index e1a7482..8623a67 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## Unreleased + +- Document adoption decisions for existing ObjectId/search workflows, additional + alias and mapping costs, alpha versus wire compatibility, stable-release gates + and a human-entry study protocol. Runtime, formats and published packages are + unchanged; no human-entry advantage is claimed. + ## 0.1.0-alpha.3 — 2026-10-28 Workflow examples and documentation; runtime JavaScript, public APIs and the diff --git a/README.md b/README.md index 38bf9a4..ae48648 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,26 @@ The image is generated from [recorded evidence](docs/evidence.json). See [measur ## Try it +**Already have an ObjectId, invoice number or working search? Keep it unless an +observed manual-entry problem justifies another representation.** RefMint does +not make database lookup faster or authorize access. The built-in existing-ID +codecs support uint64 and UUID, **not MongoDB ObjectId**. A separate random alias +for ObjectId needs a stored field or mapping, a unique index, collision handling, +backfill and lifecycle maintenance. The uint64/UUID codecs can avoid that mapping, +but still add UI, dependency and compatibility work. +[Adoption decision and costs](docs/adoption.md). + +**No human-entry advantage is established.** Selected typo mutations and codec +timings cannot show that people are faster or make fewer errors. Compare the +existing workflow, a simple alias and RefMint with real participants before making +that claim; retain failures and report manual entry separately from copy/paste. +[Measurement protocol](docs/manual-entry-study.md). + +The package remains alpha. Frozen v1 wire encoding is narrower than stable APIs, +support or application readiness. [Criteria for a stable release](docs/stability.md) +are separate from the decision to adopt: a stable release alone would not create +a need for integration. + **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 diff --git a/docs/adoption.md b/docs/adoption.md new file mode 100644 index 0000000..97e283f --- /dev/null +++ b/docs/adoption.md @@ -0,0 +1,48 @@ +# Decide whether another reference is useful + +Start from a support task that is currently difficult, not from a preferred ID +library. If users already paste a link or find the right record using ObjectId, +an invoice number, a name or a hostname, keeping that workflow may be best. +RefMint's checksum can reject some mistyped public references before lookup; it +does not speed up a database query, identify a customer or grant access. + +| Existing workflow | First choice | What RefMint would add | +| --- | --- | --- | +| ObjectId with working search or copied links | Keep ObjectId and the current search | No built-in ObjectId codec; a new alias requires a field/mapping or a separately specified codec | +| A short ticket or invoice number people already use reliably | Keep the number | A longer checked representation, new terminology and training | +| Repeated manual entry of uint64 or UUID values with measured mistakes | Compare current input, a simple alias and RefMint | Reversible checked presentation of the same ID; no additional alias column required | +| Copy/paste or QR scanning | Improve that path first | Checksum validation may still detect some corruption, but faster human entry is unproven | +| Secret invitation or authenticated lookup | Use the application's security design | Nothing: a public reversible checksum is not a credential | + +Do not truncate an ObjectId to uint64, pretend it is a UUID, or silently convert +an unsupported identifier. Such changes lose information or create an undocumented +format. A new codec should follow a demonstrated need and an explicit compatibility +contract. BookCars and Movinin feedback showed no established need beyond their +existing ObjectId workflow; a later stable RefMint release would not invalidate +that decision or constitute permission to resume an integration. + +## Account for the integration cost + +For a random alias stored alongside an existing key, budget for the new field or +mapping table, unique index, collision retries, backfill, deletion/retention rules, +backup/restore and tenant boundaries. Decide whether aliases can ever be reused. +Both a simple alias and a RefMint random reference have these lifecycle costs. + +For the existing uint64/UUID codec, decoding returns the original key, so a mapping +can be avoided. You still own namespace/version selection, input validation, +presentation, error messages, old-reader retention, tests, dependency upgrades and +support documentation. Keep existing URLs, regulated numbers and search available. +Do not store display grouping as a different key from canonical storage. + +All routes must apply the same server-side tenant and permission checks. RefMint +does not prove record existence or prevent a valid reference from selecting the +wrong record. Ask users to confirm record context before sensitive operations. + +## Decide on evidence + +Define the actual problem and acceptable costs before testing. Use +[the manual-entry protocol](manual-entry-study.md) and retain a no-adoption outcome. +A checksum test demonstrates an algorithmic property; it does not demonstrate +less support work, fewer human errors, faster entry or a product's need for RefMint. +No such human-entry advantage is currently established. An opt-in pilot is an +evaluation, not proof of adoption or readiness for all users. diff --git a/docs/manual-entry-study.md b/docs/manual-entry-study.md new file mode 100644 index 0000000..c2a5cb0 --- /dev/null +++ b/docs/manual-entry-study.md @@ -0,0 +1,49 @@ +# Measure manual-entry value before claiming it + +**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 +completion times or error rates. This protocol is a plan, not collected data. + +## Compare the actual task + +Use the same authorized record lookup and confirmation task for three routes: +the current identifier/search workflow, a simple alias, and RefMint. Preserve +existing identifiers and credentials. Use consented, non-sensitive records and +representative ID lengths; do not choose only nearby numbers that favor one route. +If the real workflow uses pasted links or QR codes, include it instead of assuming +that users must type. Keep manual entry and copy/paste results separate. + +Predefine task order, practice, time limit, exclusion rules and the benefit/cost +criteria with the product owner before collecting results. Use different records +for each task and counterbalance route order across participants. State whether +the task is visual transcription, phone dictation or a real support task; do not +generalize one into another. A single-person synthetic pilot is exploratory only. + +## Record outcomes without losing failures + +Measure elapsed time from showing the task to the first query, first correct +lookup and final correct-record confirmation. Record first-query success, rejected +input, not-found, wrong-record lookup/confirmation, skipped tasks, timeouts and +interruptions. Keep practice separate. Do not equate delete-key counts with typo +counts: silent corrections before submission are only partly observed. + +Retain every started trial and all protocol violations. Report participant/task +counts and completion rates next to time summaries. Report successful-trial median +times with their denominators and spread; do not make failures disappear from the +comparison or turn an aborted timer into a successful time. Separate search errors +from interruptions and unauthorized records. Avoid retaining entered private IDs +or raw keystrokes; use anonymous task identifiers and the minimum necessary data. + +## Interpret conservatively + +Compare paired routes within the same task conditions. Explain sample size, order +effects, participant experience, record length and any exclusions. Retain raw +consented observations privately and publish only approved aggregates and methods. +A small pilot can identify usability problems and guide a larger study; it cannot +establish a population-wide advantage or prove need in another application. + +If the current ID or simple alias is faster, easier or sufficient, report that and +keep it. RefMint's own stability and its [integration costs](adoption.md) remain +separate questions. Do not publish invented human timings or label automated QA +as participant observations. diff --git a/docs/stability.md b/docs/stability.md new file mode 100644 index 0000000..cda9a81 --- /dev/null +++ b/docs/stability.md @@ -0,0 +1,38 @@ +# Alpha scope and stability criteria + +RefMint 0.1.0-alpha.3 is a prerelease. npm publication and successful CI do not +change that status. Pin the exact reviewed version for an evaluation and keep the +existing identifier/search path available. There is no stable-release date promised. + +The [existing-ID v1 wire contract](format-v1.md) freezes its layout, canonical +encoding and accepted presentation forms. Incompatible wire changes require a new +version and reader. This is not a promise that the alpha API, error diagnostics, +supported environments or support policy will never change. Applications must +retain the readers needed for references they have already issued. + +## Criteria before a stable release + +- Review and freeze the public API and error behavior; document any migration from + alpha with examples, including rejected input and exact integer handling. +- Verify released-format compatibility against the retained frozen vectors and an + independent implementation; never update old vectors to conceal incompatibility. +- Verify the exact package archive in supported Node/browser environments, including + TypeScript consumers, and record its source identity and checksums. +- Resolve known correctness/security blockers and document remaining limits, + versioning, deprecation and maintenance policies. +- Review consumer feedback and document concrete supported uses, integration cost + and an exit/migration path. Any claim of faster entry or fewer human mistakes + additionally requires human evidence with its method and limitations published. + +These are gates to review, not a statement that all are already met. The current +synthetic tests and release records cover only their named properties and versions. +A stable API could be useful without a speed advantage; conversely, a faster +single-person trial would not establish API stability. + +## Stability is not an adoption requirement by itself + +A stable release can remove a prerelease-policy obstacle. It cannot create a +manual-entry problem where existing IDs and search already work. Adoption remains +a separate product decision, including the dependency and operational costs in +[the decision guide](adoption.md). Do not reopen declined integrations just because +the version label changes. diff --git a/docs/when-not-to-use.md b/docs/when-not-to-use.md index 9f2a31f..2a7cc5d 100644 --- a/docs/when-not-to-use.md +++ b/docs/when-not-to-use.md @@ -2,6 +2,10 @@ Start with the identifier and search workflow users already know. +See the [adoption and cost guide](adoption.md), [stability criteria](stability.md) +and [human comparison protocol](manual-entry-study.md). ObjectId has no built-in +RefMint codec; working ObjectId search does not by itself call for a new alias. + | Situation | Prefer | | --- | --- | | Existing invoice/quote numbers or hostnames are short and lookup works | Keep them; a second identifier creates training and maintenance cost |