suaveplan/openspec/changes/utils-completion/proposal.md

# Utils completion — Uint8Array helpers (countries / languages / safe-json placed elsewhere)

**Package**: `@suaveplan/utils`
**Status**: PROPOSED
**Type**: spec-conformance + feature

## Why

The 2026-05-02 audit of `packages/core/utils/src` against `../suaveplan/packages/universal/utils/src` flagged four legacy modules that genesis appears to lack: `countries/`, `languages/`, `json/safe-json.ts`, and `uint/`. Closer inspection shows three of the four are not gaps in `@suaveplan/utils` at all — they were intentionally hoisted into dedicated genesis packages (`@suaveplan/locale-data`, `@suaveplan/json`). The fourth, `uint/`, was dropped without a replacement and is the genuine gap.

The legacy `uint/` module (340 L) is misnamed — it is a Uint8Array / encoding helper bag covering hex/base64/UTF-8 round-trips, format auto-detection, UUID interop, equality, concatenation, and slicing. Crypto-utils already covers hex / base64 / concat / xor / equality for cryptographic call sites, but those helpers are deliberately scoped to the crypto plugin (no UUID dependency, no auto-detection). Application-level callers — drag-and-drop file readers, clipboard handlers, query-string parsers — need a dependency-light Uint8Array module they can pull from `@suaveplan/utils` without dragging the entire crypto stack. Without it, every consumer reimplements `bytesToHex` / `hexToBytes`, drift is inevitable, and we accumulate the kind of subtle off-by-one bugs the legacy harness already pinned tests for.

Hoisting `countries`, `languages`, and `safe-json` to dedicated packages was the right call (each has its own catalog, schemas, and OTel surface), but the parity table for `utils-completion` must say so explicitly so the next agent doesn't accidentally re-introduce them under `utils/` and create two copies that drift.

## What changes

### `@suaveplan/utils` (this change)

- ADDED: `uint8Array/` feature module under `packages/core/utils/src/uint8-array/` — encoding-format conversion + Uint8Array helpers tier appropriate for application-level (non-cryptographic) call sites.
- ADDED: `bytesToHex(bytes)` / `hexToBytes(hex)` — strict hex validation (rejects empty string, odd-length non-prefixed input, non-hex characters via opt-in strict mode).
- ADDED: `bytesToBase64(bytes)` / `base64ToBytes(base64)` — uses `btoa` / `atob` in browser, `Buffer` fallback in Node.
- ADDED: `utf8ToBytes(str)` / `bytesToUtf8(bytes)` — `TextEncoder` / `TextDecoder` round-trip.
- ADDED: `detectInputFormat(input)` — heuristic format auto-detection for `"hex" | "utf8" | "uint8array"`.
- ADDED: `validateInputTypeFormat(input, format)` — runtime check that the JS type matches the declared format.
- ADDED: `inputToUint8Array(input, format)` — universal coerce-to-bytes entry point.
- ADDED: `formatOutput(bytes, format)` — universal format-from-bytes entry point.
- ADDED: `convertDataFormat(input, outputFormat, inputFormat?)` — round-trip convertor with optional auto-detection.
- ADDED: `uint8ArrayToUuid(bytes)` / `uuidToUint8Array(uuid)` — RFC 4122 16-byte ↔ canonical string interop.
- ADDED: `generateUuid()` — UUID v4 emission backed by an injectable `Rng` from `@suaveplan/types`; defaults to `crypto.getRandomValues`. Genesis policy bans module-scope `Math.random()`.
- ADDED: `uint8ArraysEqual(a, b)` — non-constant-time equality (the constant-time variant lives in `@suaveplan/crypto-utils::constant-time`; documented in `uint8-array.md` to prevent misuse in cryptographic contexts).
- ADDED: `concatUint8Arrays(...arrays)` — accepts both varargs and a single array argument; throws on non-Uint8Array elements via `UtilsError` (`UINT8_ARRAY.INVALID_ARGUMENT`).
- ADDED: `sliceUint8Array(data, splitAt)` — returns `[head, tail]` tuple; throws on out-of-bounds via `UtilsError` (`UINT8_ARRAY.OUT_OF_BOUNDS`).
- ADDED: `DataFormat` and `InputType` types under `uint8-array.types.ts`.
- ADDED: `uint8-array.schemas.ts` — Zod schemas for `DataFormat` and `convertDataFormat` options.
- ADDED: subpath export `./uint8-array` in `package.json::exports` for tree-shaking.

### Out-of-scope mappings (NOT changed in this proposal — documented for parity)

The 2026-05-02 audit specifically asked whether `countries`, `languages`, and `safe-json` belong in `utils`. The answer is **no**, they live elsewhere; the parity checklist below is the source of truth so this question is not re-litigated.

| Capability | Upstream location | Genesis location | Status |
|---|---|---|---|
| Country code/name registry | `packages/universal/utils/src/countries/` (3021 L) | `packages/i18n/locale-data/src/countries/` | PRESENT-ELSEWHERE |
| Language code registry | `packages/universal/utils/src/languages/` (474 L) | `packages/i18n/locale-data/src/languages/` | PRESENT-ELSEWHERE |
| Safe JSON parse / stringify (proto-pollution guard) | `packages/universal/utils/src/json/safe-json.ts` (385 L) | `packages/data/json/src/safe-json/` | PRESENT-ELSEWHERE |
| Uint8Array / encoding helpers | `packages/universal/utils/src/uint/uint.ts` (340 L) | NONE | ADDED (this change) |

## Out of scope

- **Cross-publishing `countries` / `languages` / `safe-json` from `@suaveplan/utils`.** Re-exporting them from `utils` would re-introduce duplicate publish surface and break tree-shaking for non-i18n consumers. Callers wanting locale data import `@suaveplan/locale-data`; callers wanting safe JSON import `@suaveplan/json`. The entries in the parity table above are PRESENT-ELSEWHERE, not delegated.
- **Constant-time `uint8ArraysEqual`.** The cryptographic-grade comparison stays in `@suaveplan/crypto-utils::constant-time` to keep the dependency direction one-way (utils → no crypto). The `uint8-array.md` doc cross-links to it.
- **Streaming / chunked encoding.** Application-level callers wanting backpressure-aware streaming use `@suaveplan/streams` (not yet on genesis); when it lands, a thin `streamHexEncode` adapter can re-export from there. No streaming work in this change.
- **`InputType = ArrayBuffer` overload.** Legacy accepts `ArrayBuffer` indirectly via a private detector. Genesis narrows the public type to `string | Uint8Array`; callers with `ArrayBuffer` should `new Uint8Array(buf)` before passing. Documented in `uint8-array.md`.
- **UUID v1 / v3 / v5 / v7.** Only v4 generation is in scope. Other versions belong in a future `@suaveplan/uuid` package or are obtainable from `crypto.randomUUID` + format conversion already.

## Parity Checklist

Every legacy export traced, with disposition.

| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
| `bytesToHex` | ✅ | ✅ | Verbatim port; default permissive (matches legacy), strict mode opt-in. |
| `hexToBytes` | ✅ | ✅ | Throws on empty input + non-hex; matches legacy error message. |
| `bytesToBase64` | ✅ | ✅ | `btoa` browser / `Buffer` Node fallback. |
| `base64ToBytes` | ✅ | ✅ | `atob` browser / `Buffer` Node fallback. |
| `utf8ToBytes` / `bytesToUtf8` | ✅ | ✅ | Native `TextEncoder` / `TextDecoder`. |
| `_detectFormat` (private) | ✅ | 🚫 | Replaced by `detectInputFormat` (the public version). Internal helper not needed once `ArrayBuffer` overload is dropped. |
| `detectInputFormat` | ✅ | ✅ | Public API stays. |
| `validateInputTypeFormat` | ✅ | ✅ | Throws via `UtilsError` instead of plain `Error`. |
| `inputToUint8Array` | ✅ | ✅ | Verbatim. |
| `formatOutput` | ✅ | ✅ | Verbatim. |
| `convertDataFormat` | ✅ | ✅ | Verbatim. |
| `uint8ArrayToUuid` | ✅ | ✅ | Backed by `uuid` catalog. |
| `uuidToUint8Array` | ✅ | ✅ | Backed by `uuid` catalog. |
| `generateUuid` | ✅ | ⬆️ | Enhanced: injectable `Rng`, defaults to `crypto.getRandomValues`. Genesis bans module-scope `Math.random()`. |
| `uint8ArraysEqual` | ✅ | ✅ | Non-constant-time (matches legacy). Crypto-grade comparison delegated to `@suaveplan/crypto-utils`. |
| `concatUint8Arrays` | ✅ | ✅ | Same dual signature (varargs OR single array). `UtilsError` instead of plain `Error`. |
| `sliceUint8Array` | ✅ | ✅ | `UtilsError` instead of plain `Error`. |
| `DataFormat` / `InputType` types | ✅ | ✅ | Co-located in `uint8-array.types.ts`. |
| `countries/*` (3021 L) | ✅ | 🚫 | PRESENT-ELSEWHERE: `@suaveplan/locale-data::countries`. Cross-publishing rejected (see Out of scope). |
| `languages/*` (474 L) | ✅ | 🚫 | PRESENT-ELSEWHERE: `@suaveplan/locale-data::languages`. Cross-publishing rejected. |
| `json/safe-json.ts` (385 L) | ✅ | 🚫 | PRESENT-ELSEWHERE: `@suaveplan/json::safe-json`. Cross-publishing rejected. |

## Source mapping

This change derives from `../suaveplan/packages/universal/utils/src/uint/`. There is no `enterprise/utils.md` for the encoding sub-feature — source mapping cites upstream source directly.

| Requirement | Source file | Source lines | Notes |
|---|---|---|---|
| `bytesToHex` / `hexToBytes` | `packages/universal/utils/src/uint/uint.ts` | L20-L58 | Verbatim; rewire `Error` → `UtilsError` with stable code. |
| `bytesToBase64` / `base64ToBytes` | `packages/universal/utils/src/uint/uint.ts` | L62-L91 | Verbatim. |
| `utf8ToBytes` / `bytesToUtf8` | `packages/universal/utils/src/uint/uint.ts` | L95-L105 | Verbatim. |
| `detectInputFormat` | `packages/universal/utils/src/uint/uint.ts` | L134-L149 | Verbatim. |
| `validateInputTypeFormat` | `packages/universal/utils/src/uint/uint.ts` | L154-L170 | Verbatim; `UtilsError` instead of `Error`. |
| `inputToUint8Array` | `packages/universal/utils/src/uint/uint.ts` | L175-L194 | Verbatim. |
| `formatOutput` | `packages/universal/utils/src/uint/uint.ts` | L199-L216 | Verbatim. |
| `convertDataFormat` | `packages/universal/utils/src/uint/uint.ts` | L225-L252 | Verbatim. |
| `uint8ArrayToUuid` / `uuidToUint8Array` | `packages/universal/utils/src/uint/uint.ts` | L257-L271 | Verbatim; backed by `uuid` catalog dep. |
| `generateUuid` | `packages/universal/utils/src/uint/uint.ts` | L275-L278 | Enhanced: injectable `Rng`. |
| `uint8ArraysEqual` | `packages/universal/utils/src/uint/uint.ts` | L283-L289 | Verbatim. |
| `concatUint8Arrays` | `packages/universal/utils/src/uint/uint.ts` | L294-L322 | Verbatim. |
| `sliceUint8Array` | `packages/universal/utils/src/uint/uint.ts` | L330-L340 | Verbatim. |
| `DataFormat` / `InputType` types | `packages/universal/utils/src/uint/uint.types.ts` | L1-L2 | Verbatim. |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| `UtilsError` codes for `UINT8_ARRAY.INVALID_HEX`, `UINT8_ARRAY.INVALID_FORMAT`, `UINT8_ARRAY.INVALID_ARGUMENT`, `UINT8_ARRAY.OUT_OF_BOUNDS` | Genesis-wide policy that every thrown error route through `@suaveplan/error` (CLAUDE.md §Workflow rule 2). Legacy throws plain `Error`. |
| Injectable `Rng` for `generateUuid` | Genesis-wide determinism rule; module-scope `Math.random()` is banned. |
| Zod schemas for `DataFormat` and `convertDataFormat` options | Genesis-wide policy (CLAUDE.md "Zod schemas wired at every declared boundary"). |
| Module renamed from `uint/` to `uint8-array/` | The legacy name suggested typed-integer constructors (`uint8(n)`/`uint16(n)`/...) which it never delivered. The genesis name describes what the module actually does. The 2026-05-02 audit explicitly flagged this confusion. |

## Verification approach

- `src/uint8-array/uint8-array.test.ts` — every helper round-trip; error scenarios for invalid hex, invalid format, out-of-bounds slice; equality false on length mismatch; concat with mixed input shapes; UUID 16-byte validation.
- `src/uint8-array/uint8-array.spec-conformance.test.ts` — `UtilsError` codes thrown from production paths; injected `Rng` used by `generateUuid`; Zod schemas reject invalid formats; subpath `./uint8-array` resolves and tree-shakes.

## Impact

### Affected dependents

`@suaveplan/utils` currently has zero downstream packages on genesis (verified by `bunx turbo ls --filter=...@suaveplan/utils`). This is purely additive surface area — the change cannot break anything that doesn't yet exist.

- No dependents (verified by `grep -rln "@suaveplan/utils" /home/ubuntu/web/genesis/packages/ --include=package.json` returning only `packages/core/utils/package.json` itself).

When new consumers land, they import `@suaveplan/utils/uint8-array` or `@suaveplan/utils` (root barrel). Existing imports of `@suaveplan/utils/debug`, `./object`, etc. continue to work — this change adds a subpath, never removes one.

## Migration impact

None — additive only. No public surface is removed or renamed.