Initial Commit

openspec/specs/audio-core/spec.md

@@ -0,0 +1,382 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: audio-core (audio-core)
+
+**Package**: `@suaveplan/audio-core`
+**Status**: PROPOSED
+
+> Every requirement below carries a `**Verified by:**` line at authoring time. No exceptions.
+
+## ADDED Requirements
+
+### Requirement: Universal-tier purity
+
+The `@suaveplan/audio-core` package SHALL import zero browser-only APIs (`window`, `document`, `navigator`, `AudioContext`, `AudioBuffer`) and zero Node-only APIs (`node:fs`, `node:path`, `process`, `Buffer`). All environment-specific behaviour SHALL be reached only through injected adapters. The package's `dependencies` SHALL be limited to `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/streams`, `@suaveplan/serialize`, `tslib`, and `zod`; `@opentelemetry/api` is the only permitted non-workspace runtime dependency.
+
+#### Scenario: Built dist references no platform globals
+
+- **WHEN** the built `dist/` is grep'd
+- **THEN** it MUST NOT reference `window`, `document`, `navigator`, `AudioContext`, `node:fs`, `node:path`, `process`, or `Buffer`
+
+#### Scenario: Tests pass under both runtimes
+
+- **WHEN** the suite runs under `bun test` (server) and under vitest with a `happy-dom` shim (browser)
+- **THEN** both runs pass with identical results
+
+**Verified by:** `tests/purity.test.ts::"dist references no browser or Node globals"` AND `tests/purity.test.ts::"dependency set is limited to the declared workspace and zod"`
+
+---
+
+### Requirement: AudioDocument paged container
+
+The package SHALL export an `AudioDocument` class constructed from `AudioDocumentOptions`. It SHALL expose readonly `id`, `pages`, `sampleRate`, `channels`, and `sourceLength`, plus virtual `length` and `duration` getters whose cached values are invalidated by `version` bumps. PCM SHALL be stored as paged `AudioPage` records (`{ channelData: Float32Array[]; startSample: number }`); a `null` slot in the page array indicates an evicted page that can be reloaded. Construction with no `id` SHALL derive a stable id via the injected `IdGenerator`.
+
+#### Scenario: Virtual length tracks edits without materialisation
+
+- **WHEN** a caller appends a `trim` edit that halves the range
+- **THEN** `doc.length` reflects the trimmed sample count, `doc.version` has incremented, and no `AudioPage` has been allocated or copied
+
+#### Scenario: Evicted page is represented as null
+
+- **WHEN** a page is evicted from `doc.pages`
+- **THEN** the slot holds `null` and a subsequent read for that range triggers a reload rather than throwing
+
+**Verified by:** `src/document/document.test.ts::"virtual length reflects edits with O(1) cost"` AND `src/page/page.test.ts::"evicted page slot is null and reloadable"`
+
+---
+
+### Requirement: Non-destructive edit history
+
+`AudioDocument.run(...edits)` SHALL append `AudioEdit` records, increment `version`, and emit an `edit` event. `undo(n?)` SHALL pop the last `n` edits (default 1), emit an `undo` event, and return the removed edit(s) or `null` when the history is empty. `clone()` SHALL produce a document with an independent `pages` array and `edits` array such that mutating one does not affect the other. Editing SHALL be O(1) in the number of samples — materialisation is deferred to `read()` / `stream()`.
+
+#### Scenario: Run then undo restores edit state
+
+- **WHEN** a caller runs two edits then calls `undo(2)`
+- **THEN** `doc.edits` is empty, `doc.version` has incremented twice more, and `undo` returned both removed edits
+
+#### Scenario: Clone is structurally independent
+
+- **WHEN** a caller clones a document and runs an edit on the clone
+- **THEN** the original's `edits` and `version` are unchanged
+
+**Verified by:** `src/document/document.test.ts::"run appends and undo removes edits with events"` AND `src/document/document.test.ts::"clone produces an independent document"`
+
+---
+
+### Requirement: Document serialization round-trip
+
+`AudioDocument.toJSON()` SHALL return an `AudioDocumentJSON` value that, when passed through `@suaveplan/serialize`, round-trips exactly — including `Float32Array` page data, the `edits` array, `version`, `source`, and `metadata`. A document reconstructed from the deserialized JSON SHALL produce a `toJSON()` value deep-equal to the original's.
+
+#### Scenario: toJSON survives serialize/deserialize
+
+- **WHEN** a caller serializes `doc.toJSON()` and deserializes it back into an `AudioDocument`
+- **THEN** the reconstructed document's `toJSON()` is deep-equal to the original's
+
+**Verified by:** `src/document/document.test.ts::"toJSON round-trips through @suaveplan/serialize"` AND `tests/property.test.ts::"clone toJSON equals original toJSON"`
+
+---
+
+### Requirement: Typed document event surface
+
+`AudioDocument` SHALL expose `on` / `off` methods typed against `AudioDocumentEventMap` with the topics `edit`, `undo`, `plugin:error`, and `page:loaded`, backed by `@suaveplan/events`. Listener registration and removal SHALL be idempotent — registering the same listener twice SHALL fire it once, and `off` for an unregistered listener SHALL be a no-op.
+
+#### Scenario: Edit event carries the edit and version
+
+- **WHEN** a listener is registered for `edit` and a caller runs an edit
+- **THEN** the listener is invoked once with `{ edit, version }` matching the appended edit and the new version
+
+**Verified by:** `src/document/document.test.ts::"on/off manage typed listeners idempotently"`
+
+---
+
+### Requirement: Paged memory primitives
+
+The package SHALL export `PAGE_SIZE` (`1024 * 1024` samples) and `BLOCK_SIZE` (`1024` samples) constants, and the primitives `walkPages(doc, channel, startSample, count, visitor)`, `copyPages(doc, channel, startSample, count, target, targetOffset)`, and `readPages(doc, offset?, duration?)`. Pages SHALL be allocated from a reusable pool (`allocatePage` / `releasePage`) to reduce GC pressure during long streams. `walkPages` SHALL invoke the visitor once per overlapping page with the correct intra-page offset and length; `copyPages` SHALL write into a caller-supplied pre-allocated buffer without allocating.
+
+#### Scenario: walkPages visits every overlapping page
+
+- **WHEN** a caller calls `walkPages` over a range spanning three pages
+- **THEN** the visitor is invoked exactly three times with offsets and lengths that sum to the requested count
+
+#### Scenario: Page pool reuses released buffers
+
+- **WHEN** a page is released and a new page of the same shape is allocated
+- **THEN** the allocator returns the previously released `Float32Array[]` rather than allocating fresh memory
+
+**Verified by:** `src/page/page.test.ts::"walkPages visits each overlapping page with correct offsets"` AND `src/page/page.test.ts::"page pool reuses released buffers"`
+
+---
+
+### Requirement: Plan compilation
+
+The package SHALL export a `PlanEngine` class constructed from an `OpRegistry`. `compile(doc, final?)` SHALL convert `doc.edits` into a `CompiledPlan` (`{ segs, pipeline, totalLen, sampleRate, limit }`) in two passes: a resolve pass that expands high-level edits into primitive edits via each op's `resolve` function, and a plan pass that transforms the `Segment[]` via each op's `plan` function. Ops without a `plan` function SHALL be appended to `pipeline` as process-stage ops. An edit whose `type` is not registered SHALL throw `AudioError` with code `AUDIO_CORE.PLUGIN_NOT_FOUND`. When `final` is false the engine SHALL track a `limit` marking the safe source boundary for incremental decode.
+
+#### Scenario: Identity edit preserves total length
+
+- **WHEN** a document with an identity edit (e.g. `gain` at unity) is compiled
+- **THEN** `plan.totalLen` equals `doc.sourceLength`
+
+#### Scenario: Unknown op type throws AUDIO_CORE.PLUGIN_NOT_FOUND
+
+- **WHEN** `compile` encounters an edit whose `type` is not in the registry
+- **THEN** it throws `AudioError` whose `code === "AUDIO_CORE.PLUGIN_NOT_FOUND"` with the offending `type` in `context`
+
+#### Scenario: Compilation is deterministic
+
+- **WHEN** the same document is compiled twice
+- **THEN** the two `CompiledPlan` values are deep-equal
+
+**Verified by:** `src/plan/plan-engine.test.ts::"compile resolves and plans edits into a CompiledPlan"` AND `src/plan/plan-engine.test.ts::"compile throws AUDIO_PLUGIN_NOT_FOUND for unknown op"` AND `tests/property.test.ts::"plan compilation is deterministic"`
+
+---
+
+### Requirement: Plan-driven read and stream
+
+`PlanEngine.readPlan(doc, plan, offset?, duration?)` SHALL render a static range into `Float32Array[]` using the compiled segments. `streamPlan(doc, plan, opts?)` SHALL be an async generator yielding `Float32Array[]` blocks of at most `BLOCK_SIZE` samples that, summed, equal the requested range. `ensurePages(doc, plan, offset?, duration?)` SHALL preload any evicted pages a range requires before rendering. `AudioDocument.read()` and `AudioDocument.stream()` SHALL delegate to these methods. An out-of-range page request SHALL throw `AudioError` with code `AUDIO_CORE.PAGE_OUT_OF_RANGE`.
+
+#### Scenario: Stream yields the exact total sample count
+
+- **WHEN** a caller fully drains `streamPlan` for a known range
+- **THEN** the concatenated block lengths equal the requested sample count
+
+#### Scenario: Out-of-range read throws AUDIO_CORE.PAGE_OUT_OF_RANGE
+
+- **WHEN** `readPlan` is asked for a range beyond `plan.totalLen`
+- **THEN** it throws `AudioError` whose `code === "AUDIO_CORE.PAGE_OUT_OF_RANGE"`
+
+**Verified by:** `src/plan/plan-engine.test.ts::"streamPlan yields the exact total sample count"` AND `src/plan/plan-engine.test.ts::"readPlan throws AUDIO_PAGE_OUT_OF_RANGE beyond plan length"` AND `tests/property.test.ts::"stream yields exact total sample count"`
+
+---
+
+### Requirement: Block-level process pipeline
+
+The package SHALL export a `ProcessPipeline` class constructed from an `OpRegistry`. `init(pipeline, totalDuration, sampleRate, channels)` SHALL allocate `ProcessState[]`. `patch(state, pipeline)` SHALL hot-swap edit parameter values without re-allocating buffers. `process(input, output, state, blockOffsetSamples, sampleRate)` SHALL run each process op in order over a single block. When the pipeline structure changes between blocks (ops added or removed, detected via a pipeline signature), the pipeline SHALL reinitialise affected processors and crossfade over approximately 20 ms to avoid clicks.
+
+#### Scenario: patch updates parameters without re-allocation
+
+- **WHEN** a caller calls `patch` with the same op set but changed parameter values
+- **THEN** the existing `ProcessState[]` buffers are reused and the new parameter values take effect on the next `process` call
+
+#### Scenario: Structural change crossfades
+
+- **WHEN** an op is added to the pipeline between two `process` calls
+- **THEN** the pipeline reinitialises and the output transitions over a crossfade window rather than discontinuously
+
+**Verified by:** `src/process/process-pipeline.test.ts::"patch swaps parameters without re-allocating buffers"` AND `src/process/process-pipeline.test.ts::"structural pipeline change triggers a crossfade"`
+
+---
+
+### Requirement: Process-op error isolation
+
+When a process op throws inside `ProcessPipeline.process`, the pipeline SHALL NOT propagate the throw. It SHALL emit a `plugin:error` event carrying `{ plugin, error }` and copy the block's `input` channels into `output` unmodified, so a crashing op degrades to pass-through without corrupting the stream. Subsequent ops in the pipeline SHALL still run on the passed-through block.
+
+#### Scenario: Crashing op degrades to pass-through
+
+- **WHEN** a registered process op throws on a block
+- **THEN** a `plugin:error` event fires with the op name, `output` equals `input` for that op's stage, and the stream continues
+
+**Verified by:** `src/process/process-pipeline.test.ts::"crashing process op emits plugin:error and passes input through"`
+
+---
+
+### Requirement: Operation registry and the six plugin slots
+
+The package SHALL export an `OpRegistry` class with `register(descriptor)`, `unregister(name)`, `get(name)`, `list()`, and a static `createWithDefaults()`. An `AudioOpDescriptor` SHALL carry a readonly `name` and optional `params`, `resolve`, `plan`, `process`, `sr`, and `ch` members. Registering a descriptor whose `name` is already registered SHALL replace the prior descriptor. `createWithDefaults()` SHALL return a registry pre-populated with every built-in op.
+
+#### Scenario: register then get round-trips a descriptor
+
+- **WHEN** a caller registers a descriptor and calls `get` with its name
+- **THEN** the same descriptor is returned, and it appears in `list()`
+
+#### Scenario: createWithDefaults pre-registers every built-in op
+
+- **WHEN** a caller calls `OpRegistry.createWithDefaults()`
+- **THEN** `get` resolves every built-in plan op and process op named in this spec
+
+**Verified by:** `src/registry/op-registry.test.ts::"register/get/unregister/list manage descriptors"` AND `src/registry/op-registry.test.ts::"createWithDefaults pre-registers all built-in ops"`
+
+---
+
+### Requirement: Built-in plan operations
+
+The default registry SHALL ship these plan ops: `trim`, `crop`, `speed`, `stretch`, `reverse`, `insert`, `remove`, `repeat`, `pad`, and `resample`. Each SHALL transform the `Segment[]` so the compiled `totalLen`, `sampleRate`, or `channels` reflect the operation: `trim`/`crop`/`remove` shorten output, `repeat`/`pad`/`insert` lengthen it, `speed`/`stretch` change duration, `reverse` inverts segment order, and `resample` changes `sampleRate` via the op's `sr` transform.
+
+#### Scenario: trim restricts the output range
+
+- **WHEN** a `trim` edit selecting samples `[1000, 2000)` is compiled
+- **THEN** `plan.totalLen === 1000` and rendering yields the original samples from that range
+
+#### Scenario: resample changes the plan sample rate
+
+- **WHEN** a `resample` edit to 48000 Hz is compiled on a 44100 Hz document
+- **THEN** `plan.sampleRate === 48000`
+
+**Verified by:** `src/registry/built-in/trim.test.ts::"trim restricts output to the selected range"` AND `src/registry/built-in/resample.test.ts::"resample updates the plan sample rate"`
+
+---
+
+### Requirement: Built-in process operations
+
+The default registry SHALL ship these process ops: `gain`, `normalize`, `fade`, `pan`, `mix`, `dither`, and `transform`. Each SHALL implement a `process` function operating block-by-block on `Float32Array[]`: `gain` applies a linear multiplier, `normalize` applies peak or LUFS normalisation, `fade` applies a linear or exponential ramp, `pan` applies a constant-power stereo law, `mix` sums another document's blocks, `dither` applies TPDF dither, and `transform` applies a caller-supplied per-sample function.
+
+#### Scenario: gain scales every sample
+
+- **WHEN** a `gain` op with multiplier `0.5` processes a block
+- **THEN** every output sample equals the corresponding input sample multiplied by `0.5`
+
+#### Scenario: pan applies a constant-power law
+
+- **WHEN** a `pan` op at hard-left processes a stereo block
+- **THEN** the left channel carries the constant-power-scaled signal and the right channel is silent
+
+**Verified by:** `src/registry/built-in/gain.test.ts::"gain scales every sample by the multiplier"` AND `src/registry/built-in/pan.test.ts::"pan applies a constant-power stereo law"`
+
+---
+
+### Requirement: BlockProcessor interface
+
+The package SHALL export a `BlockProcessor` interface (`name`, `setup(config)`, `process(input, output, ctx)`, `reset()`, `dispose()`) and the supporting `ProcessorConfig` and `BlockContext` types. This is the universal DSP contract implemented by every FX, analysis, and codec-post-processing plugin across the audio family. A reference `NoopBlockProcessor` SHALL ship for tests, copying `input` to `output` unchanged.
+
+#### Scenario: NoopBlockProcessor passes audio through unchanged
+
+- **WHEN** `NoopBlockProcessor.process` runs on a block
+- **THEN** `output` is byte-equal to `input`
+
+**Verified by:** `src/process/block-processor.test.ts::"NoopBlockProcessor copies input to output unchanged"`
+
+---
+
+### Requirement: Streaming integration with @suaveplan/streams
+
+`AudioDocument.stream()` and `PlanEngine.streamPlan()` SHALL produce values composable with `@suaveplan/streams` `TransformStream`. The package SHALL expose a helper that wraps a compiled plan plus process pipeline as a `TransformStream<Float32Array[], Float32Array[]>`, so downstream FX can be appended with native stream backpressure.
+
+#### Scenario: Plan renders through a TransformStream
+
+- **WHEN** a compiled plan is wrapped as a `TransformStream` and piped to a sink
+- **THEN** the sink receives the same blocks `streamPlan` would yield directly
+
+**Verified by:** `src/stream/stream.test.ts::"compiled plan renders through a @suaveplan/streams TransformStream"`
+
+---
+
+### Requirement: Audio statistics
+
+The package SHALL export `computeStats(pages)` returning `AudioStats` (`{ peak, rms, dcOffset, lufs? }`) over a page set. `peak` SHALL be the maximum absolute sample, `rms` the root-mean-square across all channels, and `dcOffset` the mean sample value. Stats SHALL be attachable to `AudioDocument.stats`.
+
+#### Scenario: computeStats reports peak, rms, and dcOffset
+
+- **WHEN** `computeStats` runs over a known signal (e.g. a unity-amplitude sine)
+- **THEN** `peak` is `1`, `rms` is approximately `0.707`, and `dcOffset` is approximately `0`
+
+**Verified by:** `src/stats/stats.test.ts::"computeStats reports peak, rms, and dcOffset for a known signal"`
+
+---
+
+### Requirement: AbortSignal propagation
+
+`AudioDocument.read()`, `AudioDocument.stream()`, `PlanEngine.streamPlan()`, and `PlanEngine.ensurePages()` SHALL accept an `AbortSignal` via their options object. An already-aborted signal SHALL cause the method to throw `AudioError` with code `AUDIO_CORE.STREAM_ABORTED` before any page work; a signal aborted mid-stream SHALL terminate the generator at the next block boundary with the same error.
+
+#### Scenario: Pre-aborted signal short-circuits stream
+
+- **WHEN** `stream()` is called with an already-aborted signal
+- **THEN** it throws `AudioError` whose `code === "AUDIO_CORE.STREAM_ABORTED"` before yielding any block
+
+#### Scenario: Mid-stream abort terminates at the next block boundary
+
+- **WHEN** a signal is aborted after the first block is yielded
+- **THEN** the generator throws `AUDIO_CORE.STREAM_ABORTED` at the next block boundary and yields nothing further
+
+**Verified by:** `src/document/document.test.ts::"stream throws AUDIO_STREAM_ABORTED for a pre-aborted signal"` AND `src/plan/plan-engine.test.ts::"streamPlan honours mid-stream abort"`
+
+---
+
+### Requirement: Zod boundary validation
+
+Every public options object — `AudioDocumentOptions`, `AudioPage`, `AudioEdit`, `AudioStats`, `StreamOptions`, `CompiledPlan`, `AudioOpDescriptor`, `ProcessorConfig` — SHALL have a Zod schema exported from a sibling `*.schemas.ts`, and every public entry point SHALL validate its options argument against the schema before use. A validation failure SHALL throw `AudioError` with code `AUDIO_CORE.INVALID_EDIT` carrying the Zod issue list in `context`.
+
+#### Scenario: Invalid options are rejected at the boundary
+
+- **WHEN** `AudioDocument` is constructed with a negative `sampleRate`
+- **THEN** it throws `AudioError` whose `code === "AUDIO_CORE.INVALID_EDIT"` with the Zod issues in `context`
+
+**Verified by:** `src/document/document.test.ts::"constructor rejects invalid options with AUDIO_INVALID_EDIT"`
+
+---
+
+### Requirement: Structured error codes
+
+The package SHALL export `AudioCoreErrorCode`, `AUDIO_CORE_ERROR_METADATA`, and `registerAudioCoreErrorCodes()`, registering — via `@suaveplan/error`'s `defineCodes("AUDIO_CORE", …)` — the codes `AUDIO_CORE.PLUGIN_NOT_FOUND`, `AUDIO_CORE.INVALID_EDIT`, `AUDIO_CORE.STREAM_ABORTED`, `AUDIO_CORE.PAGE_OUT_OF_RANGE`, and `AUDIO_CORE.PROCESS_ERROR`. Code string values are the namespaced `NAMESPACE.REASON` form produced by `defineCodes` — never a hand-written literal. Every error thrown by the package SHALL be an `AudioError` extending `SuaveplanError` and carry one of these codes, `cause`, and `context`. Every registered code SHALL be reachable from a real call site exercised by tests.
+
+#### Scenario: Every registered code is thrown by a call site
+
+- **WHEN** the test suite runs
+- **THEN** each code in `AUDIO_CORE_ERROR_METADATA` is asserted thrown (or carried on a report) by at least one test
+
+**Verified by:** `src/error-codes.test.ts::"every AUDIO_CORE code is reachable from a call site"`
+
+---
+
+### Requirement: OpenTelemetry instrumentation
+
+The package SHALL instrument its public entry points via `@opentelemetry/api`: spans `plan.compile`, `process.block`, and `stream.read`; counters `audio_core_edits_total` and `audio_core_stream_blocks_total`; histograms `audio_core_compile_duration_ms` and `audio_core_process_duration_ms`. Instrumentation SHALL be a no-op when no exporter is registered and SHALL NOT run as an import-time side effect.
+
+#### Scenario: Instrumentation is inert without an exporter
+
+- **WHEN** the package is imported and used with no OTel exporter registered
+- **THEN** no error is thrown and no global state is mutated at import time
+
+**Verified by:** `src/plan/plan-engine.test.ts::"compile records a span and histogram when an exporter is registered"` AND `tests/purity.test.ts::"importing the package mutates no global state"`
+
+---
+
+### Requirement: Subpath exports per feature module
+
+`package.json` SHALL declare one `exports` entry per feature module (`./document/document`, `./page/page`, `./plan/plan-engine`, `./plan/segment`, `./process/process-pipeline`, `./process/block-processor`, `./registry/op-registry`, `./stream/stream`, `./render/render`, `./stats/stats`) in addition to the root `.` barrel, each resolving to a typed `import` condition. `sideEffects` SHALL be `false`.
+
+#### Scenario: Each feature module is independently importable
+
+- **WHEN** a consumer imports `@suaveplan/audio-core/plan/plan-engine`
+- **THEN** the import resolves to the plan-engine module without pulling the whole package barrel
+
+**Verified by:** `tests/exports.test.ts::"every feature module has a subpath export entry"`
+
+### Requirement: AnalysisOp operator contract
+
+The audio-core package SHALL expose an `AnalysisOp<TConfig, TResult>` operator contract that every `@suaveplan/audio-analysis-*` package implements, and a `createAnalysisOp` builder that constructs conforming operators with Zod-validated config, OTel instrumentation, and AbortSignal-aware cancellation.
+
+`AnalysisOp` is a discriminated operator with: `name: string` (unique within an analysis pipeline), `version: string` (semver), `capabilities: AnalysisCapabilities` (streaming/realtime/blocking flags), `configSchema: z.ZodTypeAny`, `run(doc: AudioDocument, config: TConfig, opts?: { signal?: AbortSignal }): Promise<TResult>`, and `runStream?(source: AsyncIterable<AnalysisFrame>, config: TConfig, opts?: { signal?: AbortSignal }): AsyncIterable<TResult>`.
+
+`AnalysisResult` is the base shape every analyser extends — `{ analyserName: string; analyserVersion: string; sampleRate: number; durationSamples: number; computedAt: number }`. Concrete analyser results add their own fields on top.
+
+#### Scenario: builder validates config via Zod
+
+- **WHEN** `createAnalysisOp({ name, version, capabilities, configSchema, run })` is called and a downstream caller invokes `op.run(doc, badConfig)`
+- **THEN** the builder MUST reject with `AudioError("AUDIO_CORE.ANALYSIS_INVALID_CONFIG")` carrying the Zod issues on `context.issues`, before `run` is invoked
+
+#### Scenario: builder instruments runs via OpenTelemetry
+
+- **WHEN** `op.run(doc, validConfig)` is called and succeeds
+- **THEN** the builder MUST emit one OTel span named `analysis.${name}` with attributes `{ "analysis.name": name, "analysis.version": version, "audio.sample_rate": doc.sampleRate, "audio.duration_samples": doc.sourceLength }`, increment counter `audio_analysis_runs_total{analysis=${name}}`, and record histogram `audio_analysis_duration_ms{analysis=${name}}`
+
+#### Scenario: builder forwards AbortSignal
+
+- **WHEN** `op.run(doc, validConfig, { signal })` is invoked and `signal.aborted === true` before `run` returns
+- **THEN** the inner `run` callback MUST observe the signal and the builder MUST surface the abort as `AudioError("AUDIO_CORE.ANALYSIS_ABORTED")`
+
+#### Scenario: capability flags advertise streaming support
+
+- **WHEN** a caller inspects `op.capabilities.supportsStream`
+- **THEN** the value MUST equal `typeof op.runStream === "function"`
+
+**Verified by:** `src/analysis/analysis-op.test.ts`
+
+### Requirement: AnalysisFrame streaming window descriptor
+
+The audio-core package SHALL export an `AnalysisFrame` shape — `{ samples: Float32Array[]; sampleRate: number; channelCount: number; startSample: number; sampleCount: number }` — usable as the streaming-input element type for any `AnalysisOp.runStream` implementation. The shape is types-only; no runtime construction helper is mandated.
+
+#### Scenario: streaming analyser consumes AnalysisFrame iterable
+
+- **WHEN** a spectrum analyser's `runStream(source, config)` is invoked with an `AsyncIterable<AnalysisFrame>`
+- **THEN** the analyser MUST process each frame independently and MAY yield zero, one, or many `AnalysisResult`-extending values per input frame
+
+**Verified by:** `src/analysis/analysis-op.test.ts::"runStream yields wrapped results and observes abort between yields"`