# 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.