suaveplan/openspec/changes/audio-shipped-file-size-cleanup/proposal.md

OpenSpec Change: audio-shipped-file-size-cleanup

• Change ID: audio-shipped-file-size-cleanup
• Packages: @suaveplan/audio-timeline, @suaveplan/audio-transport, @suaveplan/audio-metadata
• Category: maintenance (refactor — no behavior change)
• Status: PROPOSED
• Date: 2026-05-15
• Design: ./design.md
• Spec deltas: ./specs/audio-timeline/spec.md, ./specs/audio-transport/spec.md, ./specs/audio-metadata/spec.md

---

Why

A post-ship audit of the three universal audio packages flagged source and test files exceeding CLAUDE.md Rule §3 / openspec/AGENTS.md §3 (300-line hard cap on source, 500-line cap on tests):

Package	File	Lines	Cap	Over
audio-timeline	src/engine/engine.ts	548	300	+248
audio-timeline	src/engine/engine.test.ts	819	500	+319
audio-transport	src/transport/transport.ts	419	300	+119
audio-metadata	src/parsers/id3v2/id3v2.ts	536	300	+236
audio-metadata	src/parsers/id3v2/id3v2.test.ts	1340	500	+840
audio-metadata	src/parsers/mp4-atom/mp4-atom.ts	351	300	+51
audio-metadata	src/parsers/mp4-atom/mp4-atom.test.ts	670	500	+170
audio-metadata	src/parsers/ogg-vorbis/ogg-vorbis.test.ts	803	500	+303

The 1340-line id3v2.test.ts (more than 2.6× the cap) is the most egregious. All eight files passed their own gates because the size budget is currently enforced by manual audit rather than a CI check.

In parallel, the audit found a §7 / Rule 11 violation that was already migrated as a separate change (audio-timeline test files importing directly from vitest — the bench import was wrong-framework too and is now migrated to mitata). That work is out of scope for this proposal.

What changes

• REFACTOR: Split each oversized source file at natural responsibility boundaries while preserving the exact public API surface (every existing export keeps its name, signature, and semantics).
• REFACTOR: Split each oversized test file into co-located sibling *.test.ts modules, one per cohesive behavior cluster (e.g. id3v2/frames.test.ts, id3v2/text-encoding.test.ts, id3v2/extended-header.test.ts).
• ADDED: Per-package barrel updates if new sub-modules are created — explicit named re-exports only (§6a).
• ADDED: Sibling .md docs for any new implementation files; the original file's .md stays as the surface-level overview.
• NO BEHAVIOR CHANGE. Test counts must not decrease. Coverage must remain 100/100/100/100.

Out of scope

• API redesigns or new features.
• The runner-import migration (already done in audio-timeline).
• File-size cleanups in other packages (handled separately if needed).
• Introducing a new CI gate for the 300/500 caps — recommended as a follow-up.

Source mapping

This is a pure-genesis maintenance change; no upstream reference. The size caps come from CLAUDE.md (§Quality) and openspec/AGENTS.md §3.

Impact

Breaking changes: none. Public API surface, package exports, and package.json exports entries are preserved verbatim. Internal sub-module paths may shift, but they were never part of the public contract.

Affected dependents

The three packages are universal-tier and currently have no published consumers on genesis (bunx turbo ls --filter=...@suaveplan/audio-timeline / audio-transport / audio-metadata returns empty). Future consumers (audio-engine-browser, audio-engine-server, react-audio*) consume the public surface, which this change does not touch.

• No dependents (verified by bunx turbo ls --filter=...@suaveplan/audio-timeline).
• No dependents (verified by bunx turbo ls --filter=...@suaveplan/audio-transport).
• No dependents (verified by bunx turbo ls --filter=...@suaveplan/audio-metadata).

Verification approach

For each touched package:

1. bunx turbo lint typecheck test --filter=@suaveplan/<pkg> — green.
2. bunx turbo test:coverage --filter=@suaveplan/<pkg> — 100/100/100/100.
3. bunx turbo build --filter=@suaveplan/<pkg> — green.
4. find packages/audio/<pkg>/src -name "*.ts" ! -name "*.test.ts" | xargs awk 'END { if (NR > 300) print FILENAME, NR " lines" }' — empty.
5. find packages/audio/<pkg>/src packages/audio/<pkg>/tests -name "*.test.ts" | xargs awk 'END { if (NR > 500) print FILENAME, NR " lines" }' — empty.
6. Diff the public exports map in package.json before/after — identical.
7. Diff dist/ .d.ts files before/after — only path / source-map changes; no type-shape changes.

Follow-up

Once this change archives, add a scripts/lint/check-file-sizes.ts CI gate so the caps are enforced automatically. That belongs in its own change — out of scope here.