# UUIDv4 generation

MoonUUID implements UUIDv4 according to RFC 9562.

## API layers

The UUIDv4 API is intentionally split into three levels.

### `v4_from_entropy`

```moonbit
let id = @moonuuid.v4_from_entropy(
  b"\x91\x91\x08\xf7\x52\xd1\x43\x20\x9b\xac\xf8\x47\xdb\x41\x48\xa8",
)
```

This is the deterministic core. It requires exactly 16 input bytes and overwrites
only the RFC-defined version and variant bits.

It does not claim that the supplied bytes are random.

### `v4_with_entropy`

```moonbit
let result = @moonuuid.v4_with_entropy(fn(length : Int) -> Bytes? {
  my_secure_random_bytes(length)
})
```

The provider is always requested for 16 bytes. This form is useful for embedded
hosts, application runtimes and tests that need explicit control of entropy.

### `v4`

```moonbit
match @moonuuid.v4() {
  Ok(id) => println(@moonuuid.to_string(id))
  Err(_) => println("secure entropy is unavailable")
}
```

The convenience generator delegates to `moonbitlang/core/env.rand`.

MoonBit documents `@env.rand` as a platform secure entropy source and returns
`None` when secure entropy is unavailable. MoonUUID preserves that failure:
it does not silently fall back to `Math.random`, timestamps, counters or a
deterministic PRNG.

## RFC bit layout

For 16 entropy bytes, MoonUUID sets:

```text
octet 6 high nibble: 0100  -> UUID version 4
octet 8 high bits:   10xx  -> RFC 9562 variant
```

Every other bit remains entropy.

For example, sixteen zero bytes become:

```text
00000000-0000-4000-8000-000000000000
```

and sixteen `0xff` bytes become:

```text
ffffffff-ffff-4fff-bfff-ffffffffffff
```

## Target behavior

The default `v4()` API follows the entropy capabilities exposed by the current
MoonBit core runtime:

- native: runtime platform entropy source;
- JavaScript: `globalThis.crypto.getRandomValues`;
- wasm: WASI `random_get` when provided by the host;
- wasm-gc: currently reports entropy unavailable.

The deterministic and injected-provider APIs work on every supported target.