@denaudio/den 0.0.0-stage → 0.2.0

package/docs/spectral-large-candidate.md

@@ -0,0 +1,81 @@
+# Larger STFT offline candidate
+
+The reviewed initial proof at `262d74b` remains frozen. After independent review
+of the private large-frame proof at `cea9dfe`, this follow-up promotes the public
+`stftIdentity` wrapper to power-of-two N in8..1024, with H=N/2 or N/4. This is an
+offline candidate with explicit snapshot and execution-cost contracts.
+Convolution remains B<=32 and IR<=128 samples.
+
+## Kernel proof
+
+N1024 now uses counted native loops for initialization/bit reversal, butterfly
+stages and buffer copies. Eight complex test vectors at each of 44.1/48/96 kHz
+cover impulse, DC, Nyquist, positive/negative bins, off-bin tone and seeded
+complex/real data. Forward/inverse results match a direct O(N²) DFT rounded to
+the f32 output format within 1e-6; signs, ordering, normalization and real-input
+conjugate symmetry are checked independently.
+
+A fresh frozen-head N1024 kernel-only probe completed under the unchanged
+2-GiB/90-second watchdog: 114,709-byte WASM, 128-KiB fixed memory, 188-MB process
+RSS peak and 15.82-ms first quantum. This is a kernel diagnostic, not evidence
+for windowed framing, snapshots, practical concurrency or realtime acceptance.
+
+## Persistent frame phase
+
+The measurements and dispatch description below record the original 0.4.1
+candidate at quantum 128. Since den 0.2.0, callers pass `ctx.renderQuantumSize`
+and dispatch is `gcd(H, 128, renderQuantumSize)`; fixed FFT loops use `forIndex`.
+The [current spectral contract](spectral.md) describes snapshot behavior and
+increased work for smaller or coprime quanta. Historical timings below are not
+measurements of those targets.
+
+Public unworklet 0.4.1 has no condition-driven statement block. Its select is
+eager; everyNSamples/byN bounds are construction-fixed. Native everyNSamples
+counters are omitted from snapshots. Simply changing a hop to256 or512 would
+therefore change its phase when restoring a snapshot taken at an intermediate
+128-sample quantum boundary.
+
+The candidate uses native dispatch every min(H,128) samples, a divisor of the
+snapshot quantum. Its existing named persistent ring cursor determines whether
+cursor modulo H is zero. Only these true H-phase frames update overlap state
+and consume pending-reset invalidation. Reset never changes cursor/hop phase.
+
+For H>128 the FFT/IFFT pair still executes every128 samples. Off-phase results
+are discarded using eager selects; this is expressly not H-rate CPU savings.
+Window, history and spectrum scratch use explicit buffer indices, with no
+implicit audio/parameter sample position inside nested work loops.
+
+## Verified so far
+
+- Original small FFT/WOLA/FIR tolerances and reset/latency assertions unchanged
+- N256/512/1024 identity reconstruction at H=N/2 and N/4, all three rates
+- Every reset phase, separated sufficiently to yield nonzero reconstructed audio
+- Exact N-sample latency and reset's current-input discard
+- All four quantum-offset phase classes for H<=512, including reset immediately
+  before snapshots; continuation is bit-identical
+- Held reset, varying signed f32 subnormals and full finite f32 range, zero scrubs
+- 29 focused tests passed in26 seconds, with502-MB observed process-tree RSS
+
+## Measured eager-dispatch profile
+
+The actual internal N1024/H512 STFT dispatches every128 samples and completed a
+fresh-process 48-kHz profile under the unchanged2-GiB/60-second watchdog in2.22s.
+It generated119,327 bytes of WASM, used128KiB fixed DSP memory and peaked at194MB
+process RSS. Capture was97ms, compile1.60s and first/startup maximum18.98ms.
+After128 warmup quanta,512 measured quanta had process p50 0.163ms,
+p99 1.428ms and maximum4.680ms; maximum including copies was4.687ms. Zero output
+scrubs and fixed memory were checked. This is one local Node instance with host
+jitter, not browser or concurrency evidence.
+
+Both the cold and observed warm maxima exceed the2.67-ms 48-kHz quantum.
+The algorithmic audio latency is separately1024 samples:21.33ms at48kHz,
+23.22ms at44.1kHz and10.67ms at96kHz. Choosing H512 does not reduce execution to
+once every512 samples: preserving arbitrary-quantum snapshot phase currently
+costs one FFT/IFFT pair per128 samples, with off-phase results discarded.
+
+An isolated public packed consumer verifies the actual export, both N1024 hops,
+three offline rates, reset and all four snapshot phase classes, plus the
+generated48-kHz Vite worklet. Exact-head package evidence and final independent
+QA gate integration of this promotion. No browser, human sound or realtime clearance is
+claimed. This does not complete pitch/time processing, phase-vocoder effects or
+practical long-IR convolution.

package/docs/spectral-texture-entry.md

@@ -0,0 +1,178 @@
+# Bounded spectral texture entry contract
+
+Source scope: catalog group 11, [STFT blur and cross-synthesis](https://app.notion.com/p/3ef449b4e81d817db1acf1fff48779b3).
+This proposal adds two CANDIDATE native subgraphs. It does not claim spectral
+resynthesis completeness, transparent speech, phase-vocoder quality, phase
+locking, human sound approval, or real-time clearance.
+
+## Shared framing
+
+- Pass `renderQuantumSize: ctx.renderQuantumSize` in both module configurations.
+  Dispatch follows the shared [spectral contract](spectral.md), preserving
+  block-atomic snapshot phase at the actual render quantum.
+- Construction-fixed power-of-two N=8..256, H=N/2 or N/4. Rebuild to change.
+- Instantiate with an explicit subgraph name and call exactly once per sample
+  inside stride-1 `forSample`, passing its native `everyNSamples`.
+- Every audio input is finite normalized f32 in [-1,1]. The two cross-synthesis
+  inputs must belong to the same sample timeline and call.
+- Reuse the existing FFT/STFT code unchanged: periodic sqrt-Hann analysis and
+  synthesis, forward unnormalized DFT, inverse 1/N, WOLA scale 2H/N, internal
+  2^128 scaling, and live reference delay N.
+- A committed frame at t=mH consumes [t-N,t), excludes current input, and samples
+  controls at t. Missing startup/reset history is zero padded. Dispatch occurs
+  every `gcd(H, 128, renderQuantumSize)` samples; off-phase work is eager and
+  commits no overlap. At the original quantum 128, H<=128 needs no off-phase
+  calls. Smaller or coprime quanta add work; the N1024 single-input evidence is
+  not inherited by this two-framer composition. N<=256 retains its initial bound.
+- Clamp amount to [0,1]; NaN becomes 0, infinities clamp. Interpolation is linear
+  in bin magnitude, not dB, power, audio time, or equal-power gain. It replaces
+  newly committed frames; previous overlap remains until it finishes within N.
+- DC and Nyquist are real; negative bins are reconstructed as conjugates.
+- There is no output normalizer, limiter, extra transition ramp, or dry path.
+  Processed onset can precede the N-sample identity alignment. Drain 2N zeros
+  after the last nonzero input (both inputs for cross-synthesis).
+
+## Frequency-magnitude blur
+
+`spectralBlur({ size, hopSize, radius, renderQuantumSize }).tick(input, amount, reset, everyNSamples)`
+
+Radius is a fixed integer 1..min(8,N/2-1). Let X[k] be the full two-sided complex
+DFT and A[k]=|X[k]|. Define a circular triangular blur on the raw, two-sided DFT
+magnitudes, not on single-sided coherent-amplitude estimates:
+
+    B[k] = sum(j=-R..R) (R+1-|j|)/(R+1)^2 * A[(k+j) mod N]
+    T[k] = (1-amount)*A[k] + amount*B[k]
+
+The normalized symmetric kernel crosses DC and Nyquist through the corresponding
+conjugate bins. No endpoint duplication or renormalized truncated kernel occurs.
+Let P=max_j A[j]. Retain the current input phase only when A[k]>0 and
+A[k]>=2^-20*P: Y[k]=T[k]*X[k]/A[k]. Otherwise use phase zero,
+Y[k]=T[k]+i*0. At DC/Nyquist a retained real bin preserves its sign; a bin below
+the floor or exactly zero gets positive real magnitude. Equality belongs to
+the retained-phase side only when A[k]>0.
+
+Implement phase as separately normalized real/imaginary components, then
+multiply by T, rather than multiplying X by an unbounded T/A gain. The divisor
+is replaced by 1 when A=0 before evaluating either select branch. All finite
+inputs remain finite. The floor is relative to the same frame's maximum raw
+magnitude, so uniformly scaling a frame preserves the phase decision in ideal
+arithmetic, including tiny inputs. This deliberately discards weak-bin phase
+and can abruptly change phase at the floor. It is a deterministic texture
+choice, not extra precision, smoothing or a phase-locking guarantee.
+For target magnitude T and retained phase phi, replacing zero phase changes
+that complex bin by 2*T*abs(sin(phi/2)), up to 2T, even when the original A is
+tiny. The below/at/above floor cases and this jump bound are required evidence;
+the threshold must not be changed to make an oracle comparison pass.
+
+The rejected exact-nonzero phase rule could promote FFT roundoff at a spectral
+null into audible redistributed magnitude and make two valid DFT algorithms
+disagree audibly. Keep that counterexample in validation. The floor stabilizes
+nulls, but decisions extremely close to the floor remain finite-precision
+sensitive, and full-frame rescaling may quantize f32 input differently.
+
+The fixed amount=0 path selects the original unmodified spectrum; its PCM
+identity claim must be tested, including subnormal inputs and arbitrary reset.
+Once amount is changed to 0, previous processed overlap first needs to settle.
+At amount=1 the full triangular blur is used, which can add energy to previously
+empty bins using the deterministic phase rule above. This is frequency blur,
+not a time-memory blur or a freeze.
+
+## Gain-bounded cross-synthesis
+
+`spectralCrossSynthesis({ size, hopSize, maxGain, renderQuantumSize }).tick(carrier, modulator, amount, reset, everyNSamples)`
+
+maxGain is a finite construction-fixed number in [1,16]. Let C[k], M[k] be the
+synchronized carrier/modulator frames, A[k]=|C[k]|, and B[k]=|M[k]|:
+
+    target[k] = min(B[k], maxGain*A[k])
+    T[k] = (1-amount)*A[k] + amount*target[k]
+    Y[k] = C[k]*((1-amount) + amount*min(B[k]/A[k],maxGain))
+
+For exactly zero A, set the ratio to zero, with a safe denominator before select
+evaluation. Zero carrier therefore remains silent, including when the modulator
+is nonzero. A near-zero carrier is amplified by at most maxGain, not promoted to
+the modulator level. The amount=0 path selects the original unmodified carrier
+spectrum. A silent modulator with amount=1 suppresses the carrier spectrum.
+Same-input amount=1 should numerically preserve the carrier; any stronger
+bit-identity claim depends on measured proof and is not presumed.
+
+Carrier phase is unchanged; modulator phase does not contribute. Both spectra
+use identical raw DFT/window calibration, so the single-sided coherent-window
+factor (1/windowSum at DC/Nyquist and 2/windowSum elsewhere) cancels in every
+same-bin ratio. Full cross-synthesis replaces raw carrier magnitudes with
+modulator magnitudes only where the gain cap permits. It does not transfer a
+smooth vocal envelope, move formants, estimate frequencies, or guarantee speech
+intelligibility. No audio-rate modulator bypass/identity is inferred from a zero
+gain or silent control input.
+
+## Composition, reset and native state
+
+The cross-synthesis implementation will first tick a separately named private
+modulator STFT instance whose construction hook materializes current magnitudes
+into its own transient buffer, then tick the carrier STFT instance whose hook
+reads those magnitudes. Both use the same N, H, reset and outer sample callback.
+The modulator's inverse transform/output is unused; it still executes. This
+deliberate bounded overhead avoids modifying shared framing or adding a second
+framing engine. Native source inspection shows separate everyNSamples counters
+and sequential statement emission; synchronized analysis and no one-frame lag
+remain requirements for independent sample-by-sample proof.
+The materializing hook writes and native frame statements must remain present
+even though the tap's audio return is unused; inspect the captured graph and
+prove observed modulator changes reach the matching carrier frame.
+
+Reset immediately silences and discards the current input(s), invalidates old
+history/overlap, and does not rephase either frame cursor. Held reset remains
+silent. State contains the reviewed native history/overlap/cursor/reset state
+per instance. Magnitudes, FFT buffers, windows and sampled controls are transient
+and are fully recomputed before use at the next frame. No cross-frame blur
+memory or private snapshot format is introduced.
+
+Only full native same-graph/configuration/sample-rate/quantum snapshots are supported.
+Restoring only one member of a cross-synthesis pair is outside the contract.
+Tests must prove exact continuation across every legal H class at native
+block boundaries, including non-128-aligned boundaries, active processing,
+pending reset, and held reset. No cross-configuration/schema/rate/quantum
+migration is promised.
+
+## Ideal headroom and validation
+
+For normalized inputs, an analysis frame has L2 norm <=sqrt(N). The normalized
+circular nonnegative blur kernel is an L2 contraction on magnitudes, and linear
+interpolation preserves that bound. Cross-synthesis's target magnitude is
+componentwise <=|M|; triangle inequality bounds the interpolated norm by the
+larger of the normalized carrier/modulator frame norms. Phase replacement does
+not change norm. Each inverse-frame sample is thus bounded by sqrt(N), and at
+most N/H frames each scaled by 2H/N overlap, giving |output|<=2*sqrt(N), at most
+32 for N256. This is conservative ideal arithmetic, not a finite-f64 theorem or
+an enforced ceiling. No per-channel output normalization is permitted in proof.
+
+Required evidence: independent dense DFT/magnitude operation/IFFT/absolute-time
+WOLA; analytic circular-kernel DC/Nyquist/isolated-bin expectations; amount
+endpoints/interior/nonfinite controls; modulator scaling/phase independence and
+explicit carrier zero/near-zero gain-cap behavior; current-sample exclusion and
+simultaneous transient frames; every small reset offset, held reset, snapshots,
+subnormals/extrema, finite drain and same-schema state at 44.1/48/96 kHz. Keep
+blur's full-frame scale invariance, exact-zero/weak/retained phase boundary,
+DC/Nyquist sign and rejected near-null amplification counterexamples explicit.
+Keep existing no-hook framing/schema/PCM tests unchanged. Independently review this
+contract before DSP, and review actual implementation before integration.
+
+Measure maximum N256/R8 graph memory/cold/warm render costs later under the
+coordinator's fixed guard and exclusive resource lease. Public package exports,
+installed-consumer and hosted browser acceptance belong to the coordinator.
+No install, runtime/loader/snapshot/framework/upstream changes are proposed.
+
+## Initial focused evidence
+
+The initial 21-test focused/native compatibility pass and package typecheck
+completed in 20.25 seconds with 580 MB summed process-group RSS under the fixed
+120-second/2 GiB guard. The untouched source implementation passed independent
+DFT/WOLA, exact amount-zero identity, synchronized dual frames, tiny inputs,
+gain caps, reset, N256 native continuation and original no-hook compatibility.
+Independent review requested small-hop snapshot classes and explicit measured
+phase-floor ratios. The expanded 24-test pass and typecheck completed in 23.03
+seconds with 576 MB summed process-group RSS under the same guard. It covers
+every supported H class, pending/held reset snapshots, measured actual f32
+floor ratios, the non-real phase jump, and exact power-of-two scale invariance
+where f32 can represent the scaled waveform without subnormal quantization.
+This evidence is not public-package, hosted-browser or human-sound approval.

package/docs/spectral.md

@@ -0,0 +1,127 @@
+# Spectral framing candidate
+
+This lane is CANDIDATE. It is an FFT/framing and identity reconstruction entry
+proof for catalog §10/11, not completion of pitch/time, phase-vocoder, long-IR,
+freeze/shimmer or spectral-source work. No human sound approval or browser
+realtime clearance is implied.
+
+## Entry contract
+
+`stftIdentity({ size, hopSize, renderQuantumSize: ctx.renderQuantumSize }).tick(input, reset, everyNSamples)` is an ordinary
+unworklet subgraph. Instantiate it once with an explicit name. Call tick exactly
+once per sample from stride-1 `forSample((i, everyNSamples) => ...)`. The last
+argument is unworklet's existing conditional scheduler, not a den scheduler or a
+runtime JavaScript callback. `select` is never used to skip the FFT workload.
+
+- Pass the enclosing processor's `ctx.renderQuantumSize` in the configuration.
+  It is a positive integer, matching unworklet's compile target, not the FFT size
+  or hop. All STFT-based modules use this value for snapshot-safe dispatch.
+- Supported N is a power of two in 8..1024. H is N/2 or N/4. These are
+  offline-candidate bounds, not a performance or concurrency recommendation.
+- The internal, non-public complex radix-2 kernel has natural-order real/imaginary
+  planes, forward exponent -i2πkn/N, inverse exponent +i2πkn/N and inverse scale 1/N.
+  All intermediate work/history use fixed f64 buffers; I/O is f32. The stream
+  uses an exact 2^128 scale internally to avoid 0.4.1's 1e-30 buffer-write
+  flush discarding quiet f32 inputs. Stage JavaScript loops execute during
+  graph construction. Within each stage, the public `forIndex(count)` loop
+  visits exactly the work-buffer capacity, independently of the render quantum,
+  without audio/parameter reads or updates to sample time. The outer `forSample`
+  loop alone follows the audio quantum. Twiddle step constants are calculated at build
+  time, then a bounded f64 recurrence reanchors to (1,0) at every butterfly group.
+- A frame at sample t=mH consumes samples [t-N,t), with absent history set to
+  zero. It is added to output samples [t,t+N). Output therefore has exactly N
+  samples of latency, including startup. Drain with at least N zero input samples.
+- Both windows are periodic sqrt-Hann: w[n]=sqrt(0.5-0.5 cos(2πn/N)). The product
+  is Hann. For K=N/H in {2,4}, the shifted cosines sum to zero, so the sum of
+  squared windows is K/2=N/(2H). The synthesis scale is its reciprocal 2H/N.
+- Reset is level-sensitive: it emits zero immediately, discards the current
+  input, and invalidates prior history and overlap. Held reset remains silent.
+  It does not restart the native hop phase. The first later frame clears stale
+  overlap; output is masked until then. Post-reset reconstruction retains the
+  same N-sample delay. Discontinuities from reset are intentional.
+- Input must be finite f32. No smoothing, gain normalization beyond WOLA, bypass,
+  dry/wet routing, sample-rate converter, hidden loader, external FFT runtime,
+  or new storage/snapshot system is supplied.
+- Native persistent history/overlap/cursor/valid/reset state is saved. FFT and
+  spectral scratch are transient and fully overwritten at each scheduled frame.
+  Only identical graph/rate/quantum full-snapshot continuation is in scope;
+  migration and cross-rate or cross-quantum continuation are not promised.
+  Native hop counters are not included in snapshots. Dispatch therefore occurs
+  every `gcd(H, 128, renderQuantumSize)` samples, a divisor of both the hop and
+  every block-atomic restore boundary. The persistent cursor modulo H selects
+  frame commits. Off-phase FFT results are computed eagerly and discarded.
+  At quantum 128 this retains the former dispatch period. For H>=128, quantum
+  32 evaluates four times as many FFT pairs per sample; a quantum coprime to
+  128 dispatches every sample, up to 128 times the old workload. Correct output
+  and snapshot phase do not imply realtime feasibility. See
+  [large-frame evidence](spectral-large-candidate.md) for historical costs.
+
+## Verification required before integration
+
+Independent direct O(N²) DFT covers complex impulse, DC, Nyquist, positive and
+negative bins, off-bin tone, seeded inputs, signs, natural ordering, conjugate
+symmetry and inverse normalization. Independent time-indexed DFT/WOLA covers
+startup, every hop phase, held/arbitrary resets, block boundaries and three
+offline rates (44.1/48/96 kHz). The rate/quantum matrix includes quantum
+32/128/256, independent numerical oracles and exact quantum-128 PCM comparisons.
+Exact same-schema snapshots include non-128-aligned boundaries at quantum 32
+and non-power-of-two quantum 48. Reset discard is checked separately. Larger construction sizes require measured capture/compile
+cost, WASM size, memory and quantum-burst timing before becoming public bounds.
+
+Node driver measurements describe that environment only, including whether copies
+were included. They do not certify browser deadlines, concurrency or a device
+budget. The playground now compiles for its actual AudioContext sample rate and
+render quantum using unworklet 0.6.0; this does not grant realtime clearance.
+
+## Initial local evidence
+
+The initial N8/16/32/64 FFT/identity suite passed at all three rates, including
+all reset hop phases, native snapshots and quiet/full-range finite f32 input.
+For one N64/H16 instance in Node 24, capture was 32 ms, compile 1.16 s, generated
+WASM 314,881 bytes, fixed WASM memory 65,536 bytes. A 512-quantum warmed run had
+process p99 0.525 ms and maximum 1.07 ms, excluding input/output copies.
+
+**Cold first-quantum execution was 298 ms.** This far exceeds a 48-kHz quantum
+and is an explicit startup/deadline hazard. No deployment/realtime clearance is
+granted by the warmed result. The exact-head packed report supersedes these
+initial diagnostic values; larger frames need separate evidence.
+
+### Graph-shape corrections and current verification
+
+The original fully unrolled kernel is retained in commit `8d3df3c` for
+reproduction. At N256/H64, a fresh two-transform driver probe generated 1.61 MB
+of WASM, took 12.22 s for its first quantum and peaked at 4.21 GB process RSS.
+The fixed DSP allocation was still only 64 KiB. This host compilation/execution
+scaling failure is distinct from audio-buffer capacity; the unrolled N1024
+probe was deliberately not started.
+
+The first reduction put butterfly stages in native fixed loops. Its independent
+hop7 entry probe confirms four inner work-buffer iterations, sequential
+write/read visibility and preservation of the outer sample index at all three
+rates. The full 16 FFT/STFT/convolution tests still pass. For N64/H16, generated
+WASM falls to 84,607 bytes, fresh first quantum to 31.6 ms and peak process RSS
+to 179 MB. Warm process p99 is 0.279 ms, maximum 0.395 ms in that local run.
+This is a measured reduction, not a deadline clearance: the first quantum still
+greatly exceeds the 2.67-ms 48-kHz deadline. The same partial reduction at N256
+produced 273 KB WASM, a 110-ms first quantum and 466 MB peak process RSS. Its
+N1024 diagnostic was stopped by the external 2-GiB RSS watchdog during the first
+quantum: 1.122 MB WASM had compiled, but no cold/warm render completed. This was
+not a successful N1024 render or numerical verification.
+
+The current second reduction also uses native indexed loops for FFT
+initialization/bit reversal, spectrum copies and STFT overlap-add. The window is
+generated by a reanchored f64 sine recurrence each frame, rather than N copies
+of graph code. This is still the same periodic sqrt-Hann contract. No audio or
+parameter access occurs inside an inner buffer loop; all indices are explicit.
+
+All original small-size DFT, WOLA and direct FIR assertions remain unchanged.
+Together with three additional N256 direct-DFT cases, all 19 tests passed in
+10.5 seconds. The larger test compares f32 outputs with independently f32-rounded
+direct DFT values; it does not broaden public module support. The test process
+tree's RSS was unavailable to that run's supervisor, so no zero-memory or peak
+memory claim is made for it. Final exact-head resource/packed evidence is a
+separate gate. The later independently reviewed large-frame proof and public
+packed promotion extend STFT alone to N<=1024; B<=32/IR<=128 convolution bounds
+remain unchanged. At N1024/H512 the measured first quantum was18.98ms and warm
+maximum4.687ms with copies, both above a48-kHz quantum. Longer IRs and all
+realtime claims remain unadvertised.

package/docs/virtual-analog.md

@@ -0,0 +1,77 @@
+# Pulse, triangle and deterministic noise candidates
+
+`@denaudio/den/virtual-analog` exports `virtualAnalogSource`, `seededNoise` and
+their config/control types. These additions do not change existing sine/saw,
+instrument, unison, presets or sound candidates.
+
+## Pulse and triangle
+
+`virtualAnalogSource({sampleRate,waveform,phaseCycles?})` fixes waveform to
+`'pulse'` or `'triangle'`. Sample rate must be finite 8000..192000 Hz;
+initial/reset phase is in [0,1), default0. `tick({frequencyHz,duty,reset})`
+returns one float32 sample. Frequency clamps to [0,.45 × sampleRate], with
+NaN→0 and infinities saturated. Zero Hz holds phase. Duty clamps to [0,1],
+NaN→.5; triangle ignores duty.
+
+Pulse is +1 during phase<duty and −1 otherwise. Two-sample-support quadratic
+polynomial BLEP residuals smooth its positive and negative steps. Pulse mean is
+2×duty−1: non-50% pulse intentionally contains DC. Duty0 is exactly −1 and duty1
+exactly +1, including reset and zero frequency. No DC blocker is hidden inside.
+
+Triangle starts at −1 at phase0, rises linearly to +1 at phase.5, then falls.
+Cubic polynomial BLAMP residuals correct slope jumps +8 and −8 cycles⁻¹. It is
+direct phase evaluation, not a leaky-integrated pulse, so no integration drift or
+settling tail is added. At positive step d, its phase-zero output is −1+4d/3.
+At zero Hz it emits the raw triangle, including −1 at phase0.
+
+Both constructions equal convolution of their periodic raw waveform with a
+unit-area triangular kernel of half-width one output sample at constant frequency
+and duty. The corresponding static harmonic transfer is sinc²(k×frequency/rate),
+where sinc(x)=sin(πx)/(πx). Tests verify this independently using piecewise exact
+Gaussian quadrature and Fourier coefficients, including above-Nyquist harmonics
+folding into the sampled spectrum. This is finite polynomial alias reduction,
+not ideal bandlimiting. Residual aliases and high-frequency attenuation remain.
+The two-sample span denotes the correction support, not a two-sample output delay.
+
+Reset is level-sensitive: emit configured phase and then advance on every true
+sample. At default phase, ordinary pulse is0 when the two edge corrections do
+not overlap; near duty endpoints overlap changes that value. A held reset repeats
+phase, while output can still change with frequency/duty. Zero-frequency correction
+is disabled with a safe denominator in every eagerly evaluated branch. Abrupt
+PWM, frequency jumps and resets do not receive a crossing-time correction or
+oversampling guarantee and can alias/click. PWM is not subsample-sync support.
+
+Phase uses exact power-of-two-scaled f64 native state, avoiding the native scalar
+flush below 1e-30. The smallest positive f32 frequency accumulates from zero;
+ordinary f64 addition resolution still applies at a nonzero phase. No minimum-Hz
+gate is introduced. At fixed valid controls pulse and triangle stay in [−1,1]
+within float32 numerical tolerance. Sample-rate/config changes require a new graph.
+The 2^1020 phase scale also preserves f64 `Number.MIN_VALUE` initial phase. Stored
+phase is wrapped below 1 before scaling, leaving over 16× finite headroom; all
+waveform and advance arithmetic happens after unscaling.
+
+The distinction between step BLEP and slope BLAMP follows the concepts discussed
+in [Esqueda, Välimäki and Bilbao, Rounding Corners with BLAMP, DAFx 2016](https://www.dafx.de/paper-archive/2016/dafxpapers/18-DAFx-16_paper_33-PN.pdf).
+This implementation and its two-sample triangular-kernel coefficients were
+derived independently; the paper's reported performance is not a den claim.
+
+## Noise
+
+`seededNoise({seed?})` uses the Park–Miller multiplier48271 and modulus2147483647.
+Seed is an integer1..2147483646, default1. For each sample it computes
+next=(current×48271) mod2147483647 using exact f64 integer arithmetic (product
+below 2⁴⁷), stores next as i32, and returns float32(2×next/2147483647−1).
+Float32 rounding can include an endpoint even though the real-valued map is open.
+This deterministic generator is not cryptographic or a quality guarantee for
+all statistical/audio uses; there is no pink/brown noise or noise-shaping mode.
+
+`tick(reset)` chooses the configured seed before generating that sample whenever
+reset is true. Reset therefore emits the same first sample; held reset repeats
+it. Independent instances do not share state. Noise sequence is sample-indexed,
+so the same seed/reset samples match at all supported host rates. Snapshot
+continuation is exact for identical graph/config/rate using existing native state.
+
+Tests at 44.1/48/96 kHz cover an independent BigInt PRNG oracle, endpoint seeds,
+held reset, isolated instances, bounded finite output, mean/power diagnostics and
+snapshots. Those finite-window statistics do not prove a perfectly white spectrum.
+All generated audio remains CANDIDATE until separate human approval.

package/docs/voice-policy.md

@@ -0,0 +1,38 @@
+# Voice policy integration (GEN-616)
+
+`src/voice-policy.ts` provides a construction-time fixed-capacity unworklet subgraph. It allocates voices and emits control values; it contains no oscillator, envelope, filter, audio mixing, or MIDI transport. The public package subpath is `@denaudio/den/voice-policy`. The isolated entry consumer checks its types and renders note-on/note-off gate behavior at 44.1/48/96 kHz.
+
+Instantiate with a required configuration and an explicit instance name (the same workaround for unworklet #104 used by the entry gate). Call `bindMidi` once in declaration scope with an existing `event.midi({ from: 'main', name: 'midi' })` input. The host sends through unworklet's existing node MIDI API. Alternatively, invoke the graph methods from existing graph event handlers. Arguments are unworklet nodes, not host numbers.
+
+| Contract | Behavior |
+| --- | --- |
+| `mode` | Required `mono` or `poly`; mono uses one voice. |
+| `capacity` | Poly defaults to 16, configurable 1–32; mono requires 1. |
+| `heldCapacity` | Defaults to 128; configurable from voice capacity through 256. Counts accepted, still-held note-on identities, including stolen notes. |
+| `legato` | Mono defaults to true. True preserves gate and suppresses retriggers when held-note priority changes. False retriggers on changes and fallbacks. |
+| `voices[n].read()` | Graph nodes: `active`, `gate`, integer MIDI `note`, integer `channel`, normalized `velocity`. Inactive note/channel are -1 and velocity is zero. |
+| `voices[n].takeRetrigger()` | Returns and clears a latched start/retrigger. Consume once per sample before the envelope; share that returned node if several consumers need it. |
+| `voices[n].releaseFinished(done)` | Frees a released voice on envelope completion. Never frees a currently held replacement. Call with the envelope's current completion signal. |
+| `noteOn(note, channel, velocity)` / `noteOff(note, channel)` | Channels 0–15, notes 0–127, velocities 0–127. Velocity-zero note-on is note-off. Invalid graph values are ignored. |
+| `allNotesOff(channel)` | Removes held keys for that channel and starts their release; mono may fall back to another channel's held note. |
+| `allSoundOff(channel)` | Removes keys and immediately frees that channel's voices; mono may fall back to another channel. |
+| `reset(when)` | Immediately clears every voice, held identity, pending retrigger and overflow flag when true. Default condition is true. |
+| `overflowed()` | Latched boolean cleared by reset. Signals rejected note-ons when the held ledger is full. |
+
+The capacity defaults and ceilings are implementation bounds for the generated graph, not approved product limits. No runtime capacity changes or dynamic allocation are introduced.
+
+Poly chooses the lowest-index free slot, then the oldest released slot, then steals the oldest held slot. Allocation and release ranks remain bounded by capacity. Duplicate note-offs consume the oldest outstanding matching channel/note identity. Stolen identities remain in the bounded held ledger, so their later note-offs cannot release a newer duplicate. Mono chooses the most recently held identity and falls back through still-held identities. Duplicate identities retain their own velocity and channel.
+
+A full held ledger rejects new note-ons and latches overflow; it does not evict accepted identities. This preserves release bookkeeping for accepted notes. MIDI 1.0 contains no per-note identity, so interleaved note-offs for rejected duplicate pitches cannot be distinguished from accepted duplicate pitches. FIFO pairing is the explicit policy. Reset or channel all-sound-off clears retained identities. Sustain CC64 and other controllers are not implemented; bindMidi handles CC123 and CC120 only.
+
+Unworklet 0.4.1 drains MIDI at block boundaries in FIFO order, before processing samples. Generic control messages drain before MIDI in the same block. This module preserves those semantics; it does not add a sample-accurate event scheduler. Multiple starts in a block coalesce to one retrigger latch and the final voice assignment. An on/off pair in one block may produce a retrigger with gate already low; envelope integration must define that case. Do not claim sample-accurate MIDI from these tests.
+
+All voice and held-key storage uses unworklet transient state. Snapshots exclude live held notes. A fresh instance therefore starts empty, while native in-place restore leaves currently held notes unchanged. Use explicit reset for a cold live restore; no new snapshot/preset serializer is provided. A reset is the explicit panic operation. Completion signals belong to the current envelope attached to each slot; a delayed completion from a previous released assignment must not be reused after a steal and subsequent release.
+
+## Verification
+
+The numerical fixture renders voice state through diagnostic outputs using published unworklet 0.6.0. It checks FIFO duplicates, stolen-note releases, release reuse, mono priority/legato/retrigger, channel controls, reset, independent instances, bounded overflow and repeated reuse. These outputs are diagnostics, not audition audio or approved goldens. Offline 44.1/48/96 kHz tests are separate from the [browser entry coverage](dependency-findings.md#browser-sample-rate-and-render-quantum).
+
+Upstream [#99](https://github.com/yuichkun/unworklet/issues/99) was fixed in unworklet 0.5.0: `expectMidiBalance` treats velocity-zero note-on as note termination. The 0.6.0 regression accepts a positive-velocity note-on followed by velocity-zero note-on, and rejects both a hanging note and an additional unmatched note-off. Den retains its independent numerical gate/identity assertions. The legacy half-sample duration margin remains in this fixture; exact-duration behavior is checked separately in the [dependency regressions](dependency-findings.md).
+
+Capacity probes also exposed recursive expression expansion in unworklet's analysis of nested selects. Transient scratch accumulators keep the traversal and selection expressions shallow. Before this change the default-capacity test was stopped after more than one minute of CPU work; afterward the full numerical suite including capacity probes ran in seconds. A 64-voice/256-held diagnostic graph failed WebAssembly compilation with `local count too large`; the supported construction ceiling is therefore 32 voices, tested with 256 held identities. Larger combined instrument graphs still require their own compile and runtime budget checks. The current release-completion path performs rank maintenance across slots; passing these fixtures does not establish a real-time CPU budget for a complete instrument.

package/docs/wavetable-bands.md

@@ -0,0 +1,138 @@
+# Prepared pitch-band wavetable candidate
+
+`@denaudio/den/wavetable` additionally exports `prepareWavetableBands`,
+`bandedWavetableSource`, `PreparedWavetableBands`, `WavetableBandsOptions` and
+`BandedWavetableConfig`. The unbanded `wavetableSource` retains its layout and
+control contract with the cycle-local precision correction documented separately.
+Oscillator and instrument behavior is unchanged. This candidate implements the original catalog group's
+host-prepared pitch-band assets and shared native reader; it is not an approved
+sound or a claim of equivalence to another synth.
+
+## Host preparation and provenance
+
+Call `prepareWavetableBands({ frames })` on the host, outside audio processing.
+Supply 1..16 `Float32Array` mono cycles of equal power-of-two length 16..4096.
+A cycle contains no duplicate final endpoint. All input samples must be finite.
+The helper does not decode files, load assets or assume a license for user data.
+Tests use original analytic sine/cosine combinations, silence and synthetic
+finite/nonfinite edge fixtures; no third-party audio or proprietary tables.
+
+A host-only radix-2 FFT obtains each cycle's complex spectrum. The first band's
+positive harmonic limit is N/2−1; each next limit is floor(previous/2), ending at 1.
+DC is retained in every band. Only conjugate pairs through that limit are kept;
+the table Nyquist bin is omitted. Explicit conjugate symmetry and inverse FFT
+produce real cycles. Original DC, retained gain and phase are preserved within
+FFT/float32 roundoff. There is no peak or per-band normalization. Finite source
+PCM can overshoot after harmonic truncation: if any reconstructed value becomes
+nonfinite when converted to float32, preparation throws `RangeError`, without
+clamping or returning a partially prepared asset. Nonfinite input also throws.
+The input cycles are never modified.
+
+The result is an ordinary local object `{data, frameLength, frameCount,
+harmonicLimits}`. `harmonicLimits` is frozen, descending and explanatory; it is
+not a transport protocol. Native construction derives the same fixed schedule.
+Editing a source frame means preparing it again and loading the resulting full
+PCM through the existing resident. This is not a new serializer or asset manager.
+
+## Fixed layout, capacity and ingress
+
+The resulting `data` is band-major then frame-major: band0/frame0 cycle,
+band0/frame1 cycle, …, band1/frame0 cycle, …. Required PCM length is
+N × morph-frame count × band count. Both host preparation and native construction
+reject layouts larger than 65536 samples. Native construction also rejects a
+resident with insufficient capacity. There are 3..11 bands. Examples:
+
+- 512 samples × 16 frames × 8 bands = 65536 samples, the full 256 KiB resident
+- 1024 × 7 × 9 = 64512 samples
+- 2048 × 3 × 10 = 61440 samples
+- 4096 × 1 × 11 = 45056 samples
+
+Host preparation allocates the output plus four reused float64 work arrays,
+32N bytes (at most 128 KiB), excluding the caller's original frames and ordinary
+object overhead. Transform cost is O(frameCount × bandCount × N log N).
+No FFT, arbitrary JS, allocation or user callback is invoked by the native tick.
+
+Instantiate the existing `/sample` `residentSample`, then pass it with matching
+`frameLength`/`frameCount` to `bandedWavetableSource`. Load `prepared.data` with the
+resident's established native `event<{data:Float32Array}>` and `sample.load(data)`.
+The native event copies PCM at a block boundary. For the full layout the existing
+CAPACITY_16 ingress and 262144-byte payload reservation contribute 4 MiB of event
+arena, in addition to the 256 KiB resident and native I/O/state/metadata. The reader
+adds eight integer resident reads (16 underlying PCM taps), four local cycle
+interpolations and 76 bytes of declared scalar
+state before native alignment. Multiple sources can share the resident/ingress.
+There is no extra native PCM bank, new loader, streaming or upstream patch.
+
+A short or empty load is entirely silent with `missing=true`. Extra PCM after
+the required layout is ignored. Construction dimensions stay fixed; replacing
+with a different-dimensional asset requires a matching graph or intentionally
+adapted data. Length alone cannot certify harmonic content or identify a same-size
+layout mismatch. The caller must load the matching prepared layout. Arbitrary
+PCM is still protected by the resident's nonfinite-tap-to-zero rule; the native
+reader does not validate its spectrum or metadata.
+
+## Pitch bands, frame scan and state
+
+The controls and result match `WavetableControls`: `{frequencyHz, frame, reset}`
+and `{output, missing}`. The source rate is finite 8000..192000 Hz, fixed at
+construction. Resident `sourceSampleRate` does not affect cyclic pitch.
+
+`frequencyHz` is clipped to [0,.45 × sampleRate]. NaN/negative/negative infinity
+become0; positive infinity saturates at the upper limit. Zero Hz holds phase.
+`frame` is a fractional index clipped to [0,frameCount−1], with NaN→0. Neighboring
+frames interpolate linearly without frame-selector wrap or control smoothing.
+`phaseCycles` is the finite initial/reset phase in [0,1), default 0.
+
+For each bright band with limit H, its transition to the next darker band starts
+at .225 × sampleRate/H and finishes at .45 × sampleRate/H. The mix is linear in
+frequency. Transitions do not overlap; any gap holds the darker band. The last
+H=1 band is held through the accepted .45 × sampleRate frequency cap. Thus every
+represented positive table harmonic with nonzero band weight is below or equal
+to .45 × sampleRate for static playback. This statement concerns the retained
+base harmonics only, not the images of linear table interpolation.
+
+The reader retains each local fractional phase before adding the cycle base,
+fetches two integer-position resident reads per cycle, interpolates periodically
+within each of four cycles, then
+interpolates their two frame pairs and the pitch bands. Each cycle wraps to its
+own first sample, never to another frame/band. There is no output limiter or gain
+normalization. Pitch/frame control changes are instantaneous; rapidly jumping
+bands or frames is not click-free. Band transition continuity is a control-domain
+property, not a promise that arbitrary modulation adds no bandwidth.
+
+Reset is level-sensitive: emit the initial phase on that sample, then advance.
+A held reset repeats the initial phase while pitch-band/frame selection can vary.
+Every resident revision, including equal-length replacement and signed integer
+wrap, also restarts phase. There is no asset-replacement fade. Phase advances
+while an asset is missing; a subsequent load restarts it. Tiny frequencies and
+frame mixes use exact binary-scaled f64 control state; phase uses 2^1020 so even
+f64 `Number.MIN_VALUE` survives native scalar flushing. Arithmetic is unscaled
+before combining with PCM, and all declared state remains finite.
+
+Native snapshots include resident PCM, revision and reader state. Exact
+continuation is tested only for identical graph/configuration/sample rate. No new
+snapshot API or cross-schema/rate migration is promised.
+
+## Quality boundary and evidence
+
+Pitch bands reject high source harmonics that otherwise fold at high static
+pitch. Linear interpolation still attenuates retained harmonics and generates
+image aliases. The test suite explicitly measures one such residual image
+instead of labeling the reader brickwall-bandlimited. Rapid frame scan, FM/PM,
+reset, sync, warp and asset replacement can add bandwidth; static truncated
+assets do not make them alias-free. No automatic oversampling is added.
+
+Independent direct real-DFT preparation checks and Fourier coefficients verify
+retained/removed harmonics, DC/gain/phase, silent/edited frames and rejection of
+float32 overflow. Native tests cover 44.1/48/96 kHz, sweep and every band-transition
+boundary, frame morph, control extremes, held reset/zero Hz, missing/short/edited
+native assets, revision wrap, invalid/subnormal PCM, tiny phase/frequency/morph,
+full capacity and exact snapshot continuation. The packed isolated consumer
+imports only public `/wavetable` and `/sample`, checks strict types, loads full
+native assets, renders and compares an independent piecewise reader oracle,
+checks spectral content and replacement, and records source/package/audio hashes.
+
+Generated WAVs and manifests are CANDIDATE. Compile-driver memory/timing is
+reported with its unloaded-state limitation; loaded offline ingress/render tests
+are separate. These are neither human listening approval nor browser/hardware
+real-time performance proof.