@denaudio/den 0.0.0-stage → 0.1.0

package/docs/oversampled-drive.md

@@ -0,0 +1,153 @@
+# Bounded oversampled memoryless drive
+
+Status: **CANDIDATE**.
+
+This is a fixed 2x/4x polyphase interpolation, memoryless waveshaper, and filtered
+phase-zero decimation composition. It is not a generic wrapper around arbitrary
+or stateful graphs, and does not create a second processing runtime.
+
+## Public entry
+
+`@denaudio/den/oversampled-drive` exports `oversampledDrive`,
+`OversampledDriveConfig`, and `OVERSAMPLED_DRIVE_LATENCY_SAMPLES = 32`.
+
+Config: host `sampleRate` finite in [8000,192000] Hz; immutable `factor: 2 | 4`;
+fixed `curve: 'hard' | 'soft' | 'asymmetric' | 'fold'`. Existing drive modules are
+not invoked at an unsupported inner sample rate. The curve is a pure arithmetic
+memoryless function evaluated at the explicit high-rate phases.
+
+`tick(input, gain, mix, reset)` once per host sample. Input intentionally clamps
+to [-8,8], linear gain to [0,32], mix to [0,1]. NaN becomes zero and infinities
+saturate. Dry uses the same sanitized input. Gain multiplies the base-rate input
+before interpolation. There is no hidden control smoothing or loudness matching.
+Mix is applied after decimation. Factor and curve cannot switch at runtime.
+Aliasing already present in the host input, or created by the host-rate gain
+multiplication, is not reversed by this interpolation stage.
+
+## Filter and phase contract
+
+For L=factor, each lowpass is N=32*L+1 taps, symmetric around D=16*L, using cutoff
+fc=0.45/L cycles per high-rate sample:
+
+h0[k] = sinc(2*fc*(k-D)) * 2*fc * Blackman(k),
+Blackman(k) = 0.42 - 0.5*cos(2*pi*k/(N-1)) + 0.08*cos(4*pi*k/(N-1)).
+
+Both endpoints are exactly zero; h=h0/sum(h0). Interpolation uses zero stuffing
+followed by L*h, evaluated as fixed polyphase sums. At high-rate index L*n+r,
+up[n,r] = L * sum_j h[r+L*j] * driven[n-j]. The memoryless curve is evaluated at
+each upsampled value. A second h filters the shaped stream, then phase-zero
+samples at high-rate L*n are retained. There is no unfiltered decimation.
+
+The linear cascade's group delay is 2*D/L = 32 host samples for both factors.
+This is bulk delay, not a requirement for silence before sample 32: the causal
+response has precursors and a 65-tap support spanning 64 sample intervals.
+Its dry counterpart is g[j] = L*(h convolved with h)[L*j], j=0..64. This is the
+exact same linear interpolation/decimation response: identical delay and
+rolloff, not merely a pure delay approximating the nonlinear path's phase.
+Mix zero therefore remains filtered and delayed; it is not transparent bypass.
+No sample-accurate constant group delay is claimed for arbitrary nonlinear
+signals, as opposed to the surrounding linear filtering.
+
+## State and bounds
+
+Native fixed rings retain 33 driven base samples, 65 dry base samples, and N
+shaped high-rate samples, plus cursors and valid counts. Reset invalidates old
+history before consuming the current host sample; no stale samples may return.
+Held reset repeatedly applies this rule. Same-schema native snapshots preserve
+all histories and phase. State scaling retains recoverable f32 subnormals.
+
+Finite FIR coefficient L1 bounds cover interpolation overshoot and dry output.
+The curve limits every shaped high-rate value to [-1,1] (asymmetric [-0.5,1]);
+therefore the wet output is bounded by sum(abs(h)). Transient overshoot above
+unity is permitted and documented, never hidden with a final output clip.
+There is no optional DC blocker or automatic limiter.
+
+## Verification coverage
+
+- Independent literal zero stuffing and time-domain convolution, including phase
+  zero versus a deliberately wrong decimation-phase counterexample
+- Symmetry, impulse support/peak, constant gain, linear dry/wet null, near-Nyquist
+  attenuation and measured anti-imaging/stopband response
+- Fixed synthetic folded-alias metrics and fundamental gain for direct versus
+  2x/4x; no universal bandlimit or monotonic audible-quality promise
+- 44.1/48/96 kHz, gain/mix changes, reset before current sample, held reset,
+  independent instances, same-schema continuation, tiny and non-finite controls
+- Maximum-factor graph/compile/WASM/memory/cost diagnostic and isolated packed
+  public declarations, actual rendering, hashes, and native parameter edits
+
+Any generated audio is **CANDIDATE**. Offline evidence does not establish browser
+quantum deadlines, maximum simultaneous instance count, or listening approval.
+
+The independent integration owner approved this bounded entry before DSP.
+Existing `/drive` and `/curve-shaper` source and semantics remain untouched.
+
+## Filter bandwidth and residuals
+
+The design's individual filter magnitude is approximately 0 dB through
+0.35*hostRate, -0.34 dB at 0.4*hostRate, -6.02 dB at 0.45*hostRate, -28.37 dB at
+host Nyquist, and -79 dB at 0.55*hostRate. The band between 0.35 and 0.55*hostRate
+is a transition, not a flat audio passband. This deliberately sacrifices high
+treble near host Nyquist to attenuate images and decimation aliases.
+
+The base-rate linear response must be computed from g, not assumed to be exactly
+one filter's squared magnitude: finite residual image terms survive the
+interpolation/decimation cascade. In particular the mirrored transition term
+matters at host Nyquist. The per-phase interpolator's constant-input gain ripple
+is about 1.7e-6 before shaping. Finite filters and a finite internal sample rate
+leave residual aliases. Increasing factor alone does not make arbitrary driven
+waveforms bandlimited, restore existing aliases, or guarantee better perception.
+
+For the specified kernels, sum(abs(h)) is about 1.853 at 2x and 1.847 at 4x.
+The matched dry kernel has L1 norm about 1.879, so an arbitrary bounded dry input
+can reach a conservative 15.04 transient bound. This is a stability bound, not
+a recommended signal level. Wet output may also exceed unity because of the
+post-shaper FIR. No final clip masks those filter transients.
+
+## Measured candidate evidence
+
+The 11 focused tests render actual native WASM at 44.1,48,96 kHz. All fixed
+curves and both factors match an independent literal zero-insertion/high-rate
+convolution reference at f32 precision for the tested input, gain, mix and reset
+sequences. That oracle does not use the implementation's polyphase indices or
+precomputed dry kernel. A deliberately wrong decimation phase differs enough to
+fail the same oracle. Linear dry/wet null, symmetric impulse peak at 32, nonzero
+precursors, exact finite tail drain, resets, same-schema continuation, independent
+silent instances, invalid controls and recoverable tiny impulses are checked.
+
+A 1001-point frequency sweep of the independently generated individual FIR
+finds maximum passband magnitude error below 0.000167 through 0.35*hostRate, and
+stopband attenuation at least 75.27 dB from 0.55*hostRate to the internal Nyquist.
+This is the stated guardband, not a promise of that rejection immediately above
+host Nyquist. The native convolution-oracle checks also bind the implementation
+to this filter design.
+
+Alias fixtures use 8192-frame coherent sines at bins 997 and 1709, amplitude 3,
+after a complete period of warmup. Projection removes DC and harmonics below
+host Nyquist; the residual is measured without loudness normalization. Across
+all four curves at the three rates, folded RMS falls 13.75–27.78 dB at 2x and
+29.98–48.63 dB at 4x versus direct shaping. The requirements remain 6 dB and 10 dB
+respectively. Fundamental amplitudes are recorded separately, and are preserved
+to about 5e-5 absolute amplitude in these specific fixtures. Different inputs,
+gain modulation, and frequencies can produce different outcomes.
+
+`tests/oversampled-drive-packed.test.mjs` installs the actual tarball into a locked
+isolated consumer. Strict public declarations, native a-rate gain/mix writes,
+all 24 factor/curve/rate combinations, independent convolution, exact native
+snapshot continuation, tail drain and source/package/audio hashes are required.
+Whole offline-renderer output must exactly equal the manually driven native WASM
+instance, rather than a recreated JavaScript processor.
+
+The public maximum-factor candidate has at most about 0.44 MB of serialized
+graph, 52,391 bytes of WASM, and fixed 65,536-byte WASM memory per instance in the
+fixture. Timings are recorded separately from correctness: local process medians
+are below one millisecond in these runs, but cold quanta have exceeded 19 ms.
+The cold cost alone rules out claiming a verified browser deadline. These are
+single-instance local Node diagnostics with host jitter and no input/output copy
+or browser scheduling cost. No real-time capacity, browser worklet, device,
+true-peak, or listening approval is implied.
+
+Use the normal native construction API, for example
+`instantiate(oversampledDrive, {sampleRate, factor:4, curve:'soft'}, {name:'drive'})`,
+then call `tick(input, gain, mix, reset)` inside the enclosing `forSample`.
+The 32-sample bulk-delay constant is useful when designing a chain, but the full
+matched dry response remains necessary for this module's own linear null.

package/docs/performance.md

@@ -0,0 +1,53 @@
+# Bounded performance candidates
+
+Status: CANDIDATE. Catalog §4 extension; existing `voicePolicy`, instrument, presets and MIDI runtime are unchanged. This is not general MPE support, hardware validation, real-time acceptance or human-approved sound.
+
+## Public surface
+
+`@denaudio/den/performance` exports `performancePolicy`, `pitchGlide` and `tunedFrequency`, plus their TypeScript control/configuration types. Use existing unworklet 0.4.1 native MIDI, AudioParams and snapshots.
+
+`performancePolicy({mode, capacity, heldCapacity, legato})` composes the existing allocator. Mono requires one voice; poly defaults to four, maximum four. The held-identity ledger defaults to eight, maximum eight, and must be at least voice capacity. Methods are `bindMidi(input)`, `reset(when)`, `overflowed()`, and `voices[]`. Each voice retains `read()`, `takeRetrigger()` and `releaseFinished(done)` and adds `takeReset()` for a latched DSP-clear pulse. `read()` adds normalized `channelPressure`, `polyPressure`, `bend`, `timbre` and boolean `sustain` lanes. Bind once in declaration scope. Do not also bind the wrapped allocator.
+
+### Identity, sustain and cleanup contract
+
+- Each accepted positive-velocity note-on creates one bounded channel/key identity. FIFO note-off pairing is with the oldest physically-down matching identity, including stolen identities. Velocity-zero note-on is note-off.
+- With sustain down (CC64 >=64), note-off marks that identity physically released but keeps it held in the original allocator. Its gate stays high and it retains held-note allocation priority. The allocator still prefers free voices, then ordinary released voices, then steals the oldest held voice, which can be a pedal-held voice.
+- Pedal-up releases deferred identities in their original note-on order, oldest first. Ordinary nondeferred key releases take effect immediately. Mono therefore keeps the original last-held-note priority among physically-held and pedal-held identities; pedal-up may fall back to another held note without retrigger when legato is true.
+- Repeated same-key identities remain separate. A pedal-held older identity does not consume a later physical note-off twice. Pedal-up forwards exactly one oldest allocator note-off for each deferred identity. Stolen identities stay tracked until their own release, preventing a stale note-off from releasing a newer duplicate.
+- A full ledger rejects new positive note-ons and latches overflow. It never evicts an accepted held identity. MIDI 1.0 cannot identify a late note-off belonging to a rejected duplicate, so FIFO pairing remains explicit. Reset clears overflow; per-channel cleanup does not clear the global diagnostic.
+- CC123 marks all physically-down keys on its channel released. Pedal-down defers them; pedal-up releases them. It does not change expression or pedal state.
+- CC120 immediately clears that channel's keys and active/releasing voices, sets its pedal up and latches `takeReset()` for slots that were using that channel. It retains other expression controls. Mono may fall back to a different channel's held key, following the original allocator policy. The DSP-clear latch belongs to the physical slot and must be consumed by composition code before sounding any replacement there.
+- CC121 centers bend, clears channel pressure, timbre and that channel's active poly-pressure values, raises its pedal and releases its deferred identities. Physically-down notes stay held.
+- `reset(true)` clears every held identity, allocation, pedal and expression lane, pending retrigger and overflow, and latches every slot's DSP reset. Held reset repeatedly clears. `reset(false)` leaves state unchanged. Ordering follows graph invocation; a composition wanting panic to win over same-quantum MIDI must invoke reset after MIDI dispatch at the start of process, as the example does.
+- Release completion is forwarded to the original allocator only after the current envelope is done. Sustain-held notes cannot be freed by a stale completion because their allocator owner remains held. Completion must describe the current slot envelope; callers must not reuse completion from a previous owner.
+
+### Expression contract
+
+- Pitch bend 0..16383 maps to -1..1, center 8192 maps to exactly zero. Negative values divide by 8192; positive values divide by 8191. Bend range is a composition choice in semitones.
+- Channel pressure and CC74 timbre normalize 0..127 to 0..1 and persist per channel until updated, CC121 or reset. They affect held and releasing voices on that channel.
+- Native `aftertouch` is polyphonic key pressure. It updates all currently active matching channel/key voices, including release tails. Pressure received before a matching voice exists is ignored. New assignment/retrigger clears that slot's poly pressure; a mono legato pitch/channel change also clears it. Another same-key voice's existing pressure is preserved until the next matching aftertouch message. This is key-addressed expression, not a distinct-note MIDI 2.0 identifier.
+- Inactive voice expression outputs are zero. Unsupported controllers and message families are ignored. CC74 is a raw timbre lane; this module does not invent a destination or smoothing rule.
+- unworklet 0.4.1 drains MIDI in FIFO order before each 128-sample process quantum. This layer preserves that timing. Several changes in a quantum coalesce to the final assignment and latched start/reset flags. It does not implement sample-accurate MIDI scheduling.
+- Every performance/held-key/expression state slot is native transient state. A snapshot excludes held notes/pedals/controllers. Fresh-instance restoration starts from their declaration defaults; in-place native restore preserves their current values rather than clearing them. For a cold live restore, explicitly reset the allocation/expression/DSP composition after restoring and render a quantum before new notes. DSP composition must reset inactive voices to prevent an orphan envelope tail.
+
+## Glide and tuning contract
+
+`pitchGlide({sampleRate}).tick({target,seconds,reset,snap})` returns MIDI-note semitones. Supported construction rates are integer 8000..192000 Hz. Finite target is clamped to [-128,255], finite seconds to [0,30], duration is floor(seconds * sampleRate + 0.5). The first call snaps to target. A changed target starts a new constant-time linear glide from the last emitted value; a change during a glide replaces its destination and duration. The first step is emitted on the change sample and step N is the exact endpoint. Zero/sub-half-sample durations snap. Seconds changes without a target change do not retime the current glide. `snap` and `reset` are level-sensitive and follow the current target immediately while held; releasing them does not invent a new glide. Native persistent state resumes exactly at the same sample rate. Different-rate snapshot restoration is outside this candidate contract.
+
+`tunedFrequency({note,transpose,cents,a4}, maxFrequency)` is a stateless 12-TET mapping: A4 × 2^((note−69+transpose+cents/100)/12), with note [-128,255], transpose [-48,48], cents [-1200,1200], A4 [220,880]. maxFrequency is a finite positive construction value no greater than the largest finite f32 value. The combined musical exponent is calculated before the single final frequency clamp. Controls must be finite. The bounded conversion uses degree-12 f64 exp(x/32) polynomial arithmetic and five squarings. Native 0.4.1 pow and exp both demote through an approximate f32 bridge; the independent tuning oracle caught this path's 0.05–0.098 Hz error before replacement. The independent oracle's threshold was preserved.
+
+## Candidate evidence
+
+- Native receiver entry passes at 44.1/48/96 kHz, including channel pressure, aftertouch, pitch bend and CC. An event scheduled at sample 129 is observed at boundary 128, demonstrating the native quantum timing rather than claiming sample timing.
+- 33 focused tests cover closed-form interrupted glide, duration latching, held reset/snap, tiny signed pitch, tuning and AudioParam automation, independent object/queue FIFO identity and sustain oracle, all controller cleanup paths, capacity/overflow, mono legato owner changes and same-key pedal/off orders. The combined focused and unchanged allocator/envelope/instrument regression run passes 94 tests.
+- The isolated packed consumer imports only public subpaths and typechecks strictly. At all three rates it renders the existing envelope and sine oscillator, checks held-pedal release, bend, pressure and timbre, and compares against independent Math.sin and linear-envelope equations. A separate chord exercises all four active voices. Tuning and automation outputs match the independent f32 oracle; all runs report zero scrubbed samples.
+- Performance state is absent from snapshots, while the composed envelope/oscillator/glide state is persistent. Restoring a snapshot from a sustained note into a fresh offline instance produces exact silence; a fresh note after that restore restarts safely. This does not establish clearing of an already live browser instance. The pitch-glide primitive separately proves exact same-rate continuation.
+- The maximum declared four-voice/eight-identity diagnostic composition compiles to 747,451 WASM bytes with 65,536 bytes of memory, unchanged across 256 driver blocks. This is a local fixed-memory check, not a timing or hardware acceptance claim.
+
+The packed gate retains source/package/lock hashes, exact source commit and dirty-state flag, per-rate numerical results, and CANDIDATE status in its manifest. The first source-development packed run measured maximum audio error below 1.5e-8; subsequent clean-head results are in the generated manifest/result pair.
+
+The composition's choices are deliberately explicit: two-semitone bend range; normalized channel/poly pressure maximum scaled to amplitude 0.5..1; CC74 scaled to amplitude 0.5..1; gain 0.2; instantaneous attack/decay; a parameterized linear release; and sine source. These are diagnostic values and routing, not an approved preset. Pitch and frequency intermediates are materialized to bound the unworklet graph. Existing instrument and voice-policy behavior is unchanged.
+
+## Remaining boundaries
+
+This policy does not implement MPE. The separate `/mpe-expression` entry adds a manually configured lower-zone expression subset; full MPE zone/pedal/RPN behavior remains outside both contracts. No hardware MIDI-host integration, browser-rate expansion, real-time CPU budget, acoustic/listening approval, cross-rate snapshot migration or approved golden is claimed. The full integrated catalog gate remains the integration owner's responsibility.

package/docs/pitch-quantizer.md

@@ -0,0 +1,55 @@
+# Octave-periodic musical pitch quantizer
+
+`@denaudio/den/pitch-quantizer` exports `pitchQuantizer`, `PitchQuantizerConfig`, and `PitchQuantizerOutput`. This is the catalog group 5 musical-quantize candidate. It quantizes a pitch-control signal using native unworklet 0.4.1 DSP. It does not detect pitch in audio, tune an audio recording, quantize event timing, or deliver MIDI to a host.
+
+## Construction and use
+
+```ts
+import { instantiate } from '@unworklet/core';
+import { pitchQuantizer } from '@denaudio/den/pitch-quantizer';
+
+// Inside defineProcessor, outside forSample:
+const quantizer = instantiate(pitchQuantizer, {
+  pitchClasses: [0, 2, 4, 5, 7, 9, 11],
+  hysteresis: 0.125,
+}, { name: 'cMajor' });
+
+// Inside forSample, exactly once per sample:
+const result = quantizer.tick(pitchControl, reset);
+// result.pitch is f32; result.degree and result.octave are i32.
+```
+
+Pitch uses semitones on the MIDI-coordinate axis: 60 is C4; negative and fractional controls are valid. Each allowed pitch is `12 * octave + pitchClasses[degree]`. `octave` is that integer multiplier, not a printed musical octave number. For example, pitch 60 has octave multiplier 5. To transpose a scale, prepare its transposed offsets in `[0,12)` before construction. No tuning file loader, tonic control, Hz conversion, gate policy, or scale-name registry is included.
+
+- `pitchClasses`: 1 through 128 numbers. Entries must be finite in `[0,12)`, including after conversion to IEEE f32. The module copies, f32-rounds, and sorts them ascending. Exact duplicates and duplicates after rounding, including 0/-0, are rejected. The input order has no musical meaning; returned degree indexes the sorted canonical list. A value just below 12 that rounds to 12 is rejected rather than silently wrapping.
+- Fractional and microtonal offsets are supported, including representable f32 subnormals. This is not restricted to twelve-tone equal temperament. Offsets finer than f32 precision round to the same value and therefore cannot be distinct degrees. The period remains exactly twelve semitones; non-octave-repeating tunings are outside this module.
+- `hysteresis`: optional finite number in `[0,12]` semitones, default 0, converted to f32. It is a construction-time margin, not a time constant. Positive values smaller than the least positive f32 round to 0. Scale structure and margin cannot be changed through a per-sample control.
+- Invalid construction inputs throw `RangeError`. These bounded inputs control graph size; no callback-time array allocation or arbitrary JavaScript execution is used.
+
+## Nearest, precision, and invalid controls
+
+On every sample, NaN input maps to pitch 0. All other inputs, including infinities, clamp to `[-16384,16384]`. Quantization then searches the scale; the output itself is not clipped to that range. For example, offset `[6]` can produce pitch 16386 from input 16384. This preserves scale membership at the input-domain endpoints.
+
+Without hysteresis, choose the candidate with the smallest native binary64 absolute distance from the sanitized f32 input. Computed distance equality chooses the lower computed binary64 pitch. If different degrees collapse to that same binary64 pitch, the lower sorted degree index wins. Each class compares the distances of its two bracketing octaves; a midpoint shortcut would not preserve this computational tie policy for all tiny controls. The result is then converted to f32. Thus arithmetic and output rounding are explicit parts of the contract; this is not arbitrary-precision tuning. Fractional degrees that differ in their construction values can produce the same f32 output at a large octave, and exceptionally tiny offsets can also collapse during binary64 octave arithmetic.
+
+The chosen degree and octave are retained as integer state, never reconstructed from the rounded output. They are returned along with pitch, so callers can inspect the selected scale identity even where two f32 output pitches coincide. Internal distance/pitch staging uses exact power-of-two scaling to preserve subnormal f32 values through unworklet 0.4.1's scalar-state denormal floor.
+
+## Hysteresis, reset, and rate
+
+For positive margin `h`, the current degree remains selected while the sanitized input is within the inclusive interval
+
+`[(previousPitch + heldPitch)/2 - h, (heldPitch + nextPitch)/2 + h]`.
+
+Previous and next mean adjacent entries in the periodic sorted scale, including across an octave boundary. Bounds are evaluated as binary64 local-degree midpoints plus the integer octave base. Both boundary equalities retain the held degree. Outside the interval, the result jumps directly to ordinary nearest for the current input; it does not walk one scale degree per sample. For large margins, several neighbors can be passed before a change. A one-degree scale uses the same degree in adjacent octaves as its neighbors.
+
+The first call and every reset-high sample ignore history and emit ordinary nearest immediately. Holding reset high therefore continues to quantize moving input, rather than muting output or pinning one pitch. The next reset-low sample starts hysteresis from the last reset-selected degree. At margin 0, every sample uses ordinary nearest, including its lower-pitch tie policy; there is no history-dependent tie retention.
+
+There is no smoothing, event queue, lookahead, clock, time constant, or sample-rate-dependent state. Call once per sample of the chosen control stream. The same trajectory has the same result at 44.1, 48, and 96 kHz. Existing unworklet snapshots restore degree, octave, initialization, and internal staging state; no new serialization API is introduced. Different named instances have independent state.
+
+## Evaluation and limitations
+
+The source tests exercise native rendering against an independent exhaustive local lattice rather than copying the per-class search. Coverage includes signed octaves, scale/octave midpoints and adjacent f32 values, input clamp endpoints, NaN/infinities, one-note and microtonal scales, subnormal offsets, f32-output collapse, duplicate-after-rounding rejection, maximum 128-degree capacity, hysteresis equality and leaps, held reset, and exact snapshot continuation. The isolated packed-consumer gate additionally checks public TypeScript declarations, package resolution, actual native rendering at 44.1/48/96 kHz, zero scrubbed samples, and fixed memory.
+
+Work per sample and captured graph size are linear in the fixed degree count. All candidates are evaluated; this is not a promise of automatic control-rate scheduling. No browser/hardware real-time acceptance, auditory approval, note-host delivery, adaptive tuning, or perceptual pitch quality is claimed. Test and audition artifacts remain CANDIDATE.
+
+Scope source: [den catalog, group 5](https://app.notion.com/p/3ef449b4e81d817db1acf1fff48779b3). The numerical policy above is this implementation's explicit bounded interpretation of musical quantize, not a feature-equivalence claim about a referenced product.

package/docs/prepared-convolution.md

@@ -0,0 +1,188 @@
+# Prepared-spectrum convolution candidate
+
+`@denaudio/den/prepared-convolution` exports `preparedConvolution`, the host-only
+`prepareConvolutionSpectrum`, and `PreparedConvolutionConfig` /
+`PreparedConvolutionPacket`. This is an offline-validated **CANDIDATE**, without
+browser, realtime-capacity or human-audition clearance.
+
+## Fixed boundary
+
+- Mono, block size B=128, FFT N=256, P=64 partitions. Configuration must be exactly
+  `{ blockSize: 128, partitions: 64 }`; unsupported configurations throw.
+- Original IR: 1..8192 finite real taps, each in [-1,1], with absolute sum <=4.
+  No normalization, truncation, sample-rate conversion or output limiter.
+- Audio input must be finite and normalized to [-1,1]. Output can exceed unity.
+- Nominal latency is 128 samples: 2.902 ms at 44.1 kHz, 2.667 ms at 48 kHz,
+  1.333 ms at 96 kHz. IR leading zeros and its own tail are additional.
+- Maximum original IR duration is 185.76 / 170.67 / 85.33 ms at those rates.
+  This is a bounded cabinet/body/short-space candidate, not arbitrary long-IR
+  room convolution. The existing small `partitionedConvolution` is unchanged.
+- The nominal target is original direct FIR delayed by B. Quantized spectra
+  introduce small bounded circular/padding leakage, so exact onset/support
+  zeros and exact original-IR gain are not promised after quantization.
+
+## Host preparation and native delivery
+
+Call `prepareConvolutionSpectrum(impulse, config)` outside audio processing.
+Accepted inputs are arrays, Float32Array or Float64Array. Invalid input/config
+and excessive reconstruction error throw RangeError; the helper never changes
+IR gain to make an asset pass.
+
+The returned native packet contains:
+
+| Field | Value |
+| --- | --- |
+| formatVersion | 1 |
+| blockSize | 128 |
+| partitions | 64 |
+| impulseFrames | Original integer length, 1..8192 |
+| declaredValues | 32768 |
+| spectrum | Float32Array, exactly 32768 values |
+
+Bin k of partition p starts at `2*(p*256+k)`, real then imaginary. Forward sign
+is `exp(-i*2*pi*k*n/256)`, without normalization. Each original partition has
+128 taps followed by 128 zeros. Unused partitions are zero. Preparation enforces
+conjugate symmetry, exact zero DC/Nyquist imaginary components, and Float32
+rounding. The returned packet remains mutable: send it **unchanged**.
+
+The caller explicitly declares a native event and forwards its graph payload:
+
+```ts
+import { CAPACITY_16, event, instantiate } from '@unworklet/core';
+import {
+  preparedConvolution, type PreparedConvolutionPacket,
+} from '@denaudio/den/prepared-convolution';
+
+const convolver = instantiate(preparedConvolution,
+  { blockSize: 128, partitions: 64 }, { name: 'convolver' });
+const ir = event<PreparedConvolutionPacket>({
+  from: 'main', name: 'ir', capacity: CAPACITY_16, payloadCapacity: 131072,
+});
+ir.onReceive(packet => convolver.load(packet));
+// Inside stride-1 forSample: convolver.tick(input, reset, everyNSamples).
+```
+
+No event, loader, acknowledgement or asset-file abstraction is created by the
+module. The caller uses existing native host message facilities and owns IR
+sample-rate conversion. Native transport can truncate oversized typed arrays:
+validate type and length before enqueueing. The independent declaredValues
+field detects accidental truncation only when it truthfully states original
+length; it cannot authenticate a forged packet.
+
+The native handler checks format/capacity/frame count/decoded length and scans
+all 32768 components for NaN, infinity and abs(component)>4. This is malformed
+number protection, **not** inverse-domain IR/L1/symmetry/provenance validation.
+Correctness and error claims require the unchanged host-prepared packet.
+
+## Approximation certificate
+
+Host preparation independently reconstructs each quantized partition through a
+direct inverse DFT over all 256 samples. It sums absolute real error from the
+original zero-padded partition plus absolute imaginary residual over every
+partition/sample, adds a 1e-8 host numerical guard, and rejects above 4e-6.
+The numerical guard is conservative relative to the measured modulo-reduced
+host DFT error; this is not a formal cross-engine bound on JavaScript Math.
+
+For any output block phase, the two overlapping input blocks select complementary
+halves of each circular error impulse. With |input|<=1 their total error is at
+most that partition's reconstruction L1 error. This includes quantized padded-
+half leakage and circular wrap, rather than assuming those values remain zero.
+The independent test also checks the looser spectral estimate
+`2B * sum_p(max_k(complexMagnitude(deltaH[p,k])))`.
+
+A Float32 quantization sanity estimate from Parseval/Cauchy-Schwarz is
+`sqrt(N)*2^-24*sum_p(L1(partition[p]))`, at most 3.815e-6 for N256/L1<=4,
+plus the absolute subnormal term `P*sqrt(2*N)*2^-150` (about 1.02e-42).
+The per-asset inverse-domain certificate remains the actual rejection gate.
+
+Native arithmetic/history/FFT/products/OLA use Float64, coefficients use
+Float32, and input/history are scaled by exact 2^128 to preserve signed
+subnormal audio against core 0.4.1's tiny-state flushing. Output is Float32.
+Tiny IR coefficients can quantize to zero; **no relative tiny-IR accuracy** is
+promised. A preparation certificate is not a proof of native arithmetic error.
+
+Acceptance tests separately target native-vs-quantized-operator absolute error
+<1e-6 and original-FIR error <5e-6. These are measured test targets, **not a
+universal total-error guarantee**. Corresponding 4.000005 gain headroom is a
+practical test budget, not a proven bound for every implementation/environment.
+
+## Load, reset, state and scheduling
+
+`tick(input, reset, everyNSamples)` returns `{ output, loaded, rejected,
+revision }`. Call it once per sample inside stride-1 native forSample. This
+implementation requires the core 0.4.1 128-sample quantum.
+
+- Valid full packet: loaded=true, rejected=false. A shorter IR still carries
+  the complete padded 32768-value table, so previous coefficients are replaced.
+- Explicit unload: matching format/B/P, impulseFrames=0, declaredValues=0 and
+  empty Float32Array. loaded=false, rejected=false.
+- Malformed load: loaded=false, rejected=true; no prefix is accepted as an IR.
+- Every load attempt, including rejection/unload, increments wrapping i32
+  revision. Compare for inequality rather than ordering. Do not round-trip
+  revision through an f32 audio channel if exact i32 identity matters.
+- Every attempt invalidates old input/spectrum history and OLA tail without
+  resetting cursor/hop phase. A valid load accepts the next audio sample.
+- Reset keeps the IR and revision, discards its own input sample, invalidates
+  history/tail and preserves phase. Held reset is silent. Release resumes with
+  nominal B latency. Reset never causes sample-scheduler rephasing.
+- Missing/unloaded/rejected assets are silent. Invalidation is logical, not
+  secure erasure; bytes may remain in buffers/snapshots until overwritten.
+
+FFT+64-partition MAC+IFFT+OLA run eagerly once every 128 samples, including while
+unloaded. Indices are explicit; native counted loops avoid graph expansion by
+P*N. B equals quantum size, so the dispatch phase is identical at every native
+snapshot boundary. Named persistent cursor, spectral cursor, valid counts,
+coefficients/status/revision, histories and overlap fully describe continuation.
+Same-graph/config/rate native snapshots continue bit-identically. Pending queued
+messages, cross-configuration migration and live-swap crossfades are outside
+this contract. Transient FFT/mix buffers are overwritten before use.
+
+## Loading and resource costs
+
+The native coefficient table is 128 KiB, complex input history 256 KiB, and
+16-slot native payload ring 2 MiB. Scratch/history/OLA, scalar state and I/O add
+more; use the complete packed profile for actual fixed WASM memory.
+Sixteen queued loads copy 2 MiB and scan 524288 coefficient components at one
+boundary. Preparation allocates host arrays and performs direct DFT/certificate
+work outside the callback. Native copy/scan occurs during audio message dispatch,
+not outside the callback. Preload with audible playback gated off. postMessage
+fallback may allocate. No allocation-free-loading, realtime live-swap or
+concurrent-instance capacity claim is made.
+
+The public core driver has no message-ingress method. The packed profile
+therefore reports unloaded full-loop cold/warm quantum cost separately from
+loaded one-quantum `renderOffline` end-to-end cost for 0/1/16 queued packets.
+End-to-end includes instantiate, enqueue, copy/scan, DSP, I/O and snapshot; it is
+not an isolated handler measurement. Do not infer audio deadline clearance from
+those timings. Complete measured numbers are recorded with exact source and
+package hashes in the packed artifact manifest.
+
+## Evidence
+
+- Three-rate focused tests: full8192 impulse tails, dense original FIR,
+  independent quantized circular operator, complex transfer, superposition,
+  all128 reset offsets/rate, held reset, malformed→unload→short replacement,
+  wrapped i32 revision and signed subnormal input.
+- 24 focused and 21 packed bit-identical snapshot continuations across
+  load/reject/unload/short replacement and reset states; zero output scrubs.
+- Separate native Float32 full-capacity entry and host precision probes retain
+  independent assertions. The earlier Float64 failure is preserved as a manual
+  red reproduction: core 0.4.1 payload.length seals the field as Float32 even
+  after Float64 copy, reporting twice the intended element count. No upstream
+  dependency patch or byte reinterpretation is used.
+- Packed public typecheck, actual native-message render and Vite worklet build.
+  Test audio is CANDIDATE; no human approval or browser realtime clearance.
+
+The preliminary packed gate passed in16.23 s (759 MB process-group peak RSS).
+At48 kHz its fresh local profile recorded26,747-byte WASM and2,555,904 bytes
+fixed memory, including the2 MiB payload ring. Unloaded full-loop cold quantum
+was2.063 ms; startup maximum4.218 ms; warm512-quantum p50/p99/max including
+I/O copies was0.142/0.539/2.141 ms. Dense8192-tap host preparation was58.6 ms.
+The16-load one-quantum offline end-to-end median/max was6.244/11.178 ms.
+These measurements include host jitter and do not establish an audio deadline
+guarantee; in particular the startup maximum exceeds the48 kHz deadline.
+
+Packed three-rate original-FIR error was2.235e-8 and full impulse error5.372e-9.
+The first focused run passed all14 tests in24.15 s with677 MB process-group peak RSS.
+Measured dense original-FIR error was1.027e-9, native-vs-quantized operator
+8.808e-10, superposition2.329e-9, complex transfer6.597e-8 at all three rates.

package/docs/realtime-audition.md

@@ -0,0 +1,63 @@
+# Sustained audition deadline regression
+
+The manual `node scripts/probe-realtime.mjs` command builds its own isolated
+packed consumer before capture. It does not require or alter public `site-dist`,
+and it does not restore the removed public audition page. The capture modes and
+assertions below are unchanged.
+
+The first browser tests proved sample values and lifecycle behavior, but did not prove that an AudioWorklet could produce those samples on time. In particular, waiting only for AudioContext time lets an overloaded renderer eventually finish and hides wall-clock drift. This gap allowed a numerically correct sustained sine to crackle during real playback.
+
+## Reproduction and isolation
+
+At reviewed frontend head `5d42072`, the audition compiled to 1,122,834 bytes of WASM. In this execution environment, warmed native WASM calls over 128-frame blocks measured a median 2.82 ms and p95 8.90 ms, exceeding the 48 kHz budget of 2.667 ms. A real Chromium capture took about 8.09 wall-clock seconds for five seconds of graph output and reported 839 playback underrun events. The raw graph samples remained continuous. Disabling waveform drawing did not remove the problem; a separate native sine context could render without underruns. The independent reviewer also reproduced excessive AudioWorklet process cost and phase-dependent stalls with depth zero.
+
+This isolates a deadline failure in the composed DSP, rather than a phase reset in its sample sequence. The published 0.4.1 arithmetic emitter recursively emits child expressions; retaining a Node in a JavaScript variable does not materialize its computed value. The repeated polynomial/squaring expressions used by pitch modulation amplify the composed expression tree. Explicitly materializing the subgraph boundaries reduces emitted size and processing cost while preserving samples. This is a den composition fix, not an upstream patch or a claim that every compiler path has been audited.
+
+The fix stores envelope level, LFO output and final pitch in three existing unworklet f32 transient state slots, then reads each later in the same sample. It adds no sample delay, custom state mechanism, preset or routing system. Each subgraph still ticks once per sample. The independent sine-times-envelope error remains 8.15e-8. WASM becomes 34,679 bytes; a warmed run measured p50 0.109 ms and p95 0.199 ms. These are measurements on this runner, not guarantees for every physical device or the future polyphonic instrument.
+
+The final regression harness was also run against the unchanged `5d42072` audition source: its native control recorded zero underruns, while den windows recorded 589/588/594/592 events and took 6.1–6.4 seconds for five seconds of samples. It exited with `full: real-time underrun events` (589 != 0). Restoring the materialized source passed the same checks.
+
+## Regression check
+
+`tests/realtime/audition.test.mjs` builds an isolated packed production consumer and runs after the existing numerical and packed/browser tests, rather than competing with them for CPU. The packed test files run serially because each invokes the shared package prepack build; concurrent TypeScript writes can otherwise race tarball reads. It uses a test-only native AudioWorklet recorder with preallocated storage and no per-quantum allocations. The recorder does not replace the production DSP or transport.
+
+Each capture warms the recorder for one audio-clock second, then collects 240,000 real-time samples (five seconds at 48 kHz). Conditions are: native sine reference, den held tone with UI, LFO modulation, repeated parameter changes, and UI drawing disabled. Existing audition tests separately cover touch release/cancel, repeated Start/Stop, unavailable contexts and asynchronous startup.
+
+For every den window and its conservative delayed-observation interval, the test requires zero new playback underrun events and zero underrun duration, five seconds of output within 5.5 wall-clock seconds, no consecutive zero samples, bounded adjacent/quantum-boundary steps, and a fitted 220 Hz sine residual below 1e-6 for unmodulated windows. Native oscillator results are recorded as an environment control; its implementation is not den's numerical contract. A warmed 1,000-block native WASM cost probe additionally requires p95 below half the quantum budget. Unsupported playback statistics fail the test instead of silently substituting offline evidence.
+
+Raw capture precedes device fallback, so continuous samples alone cannot rule out crackling. `AudioContext.playbackStats` checks that separate playback layer. Recorder allocations initially caused small measurement artifacts, and native controls sometimes exposed host scheduling noise; the committed recorder avoids per-block array views. Neither existing sample tolerances nor expected audio have been relaxed.
+
+`artifacts/realtime/current` is cleared at test start and holds fresh raw f32 files, actual browser version, playback statistics, wall/audio timing, continuity results and source/audio hashes. Each completed window is saved immediately; the manifest is written before assertions and on failure, including capture errors. CI uploads the scoped artifacts directory even when checks fail. A Node-side 15-second bound on each capture ensures a stalled worklet reaches teardown. The capture endpoint is taken on buffer reception before converting samples to a JavaScript array; conversion time and post-conversion statistics are recorded separately for both native and den windows. Immediate counter snapshots are not treated as final evidence. It is CANDIDATE evidence, never an approved golden. The unchanged production transport remains unworklet's postMessage fallback where cross-origin isolation is absent; no headers, protection settings, permissions or credentials change. Stop still closes the context, consistent with the risk described in upstream #81; each build runs in a fresh process, avoiding the repeated-build cache scenario in #101. Those reports are not being claimed as newly reproduced here.
+
+Physical iOS/Android playback and human listening still require verification. This regression covers Chromium's actual 48 kHz real-time path and does not establish 44.1 kHz browser support or full-instrument CPU capacity.
+
+## Materialization contract limits
+
+All existing AudioParam declarations, names, ranges and automation rates are unchanged. Each new scratch slot is f32, transient and unpublished; the envelope/LFO/oscillator persistent slots retain their names and types. Writes precede reads within the same sample and every scratch value is overwritten before use, including after restoration. A separate dynamic probe changed frequency, rate and depth, then released the envelope: old/fixed PCM and split-render same-schema continuation were bit-identical. Snapshot inspection excluded all three scratch slots.
+
+Transient declarations still change unworklet's schema hash: `31f5b44c3627df618038170d9b2af9be` becomes `34898cbf87b8f22e8754fff7b664da5d`. Version 0.4.1 falls back to name-matched restoration when no migration exists; this specific old-to-new continuation also matched exactly, but arbitrary cross-schema compatibility remains unsupported by den's entry contract. No preset migration framework is added.
+
+This technique is not a blanket rewrite rule for arbitrary subgraphs: moving a read across a state write can change semantics, storing f64 intermediates into f32 loses precision, and existing unworklet state stores flush magnitudes below 1e-30 to zero. Here the materialized boundaries already return f32, with the audition's bounded normal-range controls. Future instrument/filter/delay compositions must establish their own ordering, precision, restoration and real-time evidence. The modules themselves are unchanged.
+
+## Remaining sporadic browser underruns
+
+The sustained old-graph overload is reproducibly removed, but some local Chromium runs still report isolated playback underruns. Raw captured samples remain continuous; that does not disprove playback-layer fallback. A fixed three-round native/den × recorder/no-recorder comparison had no underruns or container CPU throttling, and a separate traced run had GC activity without underruns. Conversely, a later capture using the pre-conversion endpoint recorded five native-reference events and one den held-tone event, with unchanged immediate counter snapshots across array conversion. Because counters update asynchronously, those snapshots cannot exclude events reported later. These observations do not establish a browser-version, GC, recorder or host-scheduling cause. Preserve failed runs alongside successful CI evidence; do not waive the zero-underrun assertion or infer universal device clearance.
+
+## Delayed playback statistics
+
+The [Web Audio stats update algorithm](https://webaudio.github.io/web-audio-api/#updating-the-stats) updates counters once per second while running and visible. Reading them only at buffer delivery can miss a terminal underrun. The harness keeps the context running, polls every 100 ms, and requires `totalDuration - underrunDuration >= captureEndAudioTime`, after at least 1.25 seconds of observation. Observation is bounded at four seconds; stale or unavailable counters fail with the complete poll history saved. The outer 15-second capture deadline still bounds stalled page/worklet execution.
+
+The raw sample/wall-time window remains five seconds. The zero-underrun assertion conservatively includes the interval from the baseline's last reported counters through the delayed final counters; this may include pre-capture reporting lag and post-capture rendering/result handling. No late event is automatically attributed to conversion or discarded. Every observation retains wall time, audio time, covered audio time, visibility and counters.
+
+A test-only 100 ms stall on the final recorded quantum of a native sine produced zero immediate events but nine delayed events (0.09018 seconds) in the local probe. The counterexample uses the same observation logic and requires the normal zero-underrun assertion to reject the capture. Fault audio is labeled separately from candidate audio. Passing earlier immediate-only checks does not establish end-of-window playback correctness.
+
+## Independent LFO frequency assertion
+
+The LFO capture also measures positive zero-crossing periods. An independent
+least-squares fit of log-frequency against 4 Hz sine/cosine bases verifies the
+0.5-semitone modulation depth, carrier and residual while allowing arbitrary LFO
+phase at capture start. A plain 220 Hz signal cannot pass. The offline packed
+fixture applies the same oracle to nonzero depth and requires zero depth to be
+rejected. Disabling depth in a separate copy of the audition composition makes
+that packed render fail specifically at the pitch-depth assertion. This adds a
+numerical check without changing DSP, continuity thresholds or expected audio.