suaveplan/openspec/archive/2026-04-20-enterprise-bytes/proposal.md

Proposal: @suaveplan/bytes

Why This Package

Low-level byte manipulation — converting between hex, base64, UTF-8, and raw Uint8Array; concatenating and slicing typed arrays; round-tripping UUID strings to 16-byte buffers — is a recurring primitive across the entire monorepo. Today every package that needs these operations duplicates ad-hoc helpers or reaches into @suaveplan/crypto-utils, which bundles encoding utilities alongside cryptographic concerns. Separating them into a dedicated @suaveplan/bytes package gives the monorepo a single, well-tested, zero-cryptographic-dependency source of truth for byte I/O.

What It Provides

The package ships three focused modules under universal/primitives/bytes:

• encoding — bytesToHex/hexToBytes, bytesToBase64/base64ToBytes, bytesToUtf8/utf8ToBytes; strict validation with typed BytesError codes; OTel spans on every public function; Zod schemas for hex and base64 strings; fast-check property tests verifying lossless round-trips for arbitrary byte sequences.
• uint8 — concatUint8Arrays, sliceUint8Array, uint8ArraysEqual, inputToUint8Array, detectInputFormat, validateInputTypeFormat, formatOutput, convertDataFormat; a uniform convertDataFormat(input, outputFormat, inputFormat?) façade that auto-detects the input format when the caller omits it.
• uuid — generateUuid (UUIDv4 via crypto.randomUUID()), uuidToUint8Array (16-byte canonical parse), uint8ArrayToUuid (reformat bytes to canonical string); Zod UUID schema.

All three modules depend only on @suaveplan/error, zod, and @opentelemetry/api. There are no external encoding libraries and no native addons.

Impact

@suaveplan/crypto-utils will be able to import @suaveplan/bytes for its encoding helpers in a follow-up refactor, eliminating internal duplication. Application packages that today copy-paste bytesToHex or import it from crypto-scoped modules will have a direct, semantically correct dependency target. The UUID utilities unblock @suaveplan/idempotency and any package that stores entity identifiers as binary blobs.