Initial Commit

openspec/specs/bytes/spec.md

@@ -0,0 +1,41 @@
+# bytes
+
+## Purpose
+
+Low-level byte I/O for the Suaveplan monorepo. Provides lossless conversion between `Uint8Array` and the three ubiquitous text representations (hex, base64, UTF-8), ergonomic `Uint8Array` utilities (concat, slice, equality, format auto-detection, unified conversion façade), and UUID string ↔ 16-byte binary round-trip functions.
+
+## Requirements
+
+### encoding
+
+- `bytesToHex(bytes: Uint8Array): string` — lowercase hex, empty → `""`
+- `hexToBytes(hex: string): Uint8Array` — case-insensitive; throws `BYTES.ENCODE.INVALID_HEX` on odd length or non-hex chars
+- `bytesToBase64(bytes: Uint8Array): string` — standard base64 with `=` padding
+- `base64ToBytes(base64: string): Uint8Array` — throws `BYTES.ENCODE.INVALID_BASE64` on invalid input
+- `bytesToUtf8(bytes: Uint8Array): string` — `TextDecoder("utf-8")`
+- `utf8ToBytes(str: string): Uint8Array` — `TextEncoder`
+
+### uint8
+
+- `concatUint8Arrays(...arrays: Uint8Array[]): Uint8Array`
+- `sliceUint8Array(arr, start, end?): Uint8Array`
+- `uint8ArraysEqual(a, b): boolean` — not constant-time
+- `detectInputFormat(input: BytesInput): InputFormat` — heuristic: Uint8Array → `"uint8array"`, even-length hex string → `"hex"`, else `"utf8"`
+- `inputToUint8Array(input, format?): Uint8Array`
+- `validateInputTypeFormat(input, format): void` — throws `BYTES.UINT8.FORMAT_MISMATCH`
+- `formatOutput(bytes, format): string | Uint8Array`
+- `convertDataFormat(input, outputFormat, inputFormat?): string | Uint8Array` — OTel span
+
+### uuid
+
+- `generateUuid(): string` — UUIDv4 via `crypto.randomUUID()`
+- `uuidToUint8Array(uuid: string): Uint8Array` — 16 bytes; throws `BYTES.UUID.INVALID_FORMAT`
+- `uint8ArrayToUuid(bytes: Uint8Array): string` — canonical lowercase; throws `BYTES.UUID.INVALID_LENGTH`
+
+## Error codes
+
+`BYTES.ENCODE.INVALID_HEX`, `BYTES.ENCODE.INVALID_BASE64`, `BYTES.ENCODE.INVALID_UTF8` (reserved), `BYTES.UINT8.INVALID_INPUT`, `BYTES.UINT8.FORMAT_MISMATCH`, `BYTES.UUID.INVALID_LENGTH`, `BYTES.UUID.INVALID_FORMAT`
+
+## Version
+
+Published: `0.1.0` (2026-04-20)