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

Tasks — Utils completion (Uint8Array helpers)

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened. Do not tick a box for a test that doesn't exist or doesn't pin the requirement it claims to verify.

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

Audit Note (2026-05-02)

Status: DEFERRED. The entire uint8-array/ feature module is missing from packages/core/utils/src/ (existing dirs: debug, email, errors, number, object, platform, random, sound, string, types, validate, validation). 0% of work is done. All tasks below remain accurate.

1. Spec authoring

• 1.1 Read ../suaveplan/packages/universal/utils/src/uint/uint.ts end-to-end
• 1.2 Read openspec/specs/utils/spec.md
• 1.3 Read openspec/AGENTS.md Sections 13 and 14
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Fill in ## Source mapping table — every requirement cites a line range OR appears in the "no source line" table with justification
• 1.6 Draft specs/utils/spec.md from openspec/templates/spec-delta.md
• 1.7 Every requirement in the spec delta carries a **Verified by:** line naming concrete it(...) titles
• 1.8 Confirm parity table: PRESENT-ELSEWHERE for countries / languages / safe-json is documented and not silently re-introduced

2. Implementation

• 2.1 Add uuid to root package.json::catalog if not already present; reference via catalog: from @suaveplan/utils
• 2.2 Add UtilsError codes (UINT8_ARRAY.INVALID_HEX, INVALID_FORMAT, INVALID_ARGUMENT, OUT_OF_BOUNDS) under src/errors/
• 2.3 Create src/uint8-array/ feature module with uint8-array.ts, uint8-array.types.ts, uint8-array.schemas.ts, uint8-array.md, index.ts
• 2.4 Implement bytesToHex / hexToBytes / bytesToBase64 / base64ToBytes / utf8ToBytes / bytesToUtf8 per spec delta
• 2.5 Implement detectInputFormat, validateInputTypeFormat, inputToUint8Array, formatOutput, convertDataFormat
• 2.6 Implement uint8ArrayToUuid, uuidToUint8Array, generateUuid (with injectable Rng from @suaveplan/types)
• 2.7 Implement uint8ArraysEqual, concatUint8Arrays, sliceUint8Array
• 2.8 Add subpath export ./uint8-array to package.json::exports
• 2.9 Re-export the public surface from the root barrel src/index.ts

3. Tests

• 3.1 Unit tests at src/uint8-array/uint8-array.test.ts covering every helper, every error path, and every round-trip
• 3.2 Spec-conformance tests at src/uint8-array/uint8-array.spec-conformance.test.ts pinning UtilsError codes, injectable Rng consumption, Zod schema enforcement, subpath export resolution
• 3.3 Property-based tests via fast-check for bytesToHex ↔ hexToBytes and bytesToBase64 ↔ base64ToBytes round-trips
• 3.4 Every it(...) carries { timeout: 5000 }

4. Documentation

• 4.1 Sibling uint8-array.md (≥200 words, basic + advanced examples, full API reference, cross-link to @suaveplan/crypto-utils::constant-time for cryptographic equality)
• 4.2 README links ./uint8-array/uint8-array.md under ## Modules
• 4.3 Update CLAUDE.md @suaveplan/utils entry to mention the new uint8Array capability

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/utils — green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/utils — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/utils — exit 0, no error findings
• 5.5 bunx turbo build --filter=@suaveplan/utils — green

6. Pre-archive 7-row checklist (AGENTS.md Section 13)

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim (DataFormat union exact-type pinned)
• 6.2 Zod schemas wired at every declared boundary (DataFormat, convertDataFormat options)
• 6.3 Every error code in error-codes.ts thrown by at least one production path
• 6.4 Strict-mode behaviors tested (e.g. permissive vs strict hex parsing)
• 6.5 OTel instruments emitted from production paths and asserted with a real in-memory MeterProvider
• 6.6 Lifecycle dedup — N/A (no caches in this module)
• 6.7 No retroactive tick — every box above reflects work done in this change

7. Archive

• 7.1 Fold spec delta into openspec/specs/utils/spec.md
• 7.2 Move openspec/changes/utils-completion/ → openspec/archive/<yyyy-mm-dd>-utils-completion/
• 7.3 Refresh MANIFEST.md if dep set changed (catalog uuid add)