suaveplan/openspec/archive/2026-04-29-utils-spec-conformance/proposal.md

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.