@denaudio/den 0.0.0-stage → 0.1.0

package/docs/resident-recorder.md

@@ -0,0 +1,151 @@
+# Resident take recorder candidate
+
+Status: **CANDIDATE / NOT_CLEARED**. Catalog §3 describes sample/live-buffer
+sources, fixed-capacity storage, and read/write competition. This module adds a
+bounded native take writer that composes with the existing sample readers.
+It is not a microphone permission layer, recorder application, rolling history,
+overdub looper, streaming engine, or realtime/listening approval.
+
+## Entry and scope
+
+Import `residentTakeRecorder`, `ResidentTakeRecorderConfig`,
+`ResidentTakeRecorderControls` and `ResidentTakeRecorder` from
+`@denaudio/den/resident-recorder`. Instantiate once inside a native processor:
+
+```ts
+const take = instantiate(residentTakeRecorder,
+  { capacity: 65536, sampleRate: ctx.sampleRate }, { name: 'take' });
+const player = instantiate(samplePlayer,
+  { sampleRate: ctx.sampleRate, sample: take.sample, loop: true },
+  { name: 'player' });
+// In forSample, call the writer once, then the readers, in the intended order.
+const status = take.tick({ input, record, reset });
+```
+
+Capacity is an integer in 1–65,536 mono source frames, immutable after graph
+construction. `sampleRate` is the incoming processor rate, finite 8–192 kHz.
+The maximum take lasts about 1.486 s at 44.1 kHz, 1.365 s at 48 kHz, or 0.683 s
+at 96 kHz. Changing the configured rate does not resample input. There is no
+hidden monitor output: route the original input separately if monitoring is
+wanted. All recording and reading is graph-native unworklet 0.4.1.
+
+## Sample-accurate write contract
+
+- Initially length and revision are zero, and reads are missing/silent.
+- `record:true` appends exactly one frame if length is below capacity.
+  `record:false` pauses without changing any exposed PCM or length.
+- At capacity, recording stops without wrap or overwrite. Dropping and raising
+  record does not start another take. Reset is needed to start at frame zero.
+- `reset:true` has priority, sets length and loaded-prefix boundary to zero and
+  suppresses recording. It increments the wrapping i32 revision on every held
+  reset tick. A still-high record resumes on the first non-reset tick.
+- `tick` returns `{written,full,length}` for this tick after the operation.
+  `written` includes recording a silent or sanitized frame. `full` is true on
+  the tick that writes the final frame; no extra input is accepted thereafter.
+- Call `tick` exactly once per incoming sample. Native statement order controls
+  visibility: a read before `tick` sees the prior take, and a read after sees
+  the completed append/reset. PCM is stored before length is advanced; no
+  partially initialized frame becomes exposed. There is no inter-thread reader
+  or concurrent host-write contract.
+
+There is no circular overwrite, so frame zero stays frame zero until reset/load.
+The valid frame age can be computed from the current length; paused time does
+not add frames or silence. This is a growing finite take, not a continuously
+advancing live history with a moving read/write safety margin.
+
+## Existing sample reader compatibility
+
+`take.sample` implements the unchanged `ResidentSample` interface. It can be
+passed directly to `samplePlayer`, `multisamplePlayer` and `granularSource`.
+The direct `read` has the existing bounded linear interpolation, slice, looping,
+NaN-position and nonfinite-tap policies; the inaccessible sentinel cannot be
+selected by a reader. Interpolation spans a loaded-prefix/recorded-suffix
+boundary normally.
+
+`sample.load(data)` is the existing native Float32Array event-boundary operation:
+it replaces the take, truncates to capacity, sets length to that truncated
+length, and increments revision. Empty data logically unloads. Subsequent
+recording appends after the loaded prefix. If load and record occur in the same
+quantum, native message dispatch installs the prefix before the audio ticks;
+reset at the first tick can still empty it. No decoding, file/device I/O, new
+transport, acknowledgement or serializer is added. Follow the input budgeting,
+preload and callback-copy limitations in [sample.md](sample.md).
+
+Appending does not change revision. Existing readers observe the growing length
+on each call/tick rather than a frozen initial bound. In particular, loop period
+grows, and grains whose positions move within the newly valid region can read
+it. A one-shot that already became inactive does not revive just because length
+grows. For stable loop/grain boundaries, stop recording before playback.
+Reset/load changes revision and invalidates existing playback/grains under
+their normal contract; a held player gate is not a fresh trigger. Trigger/gate
+and read/write order remain explicit responsibilities of the composition.
+
+## Amplitude and bounded storage
+
+Core 0.4.1 scalar buffer stores flush magnitudes below 1e-30. Direct f32 recording
+would therefore discard some representable signal values. This candidate uses:
+
+1. `loadedPCM`: C f32 frames, populated only by native event `copyFrom`.
+2. `recordedPCM`: C+1 f64 frames, recording `f64(input) * 2^128`.
+3. `loadedPrefixLength`: the native i32 boundary selecting the loaded prefix or
+   recorded suffix. Reset makes it zero; load makes it the new take length.
+
+Exact power-of-two scaling keeps every finite nonzero f32 input above the native
+store floor and below f64 overflow. Readers divide by the same factor. It is a
+storage encoding, not audio gain/normalization: decoded finite values retain
+their amplitude, including maximum f32 and the smallest f32 subnormal. Signed
+zero records as positive zero. NaN and ±Infinity record as zero, without relying
+on the output scrubber. Event-loaded invalid values are independently sanitized
+at read taps, matching the original resident sample.
+
+The extra recorded frame is an unreachable sentinel. Paused/full/reset ticks
+write only zero there. Native `select` evaluates both branches, so using a
+sentinel avoids accidentally rewriting any exposed sample. Both buffers are
+persistent; buffer storage is exactly `12*C + 8` bytes, 786,440 bytes at maximum
+capacity, plus three i32 persistent states, transient read position, normal
+runtime/IO overhead, and any caller-created ingress ring. Both read branches
+are evaluated; the split costs two bounded memory reads per interpolation tap.
+
+Reset and short/empty replacement are **logical invalidation, not secure
+erasure**. Unreachable loaded/recorded tails remain in snapshots until later
+overwritten. No growing allocation or clearing pass occurs per reset. Native
+snapshots include both buffers, length, loaded-prefix boundary and revision;
+the transient read-position cache is excluded. Exact continuation is promised
+only for the same graph, configuration and sample rate. It is not a portable
+audio-file format or an arbitrary live-restore guarantee.
+
+## Evidence and limits
+
+`tests/resident-recorder.spec.ts` compares every output sample against an
+independent scalar oracle at 44.1/48/96 kHz. Coverage includes pause/full/held
+reset, pre/post-write reads, prefix-to-suffix interpolation, short/empty/oversize
+replacement, capacity one/65,536, f32 extremes/subnormals/nonfinite input,
+inaccessible sentinel and unchanged loaded bytes, growing player/granular
+composition, wrapping revision and exact snapshots.
+
+`tests/resident-recorder-packed.test.mjs` installs the real tarball into an
+isolated locked consumer, checks public TypeScript, renders native DSP against
+the independent oracle, verifies same-schema snapshot continuation, and builds
+the actual Vite worklet/WASM at 48 kHz. Manifests retain exact source, tarball,
+consumer-lock, rendered audio and build hashes. The consumer audio is original
+synthetic signal, **CANDIDATE**, without normalization or a limiter.
+
+The separate `tests/capture-freeze-browser.test.mjs` requires actual 48 kHz
+worklet recording, deterministic native capture limits, pause/full-stop,
+existing-player readback, prefix/suffix interpolation and native PCM/history
+restoration. It uses synthetic graph input; no microphone or device is opened.
+This browser stage must pass on the exact final head before merge.
+
+Offline multirate success, worklet build and actual browser execution are separate
+evidence. There is no device capture, listening approval, realtime deadline,
+seamless take transition, antialiasing, long-form recording or streaming claim.
+Core's non-48-kHz browser loader restriction remains unchanged.
+
+Live core 0.4.1 restoration copies DSP state before restoring host AudioParam
+values. Old record/reset/player controls can therefore act on restored state
+before the saved controls arrive. The browser fixture first renders the saved
+record, play, input, limit, position and reset controls, then restores the take.
+The earlier already-full-buffer pass masked the write hazard and is not general
+atomic-restore evidence. Browser playback checks are functional PCM/readback
+checks; phase-aligned quantum continuation is separately tested offline. See the
+[observed frozen-tail restore boundary](freeze-reverb.md#live-browser-restore-ordering).

package/docs/resident-time-stretch.md

@@ -0,0 +1,190 @@
+# Bounded resident WSOLA time stretching
+
+Status: **CANDIDATE**, catalog §11. `residentTimeStretch` from
+`@denaudio/den/resident-time-stretch` changes resident mono duration independently
+of grain-local pitch. It is a waveform-similarity overlap-add (WSOLA) variant with
+fixed sparse comparison points. This is not a renamed two-head live pitch delay,
+a phase vocoder, formant preservation or a transparent general-purpose stretcher.
+
+## Entry, native ownership and cost
+
+Instantiate with `sampleRate: ctx.sampleRate` (integer 8000..192000), an existing
+`ResidentSample`, `hopSamples: 128 | 256` (default 256) and
+`searchFrames: 0 | 8 | 16 | 32 | 64 | 128` (default 64). H is the synthesis hop in
+output frames; the two overlapping source grains each span 2 H output frames.
+S is the search radius in source frames. Neither scales automatically with rate.
+At 48 kHz the default window spans 10.67 ms and search±64 spans±1.33 ms; these are short
+creative windows, especially for bass, speech and complex/polyphonic material.
+
+The asset remains bounded to 1..65536 mono f32 source frames with a fixed
+integer source rate 8000..192000 Hz, using the existing native resident ingress. See [sample.md](sample.md)
+for delivery, truncation, revision, RAM and callback-copy caveats. Decode and
+validate PCM outside audio processing, preload with audible playback gated off,
+and establish the delivery boundary before starting. There is no new loader,
+streaming path, JS-rendered audio, external WASM or unworklet modification.
+
+Call `tick(controls, everyNSamples)` once per sample inside stride-1 native
+`forSample((i, everyNSamples) => ...)`. This module allocates 64 f64 transient
+comparison values (512 bytes), fixed scalar state and no length-dependent output
+buffer. Resident PCM and ingress allocation are shared, not copied per instance.
+Sixteen maximum ingress slots reserve 4 MiB, plus 256 KiB resident PCM.
+
+The graph uses bounded native counted loops, not expanded code per PCM frame or
+search candidate. Every 128 output samples it evaluates 64 reference reads and
+(2 S+1)×64 candidate comparisons; each comparison uses zero-padded linear sampling.
+H256 commits only alternate evaluations. This eager 128 scheduling, including
+when stopped, is deliberate: unworklet 0.4.1's native hop counters are not snapshot
+state, whereas the module's persistent H clock is. Muting/gate-off does not remove
+search cost. S0 still evaluates the zero-offset baseline. Maximum S128 means
+16,448 comparisons per 128-sample quantum; there is no average-cost CPU-saving claim.
+
+## Controls, launch and transitions
+
+Controls are `{ gate, trigger, reset, durationScale, pitchRatio }`.
+
+- Gate rise or true trigger requests a launch at the next global H boundary,
+  with 0..H−1 samples of request waiting. Controls latch at actual launch, not at
+  the request sample. Gate must remain high. A held trigger restarts every hop.
+- `durationScale` and `pitchRatio` must each be finite f32 in [0.5,2]. Both latch
+  for the whole run; edits alone do nothing. Invalid controls reject that launch,
+  clear its request and leave any already-running playback intact. There is no
+  implicit clamp, smoothing or fallback transposition.
+- A launch resets source/output time to 0. Its first H-sample grain is direct,
+  without an artificial fade-in. Later boundaries use overlap. Launch/retrigger
+  can click. The resident is read with zero padding on both ends; no loop or
+  reverse mode is supplied.
+- Gate-off cancels immediately without release/tail. Reset cancels and silences
+  its current sample and clears pending launch, EOF and rejection. Held reset
+  stays silent; a still-high gate requests a new launch after release.
+- Reset does not rephase the global hop. A resident revision immediately cancels
+  playback and pending launch. A gate already held high does not silently start
+  the replacement, although a new trigger in the same sample can request it.
+  Empty/unloaded assets are missing/silent.
+
+## Exact time, search and sample law
+
+Let L be the loaded source length, R the output rate, Rs the fixed source rate,
+D the accepted durationScale and P the accepted pitchRatio. A launch has exactly
+T=ceil(L×R/Rs×D) active output samples, n=0..T−1. The logical source position is
+n×L/T. Thus requested duration rounds upward by less than one output frame, and
+pitch never changes T. The largest permitted T is 3,145,728 output frames.
+Fractional resident source rates are rejected by this module, without changing the residentSample API.
+
+Duration is an exact rational ceil for integer rates and the accepted f32 D.
+The implementation splits L×R×(D×2^24) into exact small integer products and
+compares their integer part/remainder to a nearby quotient, avoiding a pre-rounded
+rate quotient or an epsilon adjustment. The independent scalar oracle uses
+BigInt rational arithmetic. The regression L=147 / Rs=44100 / R=48000 has exactly
+80/160/320 samples at D=0.5/1/2; the original pre-rounded-rate calculation wrongly
+produced 81/161/321 and is preserved in the initial review evidence.
+
+Grain-local sampling advances q=P×Rs/R source frames per output sample. At each
+later synthesis hop the new nominal grain start is n×L/T, independent of P. The
+previous grain continues from its selected start plus Hq. Alignment compares that
+previous tail with candidate starts nominal+d, where integer d is 0,±1,…,±S.
+Each candidate's score is the sum of squared differences at 64 positions
+j×H/64, j=0..63, using the same q. Baseline d=0 is first, then +1,−1,+2,−2,…;
+strictly smaller cost wins, so exact ties prefer the smallest absolute offset,
+then the positive offset. S0 is ordinary overlap-add without alignment.
+
+At local output index k=0..H−1, output is
+(1−k/H)×previousTail[k] + (k/H)×newHead[k]. First-hop output is newHead[k]. Each
+endpoint outside [0,L) is zero, including fractional intervals [−1,0) and [L−1,L).
+Indices are explicitly clamped before resident access; padding is not endpoint
+hold, accidental index wrap or stale PCM reuse. EOF outputs silence exactly from
+n=T onward, with no post-EOF overlap tail. A late grain may encounter padding
+before EOF, so active duration does not imply nonzero PCM at every active sample.
+For the 8192-frame, 1/128-cycles/source-frame cosine fixture at D=2/P=2, a late
+256-frame region peaks near 0.309 instead of the 0.5 interior amplitude. This is
+retained edge attenuation, not corrected by hidden normalization.
+
+Interpolation and overlap weights are convex. Peak is bounded by the largest
+absolute finite resident PCM value (within floating rounding), and supported
+constant interiors retain unity gain. There is no loudness/peak normalization,
+limiter, clipping or implicit dry mix. Nonfinite PCM taps become zero through the
+resident contract. Internal exact binary scaling by 2^192 avoids the native tiny
+scalar-store scrub during sample/error accumulation. Even the 64-term score for
+opposite finite f32 extrema is below 2^649, safely finite in f64; this scaling does
+not alter audio gain or relative candidate scores.
+
+Return values are `{ output, active, position, ended, pending, rejected, missing,
+selectedOffset }`. `active` refers to the current output sample, including zeros.
+`position` is the current logical n×L/T, held at L after EOF; it is not either
+aligned readhead's position. `ended` becomes true on the first EOF sample and
+stays true until reset/replacement/new launch. Early gate-off does not set EOF.
+`rejected` retains the latest launch result until another attempted launch/reset.
+`selectedOffset` is the last committed hop's integer d. Rejected and selectedOffset
+are diagnostics, not proof that any output was audible.
+
+All launch/clock/time/grain/EOF and resident state use native persistent snapshots;
+comparison, score and output scratch are transient. Restoration is bit-identical
+only for the same graph, configuration, resident metadata and rate, at the native
+quantum boundaries. In particular, H256 halfway-hop and pending launches must
+continue exactly after a 128-aligned snapshot. No serializer or migration layer is
+introduced.
+
+## Audible and acceptance limits
+
+Linear interpolation is not bandlimited. Pitch-up aliases original source
+frequencies above R/(2 P) Hz, or R/(2 P Rs) cycles per source frame.
+Interpolation images/attenuation remain below that limit. All pitch/formants move
+together, and input frequencies above the destination Nyquist can alias even at
+P1 when source/output rates differ.
+
+Sparse waveform matching can choose an unsuitable periodic alignment. Its 64
+comparison points do not represent every output sample. Limited S cannot align
+long periods or all components of a polyphonic signal. Linear crossfades can
+cancel, amplitude-modulate and color tones, especially without alignment; grains
+can duplicate, omit or smear transients. Short input and both padded edges receive
+only partial windows, and EOF may truncate a window/transient abruptly. No
+speech/consonant preservation, stereo coherence or artifact-free claim follows.
+Use a separate envelope/crossfade if a click-free articulation is required.
+
+The algorithm is an original bounded implementation of the waveform-alignment
+idea described in Driedger and Müller, [A Review of Time-Scale Modification of
+Music Signals](https://www.audiolabs-erlangen.de/content/resources/MIR/00_PCD_AudioLabs/2016_DriedgerMueller_TSMOverview_AppliedSciences_ePrint.pdf),
+2016, §4. Their descriptions explain the method/tradeoffs, not this implementation's
+quality or performance. No third-party implementation was copied.
+
+Verification covers independent scalar source-time/search results and independent
+analytic duration/carrier checks at 44.1/48/96 kHz, arbitrary-PCM unity, mismatched
+source/output rates, short and zero-padded boundaries, invalid controls/nonfinite
+PCM, finite extremes/subnormals, launch/reload/reset/EOF and same-schema exact
+snapshot continuation. Packed public import/types, actual native ingress/render,
+fixed memory, graph/WASM cost and candidate audio are separate evidence. Every
+render is CANDIDATE; no approved golden is replaced. There is no human-listening,
+browser/hardware realtime deadline, host integration or full catalog acceptance.
+
+Initial max-size feasibility (65536 frames/H256/S128, local Node 24) measured
+296,328 graph bytes, 50,051 WASM bytes, 4,521,984 native bytes and 640 ms compile.
+Twenty unloaded quanta observed 43.3 ms cold and 2.42 ms warm maximum. These include
+an eagerly evaluated search even though the resident was unloaded; they do not
+prove loaded/device performance. The cold quantum greatly exceeds the tested audio
+budget, and 2.42 ms already exceeds the 1.33 ms budget at 96 kHz. Later packed diagnostics
+must be read alongside this retained observation, not substituted for a guarantee.
+
+Independent review retained a dominant-frequency counterexample: a 997.13 Hz
+source at 32000 Hz, output 44100 Hz, L=16384, H128/S128 and D=1.75/P=1.25 produces
+an interior Hann-window spectral peak near 1248.1625 Hz instead of the nominal
+1246.4125 Hz, a +1.75 Hz deviation. Sparse, integer-offset waveform alignment can
+shift the dominant output frequency as well as color its amplitude. The separate
+437.3 Hz test's <=0.75 Hz result describes only its measured rate/control matrix;
+it is not a universal tuning tolerance. P specifies the exact local grain read
+slope, not an artifact-free global spectral-peak guarantee.
+
+
+Further independent measurements strengthen these limits. The same 997.13 Hz
+source/control case at 96000 Hz output has a dominant peak near 1249.4125 Hz,
++3 Hz from the nominal 1246.4125 Hz. The spectral peak is not guaranteed to track
+P to a universal tuning tolerance.
+
+For the 48000 Hz, L=8192, period-128 cosine at D=2/P=2 and H256/S64, the intended
+750 Hz Hann-window carrier amplitude over output frames [15360,16128) is about
+0.00145034, versus about 0.499999997 in the interior. The last nonzero output is
+frame 16159 although the active duration ends at 16384. This is padded-edge
+cancellation/distortion and loss of intended-carrier energy, not merely a
+uniform gain reduction. The earlier late-region peak near 0.309 therefore must
+not be read as preserved pitch/tone quality at the edge. No gain compensation
+is applied. Exact logical duration and local read slope do not guarantee
+transparent duration/pitch output, preserved tail content or completed
+catalog time-stretch quality.

package/docs/sample.md

@@ -0,0 +1,191 @@
+# Resident sample, multisample and granular candidates
+
+Status: **CANDIDATE**. These are bounded DSP building blocks for catalog §3.
+No listening approval, bandlimited claim, browser/host delivery proof, streaming,
+asset loader, hardware latency or real-time deadline guarantee is implied.
+
+## Public entry and ownership
+
+Import `residentSample`, `samplePlayer`, `multisamplePlayer`, `granularSource`
+and their configuration/control types from `@denaudio/den/sample`. Create named
+subgraph instances with native `instantiate`. One resident sample can be shared
+by multiple readers; player/grain state is private to each instance.
+
+A resident is **mono**, has a fixed capacity of 1–65,536 f32 frames and a fixed
+source rate in [8,000,192,000] Hz. Its current loaded length is independent of
+capacity. Each player's `sampleRate` is its processor's `ctx.sampleRate`.
+Decoding, channel selection/downmixing and finite-PCM validation belong in the
+caller, outside audio processing. Channel/rate changes require a newly configured
+resident; there is no embedded file format or mutable sample-rate metadata.
+
+Use the existing native ingress, for example:
+
+```ts
+const sample = instantiate(residentSample,
+  { capacity: 65536, sourceSampleRate: 48000 }, { name: 'sample' });
+const load = event<{ data: Float32Array }>({
+  from: 'main', name: 'load', capacity: CAPACITY_16,
+  payloadCapacity: sample.capacity * Float32Array.BYTES_PER_ELEMENT,
+});
+load.onReceive(({ data }) => sample.load(data));
+```
+
+Validate bytes/frames on the sending side. Send at most the declared capacity,
+and handle native transport overflow/rejection. In the verified native offline
+path, a typed-array payload larger than the per-slot budget is silently truncated
+before `load` sees it; `length()` then reflects that truncated input. Do not rely
+on transport rejection to validate a full asset. The DSP `load` itself truncates
+an input longer than the resident to capacity; an empty input unloads. A shorter
+replacement leaves unreachable bytes in the fixed buffer but all readers clamp
+to the new length, so old data cannot leak into playback. The unused tail remains in native snapshots
+until overwritten; replacement/unload is logical invalidation, **not secure erasure**.
+
+**Loading is not callback-free.** `Buffer.copyFrom` is a bounded native
+`memory.copy` in the process message-dispatch phase, before that quantum's audio
+samples. Prepare/decode outside the callback, preload with playback gated off,
+and start audible playback only after the delivery boundary is established by
+the host. There is no new loader or acknowledgement protocol here. The
+postMessage fallback can allocate on the audio thread; offline tests do not
+establish live transport safety.
+
+Specify `CAPACITY_16` explicitly. Core 0.4.1 allocates the payload budget once per
+ring slot: at the maximum resident size, 16 × 65,536 × 4 = 4 MiB for the payload
+ring, plus 256 KiB PCM and small ring/state overhead. Multiple ingress/resident
+pairs multiply this budget. Sixteen distinct maximum-capacity residents, each
+with its own 16-slot ingress, reserve 64 MiB payload + 4 MiB PCM before ring/state
+overhead; that bank is materially more expensive than 16 zones sharing one resident
+(4 MiB payload + 256 KiB PCM). Simultaneously queued full loads also copy 4 MiB
+into the bank at a boundary and are unsuitable for an unmeasured audible reload.
+The native default ring has 256 slots and would use
+64 MiB payload space for that same capacity. Capacity is not an allocation-free
+loading claim or a recommended live reload size.
+
+PCM, loaded length and revision are persistent native snapshot state. The revision
+increments as a wrapping i32 on every load, including empty input. Readers compare
+for inequality, not ordering, so signed/unsigned wrap preserves invalidation.
+The bounded 16-message ring cannot wrap the whole 32-bit revision between adjacent
+audio ticks. Snapshots promise exact continuation only for the **same graph,
+configuration, resident metadata and rate**; they are not a portable sample bank
+format or cross-configuration migration contract.
+
+## Playback and slices
+
+`samplePlayer({ sampleRate, sample, startFrame?, endFrame?, loop?, releaseFrames? })`
+accepts `tick({ gate, trigger, reset, rate })` and returns
+`{ output, active, position, missing }`.
+
+- Slice boundaries are construction-time frame indices `[startFrame,endFrame)`.
+  The end intersects the loaded length; an empty intersection is missing/silent.
+- `rate` is a signed ratio clamped to [-16,16]. The increment is
+  `rate * sourceSampleRate / sampleRate`. Zero holds; negative starts at `end-1`.
+  Rate changes while playing change direction/speed without repositioning.
+- Gate-rise or a true trigger while gate is high starts/restarts. Trigger is
+  level-sensitive, so holding it repeats the initial sample. Reset has priority;
+  held reset is silent, then a still-high gate restarts on the next tick.
+- Linear interpolation explicitly wraps the second tap at the loop boundary.
+  One-shot interpolation holds the final frame until the phase exits `[start,end)`.
+  No index relies on unworklet's automatic wrap. Length 0/1 is defined and bounded.
+- Gate-off applies a linear `releaseFrames` ramp; the first off sample subtracts
+  `1/releaseFrames`, so release 1 stops immediately. Default 0 stops immediately.
+  Natural one-shot exhaustion stops independently. Use an envelope for a richer
+  articulation law. `active` describes the current emitted sample, including a
+  zero PCM value; it does not predict whether the next sample is active.
+- Replacement invalidates the current playback. A gate held high does not
+  silently restart a new asset; a fresh gate-rise/trigger can start it. A load and
+  fresh trigger in the same quantum use the newly copied asset.
+- Nonfinite rates use bounded fallback/saturation; NaN means zero speed.
+  Nonfinite PCM taps become zero individually, without poisoning reader state.
+  Fractional position/control state uses exact binary scaling internally to avoid
+  the native scalar-store flush below 1e-30; finite extreme PCM is not reduced to
+  a ±1-only assumption. Tiny/subnormal controls are tested against full finite PCM.
+- Public resident `read(position,start,end,loop)` also intersects end with loaded
+  length. Non-loop out-of-range positions hold the nearest valid endpoint; it is
+  not a zero-padded reader. Direct frame positions saturate to the signed i32 index range, with NaN
+  selecting start; start/end are i32 nodes. The player/granular methods maintain
+  their own tighter phase/control bounds. Player/grain activity masks enforce their own silence.
+
+Loop interpolation smooths fractional lookup but **does not make a discontinuous
+loop seamless**. For an explicit tail/head overlap, use the separate
+[crossfaded loop candidate](loop-crossfade.md), whose effective period is shortened
+from `L` to `L-F`. `samplePlayer` itself is unchanged. Automatic zero-crossing search,
+time-stretching, bandlimited rate conversion and seamless dynamic asset replacement
+are not provided. A high-frequency sine played at double rate demonstrably aliases.
+
+## Multisample mapping
+
+`multisamplePlayer({ sampleRate, zones, releaseFrames? })` accepts
+`tick({ key, velocity, gate, trigger, reset, rate })` and returns
+`{ output, active, zoneIndex, missing }`.
+
+There are 1–16 fixed zones. Each specifies `sample`, integer `keyLow/keyHigh`,
+normalized `velocityLow/velocityHigh`, integer `rootKey`, optional `tuneCents`
+(±2,400), `gain` (±4), and optional slice/loop configuration. All endpoints are
+inclusive; the first matching zone wins overlaps. Inputs clamp to MIDI 0–127 and
+velocity 0–1; fractional keys are supported for transposition inside a zone.
+
+Zone, key and velocity latch at note-on. Root-key tuning multiplies the rate by
+`2 ** ((key-rootKey)/12 + tuneCents/1200)`, then the player limits the final signed
+ratio to ±16. Output gain includes latched velocity × zone gain. No match returns
+zone -1/missing/silence. A matching but unloaded sample remains the selected missing
+zone; there is no hidden fallback. A new note resets other zone players, so this is
+a **monophonic selector**, not a polyphonic allocator or release-tail mixer.
+Clipping/limiting is not implicit; zone gain can exceed unity. Preserve f32
+headroom when applying gain: extreme finite PCM multiplied by a gain above one
+can overflow the output type; the raw-resident finite-range proof is not an
+unbounded-gain guarantee.
+
+## Granular source
+
+`granularSource({ sampleRate, sample, maxGrains, seed?, loop? })` accepts
+`tick({ gate, reset, positionFrames, jitterFrames, rate, durationSeconds, densityHz })`
+and returns `{ output, activeGrains, onset, dropped, missing }`.
+
+- Fixed pool of 1–32 grains. First free slot wins; a full pool drops the onset
+  instead of stealing a grain or allocating memory. Density is limited to
+  0–2,000 Hz. Gate-rise creates an initial grain even at zero density.
+- Position and uniform signed jitter are in source frames. Jittered start clamps
+  into the loaded asset. Signed pitch rate and source/host conversion match playback.
+  Position, rate and duration latch at onset; later controls affect new grains.
+- Duration rounds to the nearest output frame, bounded to 3 frames–2 seconds.
+  The triangular window is `max(0,1-abs(2*age/(duration-1)-1))`, exactly zero at
+  both endpoints. This is not a Hann window or a constant-overlap-add guarantee.
+- `seed` is an integer 1–2,147,483,646. Park–Miller 48,271 modulo 2,147,483,647
+  advances for every scheduled onset, including a dropped onset. Reset restores
+  the seed; snapshot restore preserves it and every grain. Repeatability is for
+  identical controls/rate/configuration. The oscillator/noise PRNG is not reused.
+- Scheduling phase is f64. Nominal onset times can round by one output sample at
+  nonintegral periods; this candidate is not a host musical clock or event output.
+- `loop:true` wraps each grain within the whole resident. `loop:false` masks
+  reads outside the asset to zero. Gate-off stops scheduling while existing
+  windows finish; reset or asset replacement cancels all existing grains.
+- Sum is divided by configured `maxGrains`, not active count. This gives a simple
+  overlap bound for finite bounded PCM and avoids changing gain as grains appear,
+  but sparse pools are correspondingly quieter. It is not loudness normalization.
+
+Bounded [take recording](resident-recorder.md), [rolling history](live-buffer.md),
+[live grains with explicit write-age/expiry rules](live-granular.md), and
+[loop crossfades](loop-crossfade.md) are separate public candidates. The live
+history is not a ResidentSample and must not be cast into this reader. Stereo
+grains, broader spectral sources and host streaming remain outside this contract.
+
+## Evidence and acceptance
+
+The native-ingress probe and `tests/sample.spec.ts` use synthetic original
+impulse/ramp/sine PCM, independent numeric references, 44.1/48/96 kHz playback,
+missing/short/empty replacement, finite controls, exact snapshot continuation,
+zone boundaries, seeded grain onset/window/drop and explicit alias evidence.
+Maximum resident/ring allocation and maximum pool/zone checks are separate from
+a hardware performance claim. Packed-consumer evidence is produced by
+`tests/sample-packed.test.mjs`; its manifests and audio are always CANDIDATE.
+No existing approved audio baseline is replaced.
+
+Maximum capacity is a functional offline bound, not a recommended live preset.
+`makeProcessor({ zoneCount: 1, grainCount: 4 })` in the isolated consumer is a
+modest composition for separate browser acceptance; its graph holds the fixture
+clock/gates until native loaded length is nonzero, so delayed delivery cannot
+consume the audition before PCM arrives. The maximum fixture uses
+16 zones and 32 grains. Per-module 1/4/32-grain and 1/16-zone measurements are
+reported separately. The public compile driver cannot inject load messages, so
+these timing diagnostics explicitly start unloaded and must not be presented as
+audible-pool/device performance. The actual loaded offline renders separately
+prove maximum grain activity, PCM, onset/drop and continuation behavior.

package/docs/sound-audition-headroom.md

@@ -0,0 +1,103 @@
+# Integrated sound audition: numerical headroom
+
+Status: **CANDIDATE**. Offline numerical checks do not clear the real-time gate,
+constitute human listening approval, or authorize production deployment.
+
+## Scope and reproduction
+
+`tests/integration-consumer/sound-matrix-render.mjs` runs in the isolated consumer
+installed from `npm pack`, using public `@denaudio/den/instrument` and
+`@denaudio/den/delay-fx` imports. `tests/integration.test.mjs` invokes it after the
+existing diagnostic renderer, which remains unchanged. No package DSP, public
+sound settings, gains, or normalization are altered by this audition.
+
+At 48 kHz it renders all four instruments through diagnostic delay, Chorus, and
+Rhythmic Delay. Each source runs through the FX defaults, dry mix, and maximum
+wet mix with feedback 0.5. The ten source traces produce 90 stereo FX rows:
+
+- Every displayed note at MIDI velocity 127, followed by note-off, retrigger
+  during release, and verified exact source silence after the final release.
+- The main hold button for every instrument, including each polyphonic chord.
+- Overlapping notes and last-held-note return for the mono instruments.
+- Four coherent, same-pitch voices at **every displayed pitch** for Diagnostic
+  and Pad, followed by release. This is stronger than the UI's velocity 100.
+- Pad holds exceed its 0.8 s attack + 1.2 s decay + one complete 8.333... s LFO
+  period. This applies separately to the chord and every coherent pitch.
+- Live FX history between register steps and six additional seconds after each
+  complete trace, exposing accumulated echoes and release tails.
+
+The traces contain 205.848 seconds of source audio. The initial standalone run
+completed in about 93 seconds on the cloud executor. This is test duration, not
+real-time performance evidence.
+
+The script writes `integration-sound-matrix.json`, including all settings, MIDI
+events, time windows, source/output peak and RMS, output headroom, release/end-tail
+measurements, scrub/nonfinite/clipping counts, reference errors, and bounds. It
+also writes twelve `sound-matrix-{instrument}-{effect}.wav` files: main-button
+holds at each FX's defaults, unnormalized at Master 1, with SHA-256 hashes.
+These files are listening **candidates**, never expected audio or golden files.
+
+## Independent checks and bound
+
+Each FX sample is compared with an independent unbounded-timeline delay oracle.
+The oracle uses a direct-form bilinear biquad rather than the production
+circular buffers and state-variable-filter recurrence, and evaluates the
+Chorus modulation and stereo phase separately. Maximum sample error is limited
+to `6e-6`; the observed worst error was `2.1909363568e-6`.
+
+Every render must have zero scrubbed samples, zero nonfinite output, and zero
+samples at or above full scale. Dry output must be bit-identical to its source.
+Deliberately clipped, nonfinite, and above-ceiling fixtures verify that the
+numerical guards reject invalid material.
+
+The test first enforces explicit per-instrument **source regression ceilings**:
+
+| Instrument | Source ceiling | Rationale |
+| --- | ---: | --- |
+| Diagnostic | 0.20001 | Four 0.05-gain voices, small numerical margin |
+| Bass | 0.24 | Twice the 0.12 raw gain allows resonant/transient overshoot |
+| Percussion | 0.16001 | One 0.16-gain voice, small numerical margin |
+| Pad | 0.18001 | Four 0.045-gain voices, small numerical margin |
+
+These are independently chosen numerical guards, not a theorem about every
+possible MIDI schedule or every time-varying instrument filter. Bass actually
+reaches 0.12384, demonstrating why raw gain alone is not a sufficient bound.
+
+For a recorded source peak M, mix m, and feedback f, the FX bound is:
+
+`M * ((1 - m) + m / (1 - f)) * Master + 1e-6`
+
+This bound is independent of the rendered FX peak. All three feedback paths
+are flat or fixed Q=0.5 low-pass; their nonnegative impulse responses have unit
+L1 norm at the candidate cutoffs. Interpolated delay, including Chorus's moving
+readheads, cannot increase the supremum. Therefore f <= 0.5 permits at most a
+factor of two. The oracle asserts valid timing and unclipped modulation.
+
+With **Master range 0–1, default 1**, the largest fixed source ceiling yields
+an FX ceiling below 0.480001. Every output is also required to stay below the
+separate **0.5 ceiling**, preserving at least 6.02 dB to full scale for tested
+material. This explicitly replaces reliance on the prior diagnostic-only 0.8
+limit. No limiter or normalization is inserted.
+
+## Measured maxima
+
+Maximum absolute sample across all scenarios and controls at Master 1:
+
+| Instrument | Raw source | Diagnostic delay | Chorus | Rhythmic Delay |
+| --- | ---: | ---: | ---: | ---: |
+| Diagnostic | 0.187219307 | 0.276219070 | 0.368202865 | 0.326295972 |
+| Bass | 0.123841561 | 0.163044527 | 0.205227017 | 0.176587388 |
+| Percussion | 0.158914849 | 0.213010132 | 0.240000606 | 0.219704628 |
+| Pad | 0.168394074 | 0.208122611 | 0.312585205 | 0.228740290 |
+
+All 90 rows passed. The worst output, **0.368202865**, is Diagnostic → Chorus,
+four coherent voices across the displayed register, wet mix 1 and feedback 0.5.
+It leaves **8.678 dB** of measured headroom. Every render had zero scrubbed,
+nonfinite, or clipped samples.
+
+Master 2 would not clip these particular recorded samples, but would exceed the
+chosen 0.5 regression ceiling and surrender 6.02 dB of output margin. The
+integrated candidate therefore keeps Master 0–1 without changing public sound
+parameters. The matrix does not establish a universal arbitrary-MIDI safety
+proof, real-time capacity, device playback behavior, or physical listening
+approval; those remain separate checks.