suaveplan/openspec/archive/2026-05-02-bytes-spec-conformance/proposal.md

bytes-spec-conformance

• Change ID: bytes-spec-conformance
• Package: @suaveplan/bytes
• Status: PROPOSED
• Type: spec-conformance
• Date: 2026-04-26

Why

The folded openspec/specs/bytes/spec.md documented the public surface as ### encoding / ### uint8 / ### uuid Module sections plus a flat list of function signatures. The conformance parser accepts only ### Requirement: <name> or ### CAP-NN — <name> headings, so bun scripts/openspec-conformance.ts @suaveplan/bytes reported "0 requirements parsed" — a parsing gap, not a contract gap. The implementation already satisfies every clause; this change makes those clauses machine-checkable and pins each one to existing tests.

What changes

• Rewrite openspec/specs/bytes/spec.md from prose-module headings to seven ### Requirement: <name> blocks with #### Scenario: subblocks and **Verified by:** lines that name concrete it(...) titles in the existing test suite.
• No source changes; no public-surface changes; no new tests required — every scenario is already pinned by src/encoding/encoding.test.ts, src/uint8/uint8.test.ts, and src/uuid/uuid.test.ts.

Out of scope

• New behaviour. This is heading rewrite + verification annotation only.
• Source mapping table — @suaveplan/bytes is genesis-original; there is no ../suaveplan/enterprise/bytes.md to cite.

Verification approach

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

• src/encoding/encoding.test.ts — encoding round-trips, error paths.
• src/uint8/uint8.test.ts — uint8 utilities, format detection, conversion façade.
• src/uuid/uuid.test.ts — UUID round-trip and validation.

Migration impact

None — additive metadata only. Public surface unchanged.