@anizoptera/uuid-slug 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/README.md +315 -1057
  2. package/dist/alphabet.d.ts +1 -1
  3. package/dist/alphabet.js +1 -1
  4. package/dist/base64url-name.d.ts +1 -1
  5. package/dist/base64url-name.js +1 -1
  6. package/dist/errors.d.ts +1 -1
  7. package/dist/errors.js +1 -1
  8. package/dist/feistel.js +1 -1
  9. package/dist/generation-options.js +1 -1
  10. package/dist/index.d.ts +1 -1
  11. package/dist/index.js +1 -1
  12. package/dist/instant.js +1 -1
  13. package/dist/mask-handle.d.ts +1 -1
  14. package/dist/mask-handle.js +1 -1
  15. package/dist/mask.d.ts +1 -1
  16. package/dist/mask.js +1 -1
  17. package/dist/masking-codec-protocol.js +1 -1
  18. package/dist/masking-codec-types.d.ts +1 -1
  19. package/dist/masking-codec.d.ts +1 -1
  20. package/dist/masking-codec.js +1 -1
  21. package/dist/migration.js +1 -1
  22. package/dist/node/runtime.js +1 -1
  23. package/dist/payload.d.ts +1 -1
  24. package/dist/payload.js +1 -1
  25. package/dist/runtime/pool.js +1 -1
  26. package/dist/runtime/portable.js +1 -1
  27. package/dist/sentinel.js +1 -1
  28. package/dist/siphash.js +1 -1
  29. package/dist/slug.d.ts +1 -1
  30. package/dist/slug.js +1 -1
  31. package/dist/timestamp.d.ts +1 -1
  32. package/dist/timestamp.js +1 -1
  33. package/dist/types.d.ts +1 -1
  34. package/dist/types.js +1 -1
  35. package/dist/uuid-value-protocol.js +1 -1
  36. package/dist/uuid-value.d.ts +1 -1
  37. package/dist/uuid-value.js +1 -1
  38. package/dist/uuid.d.ts +1 -1
  39. package/dist/uuid.js +1 -1
  40. package/dist/v4-slug.d.ts +1 -1
  41. package/dist/v4-slug.js +1 -1
  42. package/dist/v4.d.ts +1 -1
  43. package/dist/v4.js +1 -1
  44. package/dist/v7-bounds.d.ts +1 -1
  45. package/dist/v7-bounds.js +1 -1
  46. package/dist/v7-generator-input.js +1 -1
  47. package/dist/v7-generator.d.ts +1 -1
  48. package/dist/v7-generator.js +1 -1
  49. package/dist/v7-keyless.d.ts +1 -1
  50. package/dist/v7-keyless.js +1 -1
  51. package/dist/v7-payload.js +1 -1
  52. package/dist/v7-slug.d.ts +1 -1
  53. package/dist/v7-slug.js +1 -1
  54. package/dist/v7-timestamp.js +1 -1
  55. package/dist/v7-value-options.js +1 -1
  56. package/dist/v7-value.d.ts +1 -1
  57. package/dist/v7-value.js +1 -1
  58. package/dist/v7.js +1 -1
  59. package/package.json +5 -3
  60. package/src/alphabet.ts +2 -2
  61. package/src/errors.ts +3 -3
  62. package/src/feistel.ts +1 -1
  63. package/src/generation-options.ts +1 -1
  64. package/src/masking-codec-protocol.ts +1 -1
  65. package/src/masking-codec.ts +1 -1
  66. package/src/payload.ts +2 -2
  67. package/src/runtime/bun.ts +1 -1
  68. package/src/runtime/node.ts +2 -2
  69. package/src/runtime/pool.ts +1 -1
  70. package/src/runtime/portable.ts +1 -1
  71. package/src/slug.ts +6 -6
  72. package/src/uuid-value-protocol.ts +1 -1
  73. package/src/uuid-value.ts +1 -1
  74. package/src/uuid.ts +8 -8
  75. package/src/v4.ts +2 -2
  76. package/src/v7-bounds.ts +3 -3
  77. package/src/v7-generator-input.ts +2 -2
  78. package/src/v7-keyless.ts +6 -6
  79. package/src/v7-payload.ts +1 -1
  80. package/src/v7-slug.ts +1 -1
  81. package/src/v7.ts +1 -1
@@ -555,7 +555,7 @@ function buildUuidSlugCodec(
555
555
  // function past the size JavaScriptCore inlines into a small caller, which costs Bun sentinel
556
556
  // reads a few nanoseconds; moving it into a helper cost more because Bun did not inline the
557
557
  // helper either. Recheck `sentinel.base32.decode` on Bun when this function changes
558
- // (bench/PERFORMANCE.md).
558
+ // (bench/decisions.md).
559
559
  if (uuid.length === 36) {
560
560
  if (selectedCase === UUID_TEXT_LOWERCASE && isUuidString(uuid))
561
561
  return uuid as UuidStringFor<Case>;
package/src/payload.ts CHANGED
@@ -178,7 +178,7 @@ export function ownedUuidV7BytesToMaskedSlug(
178
178
  // Raw sentinels have zero outer bits. Only that tail can collide with retained base64 reads;
179
179
  // other writes need neither a second encoding nor a lookup for a collision that cannot occur.
180
180
  // Skipping the lookup matters: on V8 it hashed and flattened every base64url slug
181
- // (bench/PERFORMANCE.md).
181
+ // (bench/decisions.md).
182
182
  const canonical =
183
183
  alphabet === BASE64URL_NAME || (tail === 0 && reserved?.size)
184
184
  ? encode(raw, BASE64URL, tail, OUTER_TAG_BITS)
@@ -203,7 +203,7 @@ export const noMaskedSlugMatch = /* @__NO_SIDE_EFFECTS__ */ (): UuidSlugError =>
203
203
  * Decode a masked slug and return `undefined` when every mask's check rejects it. Source-specific
204
204
  * readers report that miss with `noMaskedSlugMatch`; a codec reading an ambiguous 22-character slug
205
205
  * takes the plain reading instead, so the miss builds no error. Readers call this directly: a wrapper
206
- * that built the error slowed the masked-slug text reader on Node (bench/PERFORMANCE.md).
206
+ * that built the error slowed the masked-slug text reader on Node (bench/decisions.md).
207
207
  */
208
208
  export function unmaskSlug(
209
209
  slug: string,
@@ -26,7 +26,7 @@ else if (globalThis.crypto.randomUUID)
26
26
 
27
27
  // Native UUIDv7 can advance logical time during counter overflow; defaults do not forbid that.
28
28
  // Select it only when complete-call gains preserve configured-call speed and resource efficiency.
29
- // Explicit generators keep their clock controls; bench/PERFORMANCE.md owns drift and cost evidence.
29
+ // Explicit generators keep their clock controls; bench/decisions.md owns drift and cost evidence.
30
30
  const nativeUuidV7 = (globalThis as { Bun?: { randomUUIDv7?: (encoding?: "base64url") => string } })
31
31
  .Bun?.randomUUIDv7;
32
32
  if (typeof nativeUuidV7 === "function") {
@@ -35,7 +35,7 @@ if (nodeOptions?.includes("jitless")) {
35
35
 
36
36
  /**
37
37
  * Node's native UTF-8 encoder materially reduces string-seed construction; the portable adapter
38
- * remains the compatibility boundary. bench/PERFORMANCE.md owns the measured runtime scope.
38
+ * remains the compatibility boundary. bench/decisions.md owns the measured runtime scope.
39
39
  */
40
40
  export const encodeUtf8 = /* @__NO_SIDE_EFFECTS__ */ (text: string): Uint8Array =>
41
41
  Buffer.from(text, "utf8");
@@ -53,7 +53,7 @@ const nodeRuntime: Runtime = {
53
53
  }),
54
54
  // Pooled formatting wins with the JIT; native text wins without it. Missing native capability
55
55
  // stays undefined so the generator uses its tested portable fallback. Remeasure both modes
56
- // after Node changes; bench/PERFORMANCE.md owns the compared calls and resource limits.
56
+ // after Node changes; bench/decisions.md owns the compared calls and resource limits.
57
57
  ...(jitless ? { jitless: true, uuidV4: crypto.randomUUID } : {}),
58
58
  };
59
59
 
@@ -55,7 +55,7 @@ export function pooledFill(
55
55
  // Continuation draws need four bytes. Fixed stores avoid their loop without another view
56
56
  // or retained buffer. Owned draws use four-byte blocks, reusing each source offset rather
57
57
  // than repeating its arithmetic. Blocks keep the body smaller than fully expanded stores;
58
- // other lengths keep the indexed loop. Complete-call comparisons in bench/PERFORMANCE.md
58
+ // other lengths keep the indexed loop. Complete-call comparisons in bench/decisions.md
59
59
  // decide this shape, not copy-only timing. Remeasure if draw widths
60
60
  // or the runtime's typed-array handling change.
61
61
  if (length === 4) {
@@ -29,7 +29,7 @@ const runtimeCapabilities: Runtime = {
29
29
  // WebKit's fixed formatter slowed unrelated successful calls in mixed comparisons. Native hex
30
30
  // did not reproduce a repeated loss while other engines retain their fixed writers. This identity
31
31
  // selects cost only; absent hex support still uses the portable writer. Remeasure after browser
32
- // changes (bench/PERFORMANCE.md); the shared ASCII decoder also slowed slug output.
32
+ // changes (bench/decisions.md); the shared ASCII decoder also slowed slug output.
33
33
  if (
34
34
  typeof navigator !== "undefined" &&
35
35
  navigator.vendor === "Apple Computer, Inc." &&
package/src/slug.ts CHANGED
@@ -245,7 +245,7 @@ export function uuidBytesToPlainSlug(
245
245
  if (selectedAlphabet === BASE32HEX_NAME) return encode(bytes, BASE32HEX) as PlainUuidSlug;
246
246
  // Native encoding owns this exact plain-payload job. Offset windows and non-array forms retain
247
247
  // general conversion; masked tails never enter here. Keep base32 controls in the comparison
248
- // when changing this dispatch (bench/PERFORMANCE.md).
248
+ // when changing this dispatch (bench/decisions.md).
249
249
  if (selectedAlphabet === BASE64URL_NAME) {
250
250
  if (nativePlainUuidBase64) {
251
251
  try {
@@ -361,7 +361,7 @@ export function uuidStringToPlainSlug(
361
361
  // Resolve caller selectors before scratch is live, then parse and encode without callbacks.
362
362
  // Separate text-to-slug
363
363
  // writers read hex pairs and concatenated characters, and were slower on every runtime
364
- // (bench/PERFORMANCE.md). Reassess scratch ownership if encoding adds caller-controlled work.
364
+ // (bench/decisions.md). Reassess scratch ownership if encoding adds caller-controlled work.
365
365
  const bytes = uuidStringToBytes(uuidText, textSlugScratch);
366
366
  if (bytes instanceof Error) return bytes;
367
367
  return encode(bytes, alpha) as PlainUuidSlug;
@@ -549,7 +549,7 @@ export function uuidToString(
549
549
  textCase = caseAfterOffset;
550
550
  } else textCase = byteOffsetOrCase;
551
551
  // Canonical lowercase text is already the default output, so it is returned without decoding.
552
- // An inline `typeof` guard ahead of the helper slowed Node mixed-case text (bench/PERFORMANCE.md).
552
+ // An inline `typeof` guard ahead of the helper slowed Node mixed-case text (bench/decisions.md).
553
553
  if (textCase === UUID_TEXT_LOWERCASE && isUuidString(uuid)) return uuid;
554
554
  const localBytes = exactLocalUuidBytes(uuid);
555
555
  if (localBytes) {
@@ -570,7 +570,7 @@ export function uuidToString(
570
570
  }
571
571
  }
572
572
  // Only text leaves this call. Reuse private scratch instead of an owned decode array;
573
- // public caller-buffer decoding adds validation and copying (bench/PERFORMANCE.md).
573
+ // public caller-buffer decoding adds validation and copying (bench/decisions.md).
574
574
  const alpha = typeof input === "string" ? SLUG_ALPHABET_BY_LENGTH[input.length] : undefined;
575
575
  const decoded =
576
576
  typeof input === "string"
@@ -671,7 +671,7 @@ function fixedCanonicalUuidV7UnixMs(text: string): number {
671
671
  // low word so timestamps above its sign bit preserve all 48 bits. Only validated canonical text
672
672
  // reaches this helper; compact text retains its contiguous parse. Table reads slightly favor
673
673
  // Bun but lose on Node in the source screen; remeasure complete calls after parser or engine
674
- // changes (bench/PERFORMANCE.md).
674
+ // changes (bench/decisions.md).
675
675
  const high =
676
676
  (validatedHexNibble(text, 0) << 12) |
677
677
  (validatedHexNibble(text, 1) << 8) |
@@ -696,7 +696,7 @@ function parsedCanonicalUuidV7UnixMs(text: string): number {
696
696
  }
697
697
 
698
698
  // Reuse the runtime's settled JIT selection; no flag parsing or table construction belongs here.
699
- // Recheck both complete calls after engine changes against bench/PERFORMANCE.md.
699
+ // Recheck both complete calls after engine changes against bench/decisions.md.
700
700
  const canonicalUuidV7UnixMsUnchecked = runtime.jitless
701
701
  ? parsedCanonicalUuidV7UnixMs
702
702
  : fixedCanonicalUuidV7UnixMs;
@@ -11,7 +11,7 @@ export const UUID_VALUE_CONTEXT = Symbol.for("@anizoptera/uuid-slug.uuid-value-c
11
11
  * importing the value class, and private fields keep the state off the frozen value's own properties.
12
12
  *
13
13
  * A module `WeakMap` keyed by value is the rejected alternative: registering each value cost more
14
- * than the rest of value creation (bench/PERFORMANCE.md). Remeasure if engines change how they
14
+ * than the rest of value creation (bench/decisions.md). Remeasure if engines change how they
15
15
  * store private fields or weak collections.
16
16
  */
17
17
  export class LocalUuidValue {
package/src/uuid-value.ts CHANGED
@@ -74,7 +74,7 @@ class ParsedUuidValue<
74
74
  {
75
75
  // Private bytes are already a complete immutable UUID; public conversion would validate them
76
76
  // again. Resolve caller selectors, then use the same writers directly without caching spellings.
77
- // Revisit if private storage becomes mutable or borrowed; measurements live in bench/PERFORMANCE.md.
77
+ // Revisit if private storage becomes mutable or borrowed; measurements live in bench/decisions.md.
78
78
  get version(): Version {
79
79
  return uuidVersion(LocalUuidValue.ownBytes(this), 0) as Version;
80
80
  }
package/src/uuid.ts CHANGED
@@ -87,7 +87,7 @@ for (let i = 0; i < 16; i += 1) {
87
87
  HEX_NIBBLES[UPPERCASE_HEX.charCodeAt(i)] = i;
88
88
  }
89
89
  // Bun's Latin-1 writer and the fixed writer share lazily built case tables; native hex needs none.
90
- // bench/PERFORMANCE.md owns the comparison and recheck conditions. Tables are built on first use.
90
+ // bench/decisions.md owns the comparison and recheck conditions. Tables are built on first use.
91
91
  let uuidTextScratch: Latin1Scratch | undefined;
92
92
  let lowercaseHexCodes: Uint8Array | undefined;
93
93
  let uppercaseHexCodes: Uint8Array | undefined;
@@ -123,7 +123,7 @@ function formatUuidBytesLatin1(
123
123
  : (lowercaseHexCodes ??= hexCodes(HEX));
124
124
  const text = scratch.bytes;
125
125
  // Fixed positions remove the loop and offset-table reads on Bun's selected writer.
126
- // The indexed loop loses repeated complete text calls; bench/PERFORMANCE.md owns the evidence.
126
+ // The indexed loop loses repeated complete text calls; bench/decisions.md owns the evidence.
127
127
  // Keep native string construction and shared storage; remeasure after JSC or writer changes.
128
128
  const code0 = (bytes[offset + 0] as number) * 2;
129
129
  text[0] = codes[code0] as number;
@@ -267,7 +267,7 @@ export function uuidStringToBytes(
267
267
 
268
268
  // One pass decodes and validates: OR-ing every character code and every decoded pair exposes a
269
269
  // non-ASCII or non-hex character after the loop. Validating before a second decoding pass cost
270
- // about twice as much on Node and three times on Bun (bench/PERFORMANCE.md). Only failing text
270
+ // about twice as much on Node and three times on Bun (bench/decisions.md). Only failing text
271
271
  // pays a second scan, which locates the offset for the message.
272
272
  const target = out === undefined ? new Uint8Array(16) : decodedUuidScratch;
273
273
  let codes = 0;
@@ -286,7 +286,7 @@ export function uuidStringToBytes(
286
286
  if (codes < 128 && pairs < 256) {
287
287
  if (out === undefined) return target;
288
288
  // A byte loop rather than `set`: the native call made Bun text-to-slug conversion slower
289
- // (bench/PERFORMANCE.md).
289
+ // (bench/decisions.md).
290
290
  for (let byteIndex = 0; byteIndex < 16; byteIndex += 1)
291
291
  out[offset + byteIndex] = target[byteIndex] as number;
292
292
  return out;
@@ -374,7 +374,7 @@ export function formatUuidBytesUnchecked<Case extends UuidTextCase = typeof UUID
374
374
  // Bun retains its Latin-1 writer. A fixed argument list makes one flat string without
375
375
  // temporary bytes, intermediate hex or concatenation. WebKit selects native hex to avoid
376
376
  // repeated mixed-workload losses; remeasure both paths after engine changes
377
- // (bench/PERFORMANCE.md). Keep case selection and fixed writing together to avoid another call.
377
+ // (bench/decisions.md). Keep case selection and fixed writing together to avoid another call.
378
378
  if (createLatin1Scratch)
379
379
  return formatUuidBytesLatin1(
380
380
  createLatin1Scratch,
@@ -484,10 +484,10 @@ export function isUuidText(value: unknown): value is UuidText {
484
484
  }
485
485
 
486
486
  // Canonical guards stay regular expressions: a character loop measured slower on Node and Bun
487
- // (bench/PERFORMANCE.md, Canonical UUID text).
487
+ // (bench/decisions.md, Canonical UUID text).
488
488
  // Pair repetition improves canonical calls, but slows Bun's successful base32 normalization.
489
489
  // Reuse its existing Latin-1 selection once; neither pattern needs a builder or per-call dispatch.
490
- // Remeasure normalization if this capability moves to another adapter (bench/PERFORMANCE.md).
490
+ // Remeasure normalization if this capability moves to another adapter (bench/decisions.md).
491
491
  const UUID_RE = createLatin1Scratch
492
492
  ? /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
493
493
  : /^(?:[0-9a-f][0-9a-f]){4}-(?:[0-9a-f][0-9a-f]){2}-(?:[0-9a-f][0-9a-f]){2}-(?:[0-9a-f][0-9a-f]){2}-(?:[0-9a-f][0-9a-f]){6}$/;
@@ -517,7 +517,7 @@ export function isUuidV4Text(value: unknown): value is UuidV4Text {
517
517
  export function isUuidV7Text(value: unknown): value is UuidV7Text {
518
518
  // Canonical text uses the same syntax with either case, avoiding the full digit loop before
519
519
  // timestamp parsing. Other spellings retain their existing checks; remeasure after engine or
520
- // accepted-syntax changes (bench/PERFORMANCE.md).
520
+ // accepted-syntax changes (bench/decisions.md).
521
521
  if (typeof value === "string" && value.length === UUID_LENGTH) return UUID_V7_TEXT_RE.test(value);
522
522
  if (!isUuidText(value)) return false;
523
523
  const textStart = uuidTextStart(value);
package/src/v4.ts CHANGED
@@ -127,7 +127,7 @@ export function generatePortableUuidV4<Case extends UuidTextCase = typeof UUID_T
127
127
  /**
128
128
  * Fill the module scratch with UUIDv4 bytes for a writer that reads them before its next draw. Text
129
129
  * and slug writers never expose the scratch, so they skip a new array and the public converters'
130
- * input checks, which cost about a third of Node's portable text call (bench/PERFORMANCE.md).
130
+ * input checks, which cost about a third of Node's portable text call (bench/decisions.md).
131
131
  * Encoding cannot draw entropy, so the scratch cannot change between this return and the read.
132
132
  */
133
133
  export function drawUuidV4Scratch(): Uint8Array | UuidSlugError {
@@ -172,7 +172,7 @@ export function generateUuidV4<Case extends UuidTextCase = typeof UUID_TEXT_LOWE
172
172
  // Trust proper native output directly: validation and identity tracking impose guarantees
173
173
  // beyond the default native baseline. Configured entropy still validates at its caller seam.
174
174
  // Remeasure each output form if case normalization, host APIs or engine inlining
175
- // changes; bench/PERFORMANCE.md owns the evidence.
175
+ // changes; bench/decisions.md owns the evidence.
176
176
  const native = runtime.uuidV4;
177
177
  if (!native) return generatedOrThrow(generatePortableUuidV4(textCase));
178
178
  let uuid: string | UuidSlugError;
package/src/v7-bounds.ts CHANGED
@@ -70,7 +70,7 @@ function fixedTextEndpoint<Case extends UuidTextCase>(
70
70
  ): UuidV7StringFor<Case> {
71
71
  // Fixed character arguments reduce consumed bounds costs on V8 with the JIT. Byte pairs remain
72
72
  // faster on Bun and JITless Node; selection is outside per-ID calls. Remeasure engine changes
73
- // against bench/PERFORMANCE.md, including both endpoint reads and lazy table construction.
73
+ // against bench/decisions.md, including both endpoint reads and lazy table construction.
74
74
  const hex = (hexCodes ??= Uint8Array.from("0123456789abcdef", (digit) => digit.charCodeAt(0)));
75
75
  // Validated timestamps have 48 bits; splitting avoids truncating their upper 16 bits.
76
76
  const high = Math.floor(unixMs / 0x1_0000_0000);
@@ -102,7 +102,7 @@ function textEndpoint<Case extends UuidTextCase>(
102
102
  ): UuidV7StringFor<Case> {
103
103
  // Byte pairs avoid radix formatting and beat fixed character arguments on Bun and JITless Node.
104
104
  // Build the table on first use so imports that never request bounds pay no table construction.
105
- // Remeasure radix formatting and fixed arguments after engine changes (bench/PERFORMANCE.md).
105
+ // Remeasure radix formatting and fixed arguments after engine changes (bench/decisions.md).
106
106
  const hex = (hexBytes ??= Array.from({ length: 256 }, (_, byte) =>
107
107
  byte.toString(16).padStart(2, "0"),
108
108
  ));
@@ -163,7 +163,7 @@ export function uuidV7StringBounds(
163
163
  const end = intervalEnd(startUnixMs, endUnixMs);
164
164
  if (typeof end !== "number") return end;
165
165
  // Direct formatting avoids two temporary byte arrays. Keep the byte writer independent unless
166
- // repeated public-route measurements reverse this result; bench/PERFORMANCE.md owns that trigger.
166
+ // repeated public-route measurements reverse this result; bench/decisions.md owns that trigger.
167
167
  return {
168
168
  startInclusive: selectedTextEndpoint(startUnixMs, false, textCase),
169
169
  endInclusive: selectedTextEndpoint(end, true, textCase),
@@ -48,7 +48,7 @@ class ReturnObject {
48
48
  *
49
49
  * Structural validation allocated a validated object and rescanned the layout keys on every call
50
50
  * that passed `generator`, and the untrusted-generator call then needed a scratch buffer, byte
51
- * validation, an `at` check, and a copy (bench/PERFORMANCE.md). The stamp adds a private field
51
+ * validation, an `at` check, and a copy (bench/decisions.md). The stamp adds a private field
52
52
  * instead of a class prototype, so the public object stays plain. A module `WeakMap` is the rejected
53
53
  * alternative: registration made default generator creation 1.6 times slower. Remeasure if engines
54
54
  * change how they store private fields or weak collections.
@@ -106,7 +106,7 @@ export function readUuidV7Generator(
106
106
  *
107
107
  * The generator receives the result buffer and may keep a reference to it, so a result the caller
108
108
  * keeps is a copy. Pass `borrowed` only when the package consumes the bytes before returning and
109
- * never returns them: text, slug, and masked-slug writers skip that copy (bench/PERFORMANCE.md).
109
+ * never returns them: text, slug, and masked-slug writers skip that copy (bench/decisions.md).
110
110
  */
111
111
  export function generateUuidV7BytesWithGenerator(
112
112
  generator: ValidatedUuidV7Generator,
package/src/v7-keyless.ts CHANGED
@@ -48,7 +48,7 @@ const UUID_V7_BYTE_OPTIONS = {
48
48
  /**
49
49
  * Text and bytes keep independent lazy state so neither output form pays cross-form coordination.
50
50
  * Native defaults avoid constructing this generator. Explicit time, configured generators and
51
- * native failure still need portable state; bench/PERFORMANCE.md owns the selection evidence.
51
+ * native failure still need portable state; bench/decisions.md owns the selection evidence.
52
52
  */
53
53
  let textGenerator: PortableUuidV7Generator | undefined;
54
54
  let byteGenerator: PortableUuidV7Generator | undefined;
@@ -69,7 +69,7 @@ const keylessTextBytes = new Uint8Array(16);
69
69
 
70
70
  /**
71
71
  * Draw with options this module already read. Rebuilding an options object for the generator's
72
- * public method allocated it and read every option a second time (bench/PERFORMANCE.md).
72
+ * public method allocated it and read every option a second time (bench/decisions.md).
73
73
  */
74
74
  function drawFromReadOptions(
75
75
  generator: PortableUuidV7Generator,
@@ -101,10 +101,10 @@ export const uuidV7BytesAt = (at: unknown): Uint8Array | UuidSlugError => drawAt
101
101
  * Slug and pair writers encode their bytes before returning and draw nothing in between, so they
102
102
  * borrow the generator's private text scratch instead of validating a second module buffer as
103
103
  * caller output. Text keeps cached generator delegation; replacing it with a direct module
104
- * formatter has not earned its cost on the primary calls (bench/PERFORMANCE.md).
104
+ * formatter has not earned its cost on the primary calls (bench/decisions.md).
105
105
  * Keep configured output validation and the generator's reentrancy guard; a borrowed buffer
106
106
  * must never escape or survive another draw. Remeasure complete calls when either writer changes
107
- * (bench/PERFORMANCE.md), rather than assuming fewer checks improve every runtime.
107
+ * (bench/decisions.md), rather than assuming fewer checks improve every runtime.
108
108
  */
109
109
  export const currentUuidV7Scratch = (): Uint8Array | UuidSlugError =>
110
110
  v7Text().drawUuidV7Bytes(undefined, keylessTextBytes);
@@ -123,7 +123,7 @@ const portableUuidV7Text = (textCase: UuidTextCase): string | UuidSlugError =>
123
123
 
124
124
  // Trust proper native results directly; validation and identity tracking add guarantees beyond
125
125
  // the default native baseline. Keep exception fallback separate from configured calls, and
126
- // remeasure complete calls when host capabilities change; bench/PERFORMANCE.md owns evidence.
126
+ // remeasure complete calls when host capabilities change; bench/decisions.md owns evidence.
127
127
  function generateNativeDefaultUuidV7<Case extends UuidTextCase>(
128
128
  selectedCase: Case,
129
129
  ): UuidV7StringFor<Case> | UuidSlugError {
@@ -281,7 +281,7 @@ export const currentUuidV7Bytes = (): UuidV7Bytes | UuidSlugError =>
281
281
  // Independent draws remove unrequested sequence work from owned defaults. Keep JITless on its
282
282
  // measured generator path; configured calls and immutable values retain their declared layout.
283
283
  // Remeasure complete calls if entropy, timestamp writing or runtime selection changes;
284
- // bench/PERFORMANCE.md owns runtime comparisons rather than this selection comment.
284
+ // bench/decisions.md owns runtime comparisons rather than this selection comment.
285
285
  const generateSelectedDefaultUuidV7Bytes = runtime.jitless
286
286
  ? currentUuidV7Bytes
287
287
  : generateDefaultOwnedUuidV7Bytes;
package/src/v7-payload.ts CHANGED
@@ -68,7 +68,7 @@ export function readUuidV7PayloadLayout(
68
68
  * Join `rand_a` and `rand_b`; version and variant bits are separators, not payload.
69
69
  *
70
70
  * The upper 34 and lower 40 payload bits are assembled as exact numbers and joined once, because a
71
- * BigInt conversion and shift per byte cost more than twice as much (bench/PERFORMANCE.md).
71
+ * BigInt conversion and shift per byte cost more than twice as much (bench/decisions.md).
72
72
  */
73
73
  export function uuidV7PayloadFromBytesUnchecked(bytes: Uint8Array, offset: number): bigint {
74
74
  const upper =
package/src/v7-slug.ts CHANGED
@@ -56,7 +56,7 @@ const portableUuidV7Slug = (): string | UuidSlugError => {
56
56
 
57
57
  // Direct native output removes clock, entropy, byte writing and encoding from ordinary calls.
58
58
  // Configured calls and base32hex remain portable. Remeasure complete calls and resources if this
59
- // boundary changes; bench/PERFORMANCE.md owns evidence. Trust proper native results directly;
59
+ // boundary changes; bench/decisions.md owns evidence. Trust proper native results directly;
60
60
  // result validation and identity tracking would impose stronger default guarantees.
61
61
  function nativeUuidV7Slug(): string | UuidSlugError {
62
62
  const native = runtime.uuidV7Slug;
package/src/v7.ts CHANGED
@@ -105,7 +105,7 @@ function writeTimestampLoop(bytes: Uint8Array, ms: number, offset: number) {
105
105
  }
106
106
 
107
107
  // Measured Bun favors the loop while Node and Chromium favor fixed writes; select once so generation
108
- // pays no per-call branch. bench/PERFORMANCE.md owns the measurements and replacement condition.
108
+ // pays no per-call branch. bench/decisions.md owns the measurements and replacement condition.
109
109
  const writeTimestamp = (globalThis as { Bun?: object }).Bun
110
110
  ? writeTimestampLoop
111
111
  : writeTimestampWords;