suaveplan/openspec/archive/2026-05-19-add-audio-ir-core/proposal.md

Add @suaveplan/audio-ir-core

Package: @suaveplan/audio-ir-core Status: PROPOSED Type: new-package

Why

The IR ecosystem (audio-ir-loader, audio-ir-{mic,speaker,room}-plugin-<name> packages) needs a single foundation that owns the IR contract, manifest schema, and in-memory registry. Without it, every IR content package would reinvent the entry shape, the registry collision rule, and the ID-derivation convention — guaranteed drift. This package is the foundation every sibling depends on.

What changes

• ADDED: ImpulseResponse type — { id: string; channelData: readonly Float32Array[]; channels: number; sampleRate: number; lengthFrames: number; durationSec: number; gainDb: number; family: "mic" | "speaker" | "room"; manifest: IrManifestEntry }. Frozen, validated.
• ADDED: IrManifestEntry Zod schema — { id, family, uri, channels, sampleRate, gainDb, license, source }. id matches /^[a-z][a-z0-9-]*$/ (no consecutive -, starts with a letter, length 1–128). uri is any non-empty string (deferred validation to storage-uri at load time).
• ADDED: IrManifest Zod schema — { packageSlug: <slug grammar>, family: "mic" | "speaker" | "room", entries: readonly IrManifestEntry[] }. Every entry.id SHALL begin with <packageSlug>- (enforced by schema refinement). entry.family SHALL equal manifest-level family.
• ADDED: IrRegistry — in-memory Map-backed registry with register(entry), has(id), get(id), list({ family? }), clear(). register throws AUDIO_IR.DUPLICATE_ID when an ID is registered twice.
• ADDED: createIrRegistry() factory.
• ADDED: AUDIO_IR.* codes via defineCodes: DUPLICATE_ID, NOT_REGISTERED, INVALID_MANIFEST, ID_PREFIX_MISMATCH, FAMILY_MISMATCH.
• ADDED: OTel — audio_ir.registry_size{family} observable gauge; audio_ir.registrations_total{family, outcome} counter; audio_ir.lookups_total{family, outcome} counter; audio_ir.errors_total{code} counter.

Out of scope

Nothing functional within the foundation's scope. The following are explicitly NOT here, because they belong to siblings:

• Loading + decoding — audio-ir-loader owns the resolver-driven walk.
• Concrete IR data — audio-ir-{mic,speaker,room}-plugin-<name> packages own the files and the per-package register(registry, resolver) call.

Source mapping

Genesis-original. No upstream enterprise/audio-ir-core.md exists.

Requirements with no source line

Requirement	Justification
every spec requirement	Genesis-original foundation; no upstream baseline

Verification approach

• src/types/manifest-entry.test.ts — Zod parsing + refinement (id grammar, id-prefix rule, family rule).
• src/types/manifest.test.ts — manifest-level Zod validation.
• src/registry/registry.test.ts — register / has / get / list / clear semantics; DUPLICATE_ID throw.
• src/registry/registry.spec-conformance.test.ts — strict-mode behaviors, lookup invariants under concurrency.
• src/otel/otel.test.ts — counter + gauge assertions with real in-memory MeterProvider.
• src/error-codes/error-codes.test.ts — exhaustion.

Impact

Affected dependents

No dependents yet (the package is brand new). Verified by bunx turbo ls --filter=...@suaveplan/audio-ir-core returning only the package itself.

The first downstream consumers will be @suaveplan/audio-ir-loader and every @suaveplan/audio-ir-{family}-plugin-<name> package, each landing in its own change.