Initial Commit

openspec/changes/utils-completion/tasks.md

@@ -0,0 +1,73 @@
+# 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)