# utils-spec-conformance

- **Change ID**: utils-spec-conformance
- **Package**: `@suaveplan/utils`
- **Status**: PROPOSED
- **Type**: spec-conformance
- **Date**: 2026-04-26

## Why

The folded `openspec/specs/utils/spec.md` documented the public surface as
`### ./errors`, `### ./debug`, `### ./object`, … module sections with bullet
lists of function signatures. The conformance parser only sees `###
Requirement: <name>` or `### CAP-NN —` headings, so the audit reported "0
requirements parsed". The implementation already satisfies every clause;
this change makes them machine-checkable and pins each scenario to existing
tests.

## What changes

- Rewrite `openspec/specs/utils/spec.md` from `./<module>` section headings
  to ten `### Requirement: <name>` blocks, one per module:
  - debug logger with bounded dedup buffer
  - object utilities (type guards, deepMerge, pick/omit, flattenObject,
    getNestedValue, deepClone)
  - platform detection with injectable adapter
  - IEEE 754 float packing and range constants
  - pseudorandom array selection
  - provider-aware email normalization
  - sound-sprite parsing and variation selection
  - string utilities (id generation, link extraction)
  - hex string validation
  - byte-size enforcement and parsing

- Add `**Verified by:**` lines under every requirement naming concrete
  `it(...)` titles in the corresponding `*.test.ts` files (10 test files,
  169 cases pre-dating this change).
- No source changes; no public-surface changes.

## Out of scope

- New behaviour. Heading rewrite + verification annotation only.
- `errors` is not a separate requirement block — error semantics are
  asserted via the codes raised in each module's requirement (object
  prototype-pollution, random empty/oob, validation size/parse, platform
  unavailable, sound no-variations).
- Source mapping table — `@suaveplan/utils` is genesis-original.

## Verification approach

Every requirement is pinned to existing `it(...)` titles in:

- `src/debug/debug.test.ts`
- `src/object/object.test.ts`
- `src/platform/platform.test.ts`
- `src/number/number.test.ts`
- `src/random/pseudo.test.ts`
- `src/email/email.test.ts`
- `src/sound/sound.test.ts`
- `src/string/string.test.ts`
- `src/validate/validate.test.ts`
- `src/validation/size.test.ts`

## Migration impact

None — additive metadata only. Public surface unchanged.