uuid 14.0.1: Supply a 16-byte Uint8Array generator to v4 options.rng for deterministic entropy and decode buffer outputs with stringify

# Notes

- **search_known_solution result**: Found existing sample `sha256:480c1cd73d2b874c0975ff73c562ac5427aa029495a4c7609b4d9d87ab41fd00` ("Import uuid v9+ without the removed default export breaking the build").
- **What a model would write instead**: `v4({ rng: () => Math.random() })` expecting a standard `0..1` random float generator, and `const str = v4(options, buf, offset)` expecting `str` to be a formatted UUID string.
- **How the wrong version fails**: Fails loudly at runtime with `TypeError: Cannot create property '6' on number` when indexing the returned scalar, and passing `buf` mutates and returns the `Uint8Array` instance (`=== buf`) rather than returning a string.

{"case":{"caseId":"case:sha256:bf949bd6dc608b3ea1146b3acf361e045ace5a11cb488a7b09b786a542345ab2","contract":["assert v4({ rng: () =\u003e Math.random() }) throws TypeError when given a scalar random float callback","assert v4({ rng: byteSupplier }) returns a valid v4 UUID string with RFC4122 version and variant bits applied","assert v4(options, buf, offset) writes raw bytes directly into buf and returns the buffer reference instead of a string","assert stringify(buf, offset) decodes the canonical UUID string from the binary buffer","assert v4(options, buf, offset) throws RangeError when target buffer is smaller than 16 bytes"],"goal":"Supply a 16-byte Uint8Array generator to v4 options.rng for deterministic entropy and decode buffer outputs with stringify","kind":"HOW","packages":["pkg:npm/uuid@14.0.1"],"schemaVersion":1,"symbols":["v4","stringify","validate","version"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/uuid@14.0.1"],"schemaVersion":1,"symbols":["v4","stringify","validate","version"],"verifierAdapter":"node-typescript@1"}

{
  "name": "csx-sample-uuid-config",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "csx-sample-uuid-config",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "uuid": "14.0.1"
      }
    },
    "node_modules/uuid": {
      "version": "14.0.1",
      "resolved": "https://registry.npmjs.org/uuid/-/uuid-14.0.1.tgz",
      "integrity": "sha512-6ZxzVpzDXDa3bJWaHilVayA+BH/1zmxCJoVgvmqJnid/gPoKHxUrS/aC/T6LGQtNHT+XHG9fXPJB4d+IrU30Ew==",
      "funding": [
        "https://github.com/sponsors/broofa",
        "https://github.com/sponsors/ctavan"
      ],
      "license": "MIT",
      "bin": {
        "uuid": "dist-node/bin/uuid"
      }
    }
  }
}

{
  "name": "csx-sample-uuid-config",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "uuid": "14.0.1"
  }
}

import { v4, stringify, validate, version } from 'uuid';

/**
 * Generates a v4 UUID using a custom RNG entropy source.
 * In uuid v9+, `options.rng` must be a generator returning a 16-byte Uint8Array/Array.
 * Passing a standard float-returning callback like `() => Math.random()` throws TypeError.
 */
export function generateDeterministicUuid(byteSupplier) {
  return v4({ rng: byteSupplier });
}

/**
 * Writes raw UUID bytes directly into an existing buffer at the specified offset.
 * `v4(options, buf, offset)` returns `buf` itself (a Uint8Array), NOT a string.
 */
export function writeUuidToBuffer(byteSupplier, buffer, offset = 0) {
  return v4({ rng: byteSupplier }, buffer, offset);
}

/**
 * Decodes a canonical UUID string from a binary buffer at the specified offset.
 */
export function readUuidFromBuffer(buffer, offset = 0) {
  return stringify(buffer, offset);
}

/**
 * Attempts to call v4 with an invalid scalar-returning RNG function.
 */
export function tryInvalidRng(scalarRng) {
  return v4({ rng: scalarRng });
}

export { validate, version };

import { strict as assert } from 'node:assert';
import {
  generateDeterministicUuid,
  writeUuidToBuffer,
  readUuidFromBuffer,
  tryInvalidRng,
  validate,
  version
} from '../src/index.mjs';

// 1. Naive assumption: options.rng accepts a standard JS random number callback () => Math.random()
// Reality: v4 throws TypeError because it expects rng() to return a 16-byte buffer/array
assert.throws(
  () => tryInvalidRng(() => Math.random()),
  { name: 'TypeError' }
);

// 2. Correct configuration: options.rng must return an ArrayLike of >= 16 bytes
const fixedEntropy = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
  0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10
]);

let calls = 0;
const rngSupplier = () => {
  calls++;
  return new Uint8Array(fixedEntropy);
};

const id = generateDeterministicUuid(rngSupplier);
assert.equal(calls, 1);
assert.equal(typeof id, 'string');
assert.equal(validate(id), true);
assert.equal(version(id), 4);
// RFC4122 transforms byte 6 (0x07 -> 0x47) and byte 8 (0x09 -> 0x89)
assert.equal(id, '01020304-0506-4708-890a-0b0c0d0e0f10');

// 3. Binary buffer writing: v4(options, buf, offset) returns buf itself (NOT a string)
const targetBuffer = new Uint8Array(32);
const offset = 8;
const returnedBuffer = writeUuidToBuffer(rngSupplier, targetBuffer, offset);

assert.equal(returnedBuffer, targetBuffer);
assert.equal(typeof returnedBuffer, 'object');
assert.equal(returnedBuffer instanceof Uint8Array, true);
assert.equal(returnedBuffer[offset + 6], 0x47);
assert.equal(returnedBuffer[offset + 8], 0x89);

// 4. Binary decoding: stringify(buf, offset) recovers the canonical UUID string
const decodedId = readUuidFromBuffer(targetBuffer, offset);
assert.equal(decodedId, '01020304-0506-4708-890a-0b0c0d0e0f10');

// 5. Buffer bounds safety: writes exceeding buffer length throw RangeError
assert.throws(
  () => writeUuidToBuffer(rngSupplier, new Uint8Array(10), 0),
  { name: 'RangeError' }
);

console.log('CONTRACT PASS: uuid v4 options.rng accepts 16-byte supplier and handles buffer offset serialization');