@denaudio/den 0.0.0-stage → 0.2.0

package/docs/sources.md

@@ -0,0 +1,81 @@
+# Candidate source and resonator catalogue
+
+These modules extend the catalogue's FM/PM, additive, unison and tuned/modal resonator groups. They use unworklet 0.4.1 and the existing oscillator and delay-readhead. Existing instrument, voice policy, envelopes and initial presets are unchanged. Compose their outputs with the existing envelope/filter/voice instead of introducing another engine framework.
+
+All new audio is **CANDIDATE**, not a listening-approved golden. These modules are not a commercial-instrument equivalence claim. Sample, granular, spectral/FFT, arbitrary operator routing, automatic anti-aliasing and stochastic exciters are outside this slice.
+
+## Shared contract
+
+Import sources from `@denaudio/den/source` and resonators from `@denaudio/den/resonator`. Construct with `instantiate(module, config, {name})` inside processor declarations. Call each instance's `tick` exactly once per sample. `sampleRate` is an immutable finite number in [8000,192000], and must match the enclosing renderer. Offline evidence covers 44100, 48000 and 96000 Hz. Use separate named instances for separate voices/channels.
+
+All runtime controls and excitation must be finite f32 values. NaN/Infinity are outside the contract, not a musical mute/reset signal; upstream scrubbing is not validation or a quality guarantee. Out-of-range finite controls clamp as described below. Construction rejects invalid/nonfinite configuration and capacities. Core f32 precision and scalar-state flushing below 1e-30 still apply; no subnormal oscillator-frequency accumulation guarantee is made. No runtime allocation, arbitrary JavaScript callback, unbounded loop, asset load, smoothing or voice allocation is added. All loop counts are fixed at graph construction.
+
+The existing unworklet snapshot mechanism owns state. Same configuration/schema snapshots resume phases, feedback, modes and delay history exactly in the tested renderer. Reset is a sample-level boolean, not an edge detector. A caller wanting one reset should supply one true sample. Rate or structural configuration changes require a new graph; no cross-rate/cross-schema migration guarantee is made.
+
+## Phase modulation
+
+`phaseModulation({sampleRate}).tick({carrierHz, modulatorHz, depthRadians, feedbackRadians, reset})` returns mono f32.
+
+- Carrier/modulator frequencies clamp to [0,.45 sampleRate] Hz. Zero Hz holds phase.
+- Depth clamps to [-8π,8π] **radians**. Feedback clamps to [-π,π] radians.
+- At sample n, output is `sin(2π p[n] + depth[n] sin(2π m[n]) + feedback[n] y[n-1])`. The modulator and previous output are f32; accumulated phase and sine polynomial arithmetic use f64.
+- Output precedes phase advance by each current frequency/sampleRate. A frequency change preserves phase. Reset sets both phases and the previous carrier output to zero before this output. Held reset emits zero every sample. Initial phase and feedback are zero; no random seed or random phase is used.
+- Feedback is explicitly the final carrier output from the preceding sample, not current-sample algebraic feedback and not the modulator.
+
+## Frequency modulation
+
+`frequencyModulation({sampleRate}).tick({carrierHz, modulatorHz, deviationHz, feedbackHz, reset})` returns mono f32.
+
+- Base and modulator Hz clamp to [0,.45 sampleRate]. Deviation and feedback clamp to ±.45 sampleRate **Hz**.
+- Emit `sin(2π p[n])`, then advance the carrier by `clamp(baseHz + deviationHz sin(2π m[n]) + feedbackHz y[n-1], 0, .45 sampleRate)/sampleRate`.
+- This is positive-frequency linear FM with clipped negative instantaneous frequency, not through-zero FM. It is distinct from PM radians, including at changing depth and frequency.
+- Initialization, zero-frequency hold, reset and one-sample feedback source match PM. Held reset emits zero. There are two oscillator phases and one previous-output slot per PM/FM instance.
+
+Neither PM nor FM is bandlimited. Their legal frequency clamps do **not** constrain sidebands to Nyquist. Strong phase modulation, clipped FM, reset and feedback can alias. The fixture explicitly measures a folded PM sideband above 0.4 amplitude with legal carrier/modulator controls; this is evidence of the limitation, not an anti-alias test pass. Feedback can produce sensitive/chaotic waveform divergence while output remains in [-1,1].
+
+## Additive partial bank
+
+`additiveSource({sampleRate, partials:[{ratio,gain}, ...]}).tick(frequencyHz, reset)` returns mono f32.
+
+- 1–32 immutable sine partials. Ratio is finite in (0,128], signed gain in [-16,16]. Each reuses the existing sine oscillator.
+- Base frequency clamps [0,.45 sampleRate]. Requested partial frequency is base×ratio. A partial above .45 sampleRate is muted rather than accumulated at the clamp frequency. Its oscillator still advances at the existing oscillator's clamped frequency while muted, so re-entry does not restart phase.
+- All output weights are divided by the construction-time sum of absolute gains. All-zero gains produce silence. The denominator does not change when partials mute. Thus the output magnitude is at most one, without a limiter.
+- All phases initially zero; reset aligns all partial phases to zero, held reset emits zero. Each partial owns independent f64 phase and has fixed per-sample cost, even when muted or weighted zero.
+- Crossing a partial mute boundary is abrupt and unsmoothed. Dynamic modulation/reset can generate extra bandwidth; this is not a blanket anti-alias claim.
+
+## Unison stereo bank
+
+`unisonSource({sampleRate, waveform:'sine'|'saw', voices:[{detuneCents,pan}, ...]}).tick(frequencyHz, reset)` returns `{left,right}`.
+
+- 1–8 immutable oscillator voices. Detune cents is finite [-1200,1200], pan [-1,1]. Each voice reuses the existing sine or polynomial-BLEP saw oscillator.
+- Base frequency clamps [0,.45 sampleRate], then each voice multiplies by `2^(cents/1200)` and clamps again to .45 sampleRate. At high base frequencies, positive detuned voices can coincide at that ceiling; tests explicitly cover this.
+- For N voices, left weight is `(1-pan)/(2N)`, right weight `(1+pan)/(2N)`. This is **linear amplitude pan**, not equal-power pan. The channel sum L+R equals the average of the mono voices; an arithmetic mono fold-down `(L+R)/2` is half that average. Centered one-voice output is half amplitude per channel. Each channel remains bounded by one.
+- All phases initially zero and align on reset, with no random dispersion. Sine held reset emits zero; saw held reset emits the existing oscillator's phase-zero value (zero for positive frequency; -1 at exactly zero frequency). Frequency changes preserve phase.
+- A saw's existing BLEP does not imply arbitrary audio-rate modulation, feedback or resets are alias-free. No new quality mode is advertised.
+
+## Modal resonator
+
+`modalResonator({sampleRate, modes:[{frequencyHz,decaySeconds,gain}, ...]}).tick(input, reset)` returns mono f32.
+
+- 1–16 immutable modes. Mode Hz in [20,.45 sampleRate], amplitude T60 in [.005,30] seconds, gain in [-16,16]. Excitation clamps to [-1,1].
+- A mode has complex poles `r exp(±jω)`, where `r=exp(-ln(1000)/(T60 sampleRate))`, `ω=2π Hz/sampleRate`. Recurrence is `y[n]=sin(ω)x[n]+2r cos(ω)y[n-1]-r²y[n-2]`.
+- Unit impulse response is `r^n sin(ω(n+1))`. It starts on the current sample; T60 is the pole envelope decay, not a guaranteed peak ratio between arbitrary sampled extrema. The magnitude-response peak can differ from pole angle slightly.
+- Signed mode gains divide by their absolute sum. All-zero gains return silence. This bounds the **unit-impulse** response by one, not sustained resonant output. Sustained excitation can exceed unity by large amounts. With bounded input, a conservative weighted bound is the largest `1/(1-r)`. Long decay requires substantial downstream headroom/gain control; no limiter is included.
+- Reset clears both histories per mode before current excitation; held reset emits only the zero-history `sin(ω)×input` contribution each sample. Initial histories are zero. Two fixed f64 slots per mode store histories scaled by 2^128 to preserve legitimate tiny f32 tails through the upstream scalar-state flush; external units remain unchanged.
+- The modes form a fixed linear resonator bank after an explicitly clipped excitation stage, not a nonlinear physical string/plate model. Excitation waveform, envelope, velocity mapping and musical mode choices belong to the composition.
+
+## Tuned comb
+
+`tunedComb({sampleRate,minFrequencyHz}).tick({input,frequencyHz,feedback,damping,reset})` returns mono f32.
+
+- Minimum frequency is finite [20,.45 sampleRate]. Fixed buffer capacity is `ceil(sampleRate/minFrequencyHz)+2` f32 samples plus cursor/validity and damping state. Tick frequency clamps [minFrequencyHz,.45 sampleRate]. Delay is 1/frequencyHz seconds through the existing moving, linear-interpolated delay reader. Actual minimum delay exceeds two samples at the maximum frequency, and is always at least one sample.
+- Excitation is passed linearly, without a clipper. Supply finite input bounded by a known magnitude B with adequate f32 headroom. Feedback clamps [-.999,.999]. Damping clamps [0,1] and is the one-pole memory coefficient: `filtered=(1-damping)tap+damping*previousFiltered`. Zero bypasses damping; one freezes the filter history (zero when just initialized/reset).
+- Read the delayed tap, update damping, then write `(1-|feedback|)×input+feedback×filtered` into the line. Normalization is applied to excitation before storage. Return the raw delayed tap, with no instantaneous dry path. For fixed feedback this equals output-normalizing the conventional feedback comb, but changing feedback never rescales stored history. Reset invalidates history and zeroes damping **before** current excitation is written; held reset returns zero.
+- Input bounded by B, convex damping/interpolation and `|feedback|≤.999` give the ideal-arithmetic induction `|write|≤(1-|g|)×B+|g|×B=B`, including arbitrary finite feedback/frequency/damping changes. Reset/empty history is zero, so history, filter and output remain within B in ideal arithmetic. Unit-input tests use a 0.001 floating-point headroom allowance (scaled with B) and an independent normalized-history oracle and a retained executable counterexample for the rejected output-normalization topology; this is a normalized feedback network, not a brickwall limiter. Parameter edits still change the sound and can click.
+- Integer-delay undamped positive feedback has repeats every delay samples; negative feedback reverses alternate repeats. Fractional interpolation and damping change pitch and decay, so `frequencyHz` is the delay tuning control rather than a pitch-perfect physical-string guarantee. Moving delay produces Doppler behavior. Abrupt parameter changes/reset need caller-managed transitions if clicks are unwanted.
+
+## Verification and evidence
+
+`tests/source.spec.ts` independently checks Math.sin recurrence, Bessel sidebands, intentional folded alias, 32-partial peaks, detune ceilings, stereo normalization, reset, held reset and snapshots. `tests/resonator.spec.ts` checks analytical impulse/pole/T60 behavior, maximum 16-mode sustained excitation/headroom, tiny tails, signed comb repeats, damping freeze, moving-delay/feedback changes, fixed capacities and snapshots. Every in-contract render requires zero upstream scrubbed samples.
+
+`tests/source-packed.test.mjs` installs a fresh packed package using an exact consumer lock, checks public declarations/imports, renders all families at three rates, compares analytical references, verifies snapshot continuation, and records package/source/audio hashes and fixed-graph driver diagnostics. Evidence is local offline/Node driver evidence only, not browser/hardware real-time acceptance. The integration owner must still run exact-head CI and independent review. Candidate WAVs remain unapproved.

package/docs/spatial-chains-entry.md

@@ -0,0 +1,251 @@
+# Bounded hybrid space and feedforward pitched tail: proposed entry
+
+Status: entry, source and native/public-package evidence independently reviewed
+on 2026-10-06. Both entries remain CANDIDATE / NOT_CLEARED, with no human,
+hardware or realtime acceptance.
+
+## Finite catalog scope
+
+This is one concrete mono-input/stereo-output composition for catalog groups 10
+and 12, plus one explicitly feedforward pitched-tail variation. It composes the
+reviewed `partitionedConvolution`, `multiTapDelay`, `algorithmicReverb` and
+`windowedPitchShift` modules without modifying them. The convolution shapes three
+early reflections; the parallel damped FDN supplies the late tail. The variation
+pitch-shifts only a copy of the late output. Nothing from either pitch reader is
+returned to the FDN or early-reflection input.
+
+This is not regenerative feedback shimmer, a long measured-room convolution, a
+physical room model, transparent pitch shifting, or completion of those broader
+catalog categories. Existing frozen-tail support remains separate.
+
+## Proposed public API
+
+One new subpath, `@denaudio/den/spatial-chains`; no root-entry re-export:
+
+- `hybridReverb({ sampleRate, renderQuantumSize }).tick(input, controls, everyNSamples)` returns
+  `{ left, right }`.
+- `feedforwardPitchedReverb({ sampleRate, renderQuantumSize, windowSamples? }).tick(input,
+  controls, everyNSamples)` returns `{ left, right, ratioRejected }`.
+- `SpatialChainConfig`: integer `sampleRate` in 8000..192000, taken from the
+  enclosing `ctx.sampleRate`, and positive integer `renderQuantumSize` from
+  `ctx.renderQuantumSize` for the early convolution's snapshot-safe dispatch.
+- `FeedforwardPitchedReverbConfig`: same rate plus even integer `windowSamples`
+  in 32..16384, default 2048. This is the pitch delay excursion, not a grain or
+  FFT-frame duration.
+- `SpatialChainControls`: f32 `mix`, boolean `bypass`, boolean `reset`.
+- `FeedforwardPitchedReverbControls`: the same controls plus f32 `ratio`, f32
+  `pitchMix`, and boolean `retrigger`.
+
+Call exactly once per sample in a stride-1 `forSample`, passing its native
+`everyNSamples`. Construction is fixed. There is no IR ingress, runtime topology
+change, alternate scheduler, preset engine or custom snapshot mechanism.
+
+`mix` and `pitchMix` must be finite and clamp to [0,1]. `ratio` uses the reviewed
+pitch reader's inclusive [.5,2] acceptance; invalid/nonfinite values retain its
+last accepted ratio, or 1 on reset. A valid ratio is accepted during reset.
+`ratioRejected` describes rejection of the current ratio. Both channel readers
+receive identical controls and therefore have the same phase and rejection.
+
+## Literal topology and gains
+
+Let x be the input unless bypass or reset is true, in which case excitation is
+zero. The unchanged public modules are composed as follows:
+
+1. Convolve x with B=8, N=16, one fixed eight-tap original FIR:
+   h=[.625,0,0,.25,0,0,0,-.125]. Its L1 gain is 1 and DC gain is .75.
+2. Feed that convolution to `multiTapDelay` with `maxDelaySeconds=.023`,
+   feedback=0, mix=1 and bypass=false. Its three fixed taps are:
+   (.007 seconds, left .5, right .25),
+   (.013 seconds, left .25, right -.25),
+   (.023 seconds, left -.125, right .375).
+   The existing normalization divisor is exactly 1; each channel's L1 sum is
+   .875. Call this stereo early output E.
+3. Independently feed (x,0) to `algorithmicReverb` with roomScale=1,
+   decaySeconds=.6, dampingHz=min(3500,.4*sampleRate), mix=1, bypass=false.
+   Call this stereo late output F. No early signal enters the FDN.
+4. Plain hybrid wet output is .5*E+.5*F.
+5. The pitched variation applies one reviewed moving-window reader to each F
+   channel. Let that output be Q(F). Its late blend is
+   T=(1-pitchMix)*F+pitchMix*Q(F), and wet=.5*E+.5*T.
+6. The final output is (1-mix)*originalInput+mix*wet, with mono dry copied to
+   both channels. Use f64 for the wrapper blend and convert once to f32.
+
+The plain entry has no pitch readers or pitch allocation. The two entries may
+share a private construction helper, not a new exported routing abstraction.
+
+Supply finite normalized input [-1,1]. The FIR output fits the existing
+multitap/convolution operating range and |E|<=.875*peak|input| in real arithmetic.
+Start auditions around input peak .25 to leave working headroom; this is a
+recommended level, not a proved output ceiling. FDN peaks can exceed unity.
+There is no limiter, automatic normalization or output saturation.
+
+The unmodified FDN keeps its fixed contractive feedback and damping. For a
+finite-energy mono input from zero state its existing conservative wet L2 bound
+uses 1/(1-qMax), where qMax=10^(-3*dMin/(sampleRate*.6)). Pitch is strictly outside
+that loop. Convex interpolation/window weights bound each pitched sample by the
+largest retained late sample, but do not imply energy preservation: a moving
+reader can repeat, omit or cancel input. Do not transfer the FDN's orthogonality
+claim to a hypothetical pitch-in-feedback implementation.
+
+## Timing, phase and finite storage
+
+Dry is immediate. There is no host latency compensation or hidden dry alignment.
+The early FIR contributes exactly 8 samples of scheduling latency. It is not
+linear phase, so its coloration has frequency-dependent group delay. Its impulse
+support is 0..7 before that scheduling delay. Reflection tap times are fixed
+f32-seconds requests through the reviewed linear readhead, not exact integer
+delays: effective d=clamp(sampleRate*fround(seconds),1,.023*sampleRate).
+Their fractional interpolation must be included in the numerical oracle.
+
+The first ideal early support is at 8+floor(d7ms). The last ideal early support
+after a last nonzero input at n is no later than n+8+7+ceil(d23ms), subject to
+native floating-point residuals. This 7..23 ms reflection geometry does not
+rescale the eight FIR samples with rate.
+
+The FDN's four lengths are round(sampleRate*[.0297,.0371,.0411,.0437]). Its f32
+seconds readhead boundary can introduce the existing tiny fractional difference.
+First late arrival is near 29.7 ms, and the damping filters add frequency-dependent
+loop group delay. The .6 second setting specifies loop loss, not a hard tail
+cutoff or exact measured RT60. There is no finite mathematical drain for the
+IIR tail. Continue processing zeros or reset it.
+
+Pitched read ages are 1..W+1 after the FDN output. After reset/retrigger, ratio=1
+gives exactly 1+W/2 samples of extra delay. Other ratios, or unity after arbitrary
+modulation, have no single latency. Parallel pitched/unpitched mixing may comb or
+cancel. Linear reads can alias; coherent and noncoherent pitch behavior must both
+be retained as evidence. If the late input to a reader actually becomes zero,
+that reader is silent from its last nonzero sample+W+2 onward; the FDN itself has
+no such finite cutoff.
+
+Storage is the sum of unchanged modules:
+
+- Three reflection histories, each ceil(.023*sampleRate)+2 f32 values.
+- Four FDN histories, each ceil(sampleRate*(d_i/sampleRate))+2 f32 values,
+  including any existing floating-point ceiling guard; four damping states.
+- One B8/P1 convolution: 8 f64 input, 2*16 f64 previous spectrum, 16 f64 overlap,
+  2*16 f64 mixed scratch and 4*16 f64 FFT scratch values, plus native scalar state.
+- Pitched entry only: two (W+3)-value f64 histories, i.e. 16*(W+3) bytes, plus
+  native cursors, valid counts, phases, accepted ratios and transient wet slots.
+
+These are construction-fixed. Actual compiled/native instance memory includes
+runtime, scalar and port overhead and will be measured. No callback allocation
+or buffer growth is introduced. The FDN/reflection f32 histories inherit their
+existing very-small-state precision/scrub behavior; this wrapper does not promise
+retention of all subnormal input magnitudes.
+
+## Controls, reset, bypass and native restoration
+
+Reset has highest priority: emit zero even when bypass is true, suppress the
+current excitation, invalidate every module's history and reset pitch phase.
+Held reset remains silent and discards every reset sample. Native convolution
+hop phase is preserved. This explicit wrapper behavior is stricter than the
+underlying FDN/multitap reset-accepts-current-input contract.
+
+Bypass emits unity dry, admits no new wet excitation, and continues all internal
+tail/readhead processing. It does not save CPU; removing bypass reveals the then
+current tail. mix=0 still excites and advances both wet branches. pitchMix=0 still
+advances the pitched entry's readers. Retrigger resets both pitch phases before
+their current read, retains history and can click. No smoothing or universally
+click-free automation, reset, retrigger or bypass is claimed.
+
+Use only native same-rate, same-quantum, same-schema snapshots. Every inherited persistent
+history/cursor/valid count, convolution scheduling state, FDN damping state and
+pitch ratio/phase persists; transient scratch must be rewritten before use.
+Restore requires the same configuration and coordinated input/control timeline.
+The existing non-atomic core 0.4.1 AudioParam/state restore boundary remains:
+render and verify saved controls before browser restoration. Native offline
+quantum continuation is a separate exact test, not a claim of atomic live restore.
+
+## Required independent evidence
+
+Before acceptance: independent absolute-time FIR/tap/FDN/pitch references at
+44.1/48/96 kHz; impulse arrivals and path signs; linear dry/wet and pitch endpoints;
+simultaneous versus separate-path algebra; normalized bounded excitation and
+finite zero-scrub output; every B8 reset phase; held reset and reset+bypass;
+bypass admission/re-entry and uninterrupted tails; pitch rejection, retrigger and
+known coloration/cancellation; same-schema noninitial quantum restoration with
+poisoned transient scratch; minimum/maximum valid capacities and fixed memory.
+
+Integration requires actual packed public imports/declarations, native three-rate
+rendering and an actual small 48 kHz browser composition with independently
+predicted phase/gain or sample waveforms, control edits/reset and correctly
+coordinated native restore. Diagnostic costs retain cold/warm misses and do not
+certify realtime behavior. Candidate audio stays CANDIDATE and hashed.
+
+## Initial native verification
+
+On 2026-10-06 the new source passed `npm run check` and all 20 focused cases in
+`tests/spatial-chains.spec.ts`. The absolute-time reference includes f32 fraction,
+multiplication, addition and storage boundaries of the inherited readheads. The
+three-rate tests cover the complete chain equations, signed reflection arrivals,
+every B8 reset phase, reset+bypass priority, native same-schema continuation,
+and bypass re-entry after suppressed excitation with a continuing nonzero tail.
+The pitched entry at pitchMix=0 is bit-identical to the plain hybrid output.
+
+The full-composition W64/ratio2 counterexample removes independently predicted
+early output and finds no intended doubled-frequency late component for a
+128-sample-period input, while an original-frequency component remains. It is
+retained as a pitch-quality limitation, not promoted by a waveform-oracle pass.
+
+Native capacity/scratch probes at 8/44.1/48/96/192 kHz, including W32 and W16384,
+keep memory fixed, produce finite output with zero nonfinite-output scrubs, and
+match the scalar oracle within the predeclared 2e-6 absolute tolerance under
+normalized square-wave excitation. Poisoning all 11 declared transient scalar
+temporaries and six transient work buffers leaves subsequent audio bit-identical.
+The separate public snapshot test restores serialized persistent histories;
+the poisoning probe clones native memory only as a test of scratch independence.
+
+The guarded source/type/native batch completed in 15.35 seconds, with 486,039,552
+bytes maximum summed process-group RSS. This process measurement is not a
+per-quantum deadline result. Actual browser worklet and exact-head aggregate CI
+remain separate acceptance requirements. No human listening or hardware clearance
+follows.
+
+## Packed and independent review evidence
+
+`tests/spatial-chains-packed.test.mjs` checks strict public declarations, both
+actual public subgraphs, native a-rate mix/ratio/pitchMix and input controls at
+44.1/48/96 kHz, and the W16384/192 kHz maximum. The first clean packed proof at
+commit `b173a3e` had maximum absolute waveform error 2.981e-8, bit-identical suffix
+PCM and final native snapshots, fixed memory and zero nonfinite-output scrubs.
+Both distinct Vite WASM/worklet bundles were built; building is not browser
+execution. Three hashed five-channel WAVs retain raw input and stereo outputs
+as finite CANDIDATE excerpts, with no normalization or complete-tail-drain claim.
+
+The local-only dependency reuse option is rejected in CI. It requires the exact
+locked non-target resolutions, creates a private installed target from the new
+tarball, preserves the donor tar/lock/installed target, and fingerprints every
+non-target dependency package before and after. The first proof verified all of
+those identities unchanged. CI retains the isolated fresh-install path.
+
+The packed process batch completed in 14.61 seconds with 776,314,880 bytes maximum
+summed process-group RSS. Loaded native measurements include host input/parameter/
+output copies over 256 quanta per profile:
+
+| Rate | Hybrid cold / warm max | W512 pitched cold / warm max | Quantum budget |
+| --- | --- | --- | --- |
+| 44.1 kHz | 3.203 / .711 ms | 3.694 / 3.723 ms | 2.902 ms |
+| 48 kHz | 3.242 / .942 ms | 3.302 / 1.326 ms | 2.667 ms |
+| 96 kHz | 3.398 / 1.712 ms | 5.530 / 2.402 ms | 1.333 ms |
+
+Every measured profile missed its cold deadline; some warm maxima also missed.
+The maximum pitched configuration used 458,752 native bytes and 54,056 WASM
+bytes with no memory growth. These observations preserve NOT_CLEARED and do not
+predict browser scheduling or hardware capacity.
+
+An independent review imported neither the author processor nor its scalar
+oracle. It compared all 182 installed package files against the actual tarball
+and passed 16 native/public groups. A separate 4-by-4 complex FDN resolvent,
+combined with the FIR/fractional taps, dry path and initial unity-pitch delay,
+predicted both channels at four simultaneous coherent frequencies. Across both
+entries and 44.1/48/96 kHz, maximum complex-transfer error was 9.664e-10 against a
+predeclared 2e-6 tolerance. Independent reset/bypass/mix, ratio rejection including
+NaN/infinities, native snapshot and minimum/maximum capacity probes also passed.
+
+The independent 8 kHz headroom witness used mix=1 and input +1 for residues
+0..127 of each 257-sample period, -1 for residues 128..256, then zero after sample
+8191. Hybrid output reached 1.131077647; the W32 variant at ratio=1 and pitchMix=1
+reached 1.088592649. These concrete unclipped peaks confirm that normalized input
+can exceed unity at output. They are examples, not peak ceilings. Independent
+source/native review found no implementation blocker; browser, final-head CI,
+listening and realtime acceptance remain separate.

package/docs/spectral-freeze-entry.md

@@ -0,0 +1,132 @@
+# Bin-centered spectral freeze candidate
+
+Source scope: catalog group 11, [Pitch / time / STFT / spectral engine](https://app.notion.com/p/3ef449b4e81d817db1acf1fff48779b3).
+This separate native STFT effect is not the FDN reverb freeze. It uses the reviewed
+STFT/FFT sources unchanged, with a bounded construction-time spectrum hook.
+CANDIDATE only: no human sound approval, browser/realtime clearance, transparent
+sustain, phase-vocoder or phase-locking claim.
+
+## Public contract
+
+`spectralFreeze({ size, hopSize, renderQuantumSize: ctx.renderQuantumSize }).tick(input, freeze, reset, everyNSamples)`
+
+- Instantiate once with an explicit subgraph name. Call exactly once per sample
+  inside stride-1 `forSample`, supplying its existing `everyNSamples`.
+- Construction-fixed power-of-two N=8..1024; H=N/2 or N/4. Input is finite,
+  normalized f32 in [-1,1]. `freeze` and `reset` are boolean graph nodes, not
+  thresholded or smoothed floating-point parameters.
+- A committed frame at t=mH consumes [t-N,t). Freeze is sampled at t. The first
+  high sampled frame captures its complex spectrum; the current input sample
+  is excluded. Missing startup/reset history is zero padded. Capturing at t=0
+  therefore holds silence until release/reset and a later capture.
+- Subsequent high frames hold the captured magnitudes and advance each bin's
+  phase by +2*pi*k*H/N per frame. No actual-frequency estimator, phase locking,
+  neighboring-bin rule, formant preservation or transient detector exists.
+- Only nonnegative bins are stored. DC and Nyquist imaginary values are zero;
+  negative-frequency bins are reconstructed as complex conjugates. Since legal
+  H is even, Nyquist advances by an integer number of full turns and stays real.
+- H=N/2 or N/4 makes the phase advance an exact +/-1 or +/-i rotation. An integer
+  modulo-(N/H) counter rotates the original captured values, avoiding cumulative
+  rotation drift. All captured values retain the reviewed internal 2^128 scale
+  so the existing 1e-30 buffer-write flush does not discard f32 subnormal audio.
+- Low freeze releases on that committed frame. Live input and analysis history
+  continue during hold, so release uses the latest live frame. An unsampled low
+  pulse cannot rearm capture. A low committed frame followed by a high committed
+  frame releases and recaptures. Between-frame freeze edits have no effect.
+- Keeping freeze=false from initialization, or after a reset that discards prior
+  frozen overlap, uses the original unmodified spectrum and preserves identity
+  PCM exactly. On release, already scheduled frozen overlap may remain and
+  settles within N samples of the committed release frame; identity PCM is
+  restored after that overlap settles. New freeze state makes its schema distinct; interchange
+  with identity-module snapshots is not supported.
+
+## Phase meaning and transitions
+
+For captured analysis frame a[n]=input[t0-N+n]*sin(pi*n/N), a positive phase
+increment means the inverse transform on held frame t is exactly the circular
+left shift a[(n+t-t0) mod N], in ideal arithmetic. This equivalence is used as a
+separate, linear-cost numerical oracle, alongside dense complex DFT/IFFT tests.
+It also describes an important limitation: the captured analysis window is part
+of the held texture. Steady held output is N-periodic and can have pronounced
+window-related amplitude modulation, even for an on-bin sinusoid. Off-bin input
+is altered into a periodic texture. This is a deterministic bin-centered freeze,
+not a claim to preserve a tone's instantaneous frequency or smooth envelope.
+
+Both windows remain the periodic sqrt-Hann sin(pi*n/N), with WOLA gain 2H/N.
+There is no extra transition ramp, fade parameter, dry path, limiter or level
+normalization. Capture and release replace newly committed frames; already
+scheduled overlap remains. The transition settles within N samples of the
+committed edge, and the edge itself is delayed by less than H samples from a
+persistent control request. Smear, ringing, periodic beating and altered peaks
+are expected. WOLA overlap alone is not an artifact-free-transition guarantee.
+
+The live reference alignment is N samples. Processed onset is frame-dependent;
+N is not a universal first-nonzero delay for held content. There is no finite
+zero-input drain while held. After freeze is kept low and the source ends,
+provide at least 2N zero samples from the later of source end and release request.
+This conservatively includes the next sampled release and outstanding overlap.
+
+## Reset, snapshots and execution
+
+Reset silences output immediately and discards that input sample. It invalidates
+the hold and clears its integer phase immediately, without rephasing the absolute
+frame clock. High freeze can capture again at the next non-reset committed frame.
+Held reset prevents capture. Captured buffer bytes are logically invalidated,
+not physically scrubbed; a later capture overwrites every stored bin before use.
+The framing's existing pending reset discards prior history and overlap.
+
+Persistent state contains the existing history/overlap/cursor/reset state, two
+(N/2+1)-element f64 capture planes, the hold flag, held phase and a private
+modulo-H sample clock. The latter mirrors the reviewed framing cursor%H; neither
+clock changes phase on reset. Frame controls and capture decisions are transient.
+Full snapshots continue exactly for the identical graph, configuration, rate
+and quantum.
+Tests cover inactive, frozen, post-reset and release/rearm states at every
+native block-aligned snapshot offset class, including non-128 boundaries.
+No cross-rate, cross-quantum or cross-configuration migration promise is added.
+
+The shared STFT dispatch runs every `gcd(H, 128, renderQuantumSize)` samples.
+The FFT, hook and IFFT execute eagerly, but only true t=mH frames capture,
+advance the held phase or commit overlap. These extra hook calls do not change
+persistent capture/hold phase. No CPU saving is implied by a select; smaller or
+coprime quanta increase workload as documented in the [spectral contract](spectral.md).
+
+## Headroom derivation
+
+In ideal real arithmetic, every input analysis frame has Euclidean norm at most
+sqrt(N), because |input[n]|<=1 and |window[n]|<=1. A complex DFT followed by its
+properly scaled inverse preserves this norm; multiplying each bin by a unit
+phase factor preserves it too. Every live or held inverse-frame sample is thus
+bounded by sqrt(N). At an output sample, at most N/H synthesis frames overlap,
+each with |window|<=1 and scale 2H/N. The triangle inequality gives
+(N/H)*(2H/N)*sqrt(N)=2*sqrt(N), at most64 for N1024. The same argument covers
+capture/release overlap between different frames. A tighter bound is possible
+using the actual window energy; this deliberately conservative bound suffices.
+
+This is a mathematical headroom bound for normalized inputs, not a numerical
+roundoff theorem. Finite-f64 FFT error and final f32 rounding are separately
+measured against independent oracles; no limiter enforces the bound. Unexpected
+nonfinite or out-of-range audio input is outside the contract.
+
+## Validation requirements
+
+Independent dense DFT/positive-phase rotation/IFFT/time-indexed WOLA, plus the
+separate circular-left-shift oracle; DC/Nyquist, coherent/off-bin tones, capture
+exclusion of current input, frame-edge controls, both legal hops, all small and
+large reset offsets, held reset, snapshot phases, subnormals, normalized extrema,
+held sustain and release drain at44.1/48/96kHz. Existing no-hook graph/schema/PCM/
+snapshot compatibility remains unchanged. An isolated installed public-package
+consumer must typecheck, render, restore, report memory/cold/warm costs and build
+its Vite worklet before package acceptance. Audio evidence is CANDIDATE, with
+source/package/audio hashes and no per-channel normalization.
+
+## Initial focused evidence
+
+The first typecheck and25-test run passed:19 freeze tests,3 exhaustive large-reset
+cases and3 unchanged no-hook identity compatibility cases across44.1/48/96kHz.
+It completed in45.4seconds with718MB observed process-group RSS under a180second/
+2GiB guard. The native DSP, dense-DFT WOLA and circular-shift WOLA agree within
+2e-7 absolute normalized amplitude; tiny-input assertions scale the tolerance down
+to one f32 subnormal ULP. Live identity PCM and full-snapshot continuation are
+bit exact. The reviewed shared FFT/STFT files were not modified. This focused
+pass does not substitute for independent review or public-package validation.

package/docs/spectral-gate-entry.md

@@ -0,0 +1,134 @@
+# Framewise spectral gate entry proposal
+
+Status: root-approved bounded entry; implementation validation is separate. Source scope: catalog group
+11, [Pitch / time / STFT / spectral engine](https://app.notion.com/p/3ef449b4e81d817db1acf1fff48779b3).
+This is one bounded spectral effect built on the independently reviewed
+`4be1c9991459ea559102a5fa8fd76fb3d52a94b9` STFT framing.
+
+## API and meaning
+
+- `spectralGate({ size, hopSize, renderQuantumSize: ctx.renderQuantumSize }).tick(input, threshold, floor, reset, everyNSamples)`
+- Construction-fixed power-of-two N=8..1024 and H=N/2 or N/4.
+- Input: finite normalized f32 audio in [-1,1]. Controls: f32. Threshold is clamped to [0,max-f32], floor to [0,1];
+  infinities saturate, NaN threshold becomes 0 and NaN floor becomes 1 (all-pass).
+- A committed frame at sample t=mH consumes [t-N,t). It samples threshold and
+  floor at t. The current input sample is not part of that frame. Between-frame
+  control values do not retroactively modify already scheduled overlap audio.
+- With w[n]=sin(pi*n/N), W=sum(w), and forward unnormalized DFT X, the gate level
+  is |X[k]|/W for DC/Nyquist and 2|X[k]|/W for other nonnegative bins. These are
+  linear, coherent-window-calibrated single-sided bin amplitude units. They are
+  neither RMS, dB, noise power density nor an exact off-bin sinusoid amplitude.
+- Computed level >= threshold gives gain 1; otherwise gain=floor. One decision
+  applies to the conjugate pair. DC/Nyquist imaginary components are zero.
+  Floating roundoff can determine either result exactly at a threshold boundary.
+- No attack/release, hysteresis, adaptive noise profile, gain interpolation,
+  makeup normalization, limiter, dry path or bypass scheduler. Threshold 0 or
+  floor 1 is the all-pass limit. Low bins may contain positive/negative-frequency
+  window-lobe interference; threshold units remain the stated bin formula.
+
+## Framing, state and headroom
+
+Retain the original periodic sqrt-Hann analysis/synthesis windows, normalization
+2H/N, reset discard semantics and persistent cursor. Dispatch now follows
+`gcd(H, 128, renderQuantumSize)` to align every native snapshot boundary; only
+cursor%H==0 commits frames. Off-phase FFT/IFFT work is eager. See the shared
+[spectral contract](spectral.md) for increased costs at small or coprime quanta;
+there is no H-rate CPU-saving claim.
+
+The WOLA alignment/reference delay is N samples; a processed transient can spread
+across its synthesis frame [t,t+N), so its first nonzero sample need not occur at
+input onset+N. The all-pass limit retains exact N-sample delay. Drain at least 2N
+zero input samples after the source ends. Spectral processing can spread the last
+input through the rest of its analysis frame and then through a synthesis frame;
+the identity-only N-sample drain is insufficient for the gate. Reset silences immediately, discards that input sample, clears
+old history/overlap and leaves absolute frame phase unchanged.
+
+Only the existing history, overlap, cursor, valid history and pending reset need
+persistent storage. Frame controls and spectrum work are transient and overwritten
+before use. Identical graph/rate/quantum full-snapshot continuation remains in scope.
+
+Attenuating bins can increase individual time-domain peaks. For normalized input,
+an ideal contraction bound per frame and the overlapping windows give the
+conservative output bound 2*sqrt(N), at most64 for N1024. This is headroom guidance,
+not a limiter or loudness promise; measured peaks accompany candidate evidence.
+
+## Implementation boundary and verification
+
+The original gate entry added a narrow optional internal construction-time
+spectrum-copy hook to the
+existing STFT function. The identity branch must produce the same graph, schema,
+PCM and full snapshots as its frozen predecessor. The 0.2.0 compatibility
+migration separately replaces fixed-quantum FFT loops and extends snapshot-safe
+dispatch; its numerical and continuation assertions preserve this gate behavior. The public gate wrapper is separate; shared
+exports, CI and site belong to integration.
+
+Required tests: independent direct DFT/bin-mask/inverse-DFT/time-indexed WOLA;
+DC, Nyquist, on/off-bin tones, mixed strong/weak bins, threshold units and equality
+limits, conjugate symmetry, frame-sampled controls around hop/block boundaries,
+all reset phases, held reset, tiny f32 signals, finite normalized extrema and
+headroom, all quantum-offset snapshot phases, and 44.1/48/96kHz renders. A clean
+installed public package must typecheck, render, restore and build a Vite worklet.
+Document fresh compile/cold/warm costs, fixed memory and zero scrub observations.
+
+Expected artifacts include musical noise from hard decisions, ringing, transient
+smear, pumping under threshold edits and changed peaks. Neither identity proof nor
+numerical correctness means artifact-free sound. CANDIDATE only: no human sound,
+browser realtime, pitch shifting, phase vocoder, long-IR or den-kit claim.
+
+
+## Internal numeric details
+
+History and FFT spectra retain the existing exact factor 2^128. The gate compares
+`factor*(Re(Xscaled)^2+Im(Xscaled)^2)` against `(threshold*W*2^128)^2`, where factor
+is 1 for DC/Nyquist and 4 for the other bins. Double precision safely contains
+both sides over the full finite f32 control range. The comparison needs no
+runtime square root or dB conversion. Floor gains are stored multiplied by
+2^128 so even the smallest positive f32 floor is not silently flushed by the
+existing buffer-write policy. One gain is calculated and stored for each
+nonnegative bin; the negative bin is reconstructed from that canonical member.
+
+Threshold 0 and floor 1 explicitly choose the original unmodified spectrum.
+This preserves identity PCM exactly, rather than relying on re-mirrored FFT
+roundoff to round identically. No FFT work is skipped by these eager selects.
+The internal hook exists only during graph construction and is not an additional
+public `stftIdentity.tick` argument or an arbitrary runtime callback.
+
+## Focused validation
+
+The first bounded implementation run passed all49 tests in the seven spectral,
+convolution, gate and hook-compatibility files at44.1/48/96kHz. It completed in
+72.9seconds with549MB observed process-group RSS under a120second/2GiB guard.
+Existing FFT/STFT/convolution tests and numerical tolerances were unchanged.
+
+The no-hook construction produced byte-identical WASM and schema, exact PCM and
+full snapshots against the frozen4be1c99 STFT at N8/64/256/512/1024 and both large
+hop classes. Bidirectional restoration was also exact. Gate tests separately
+cover every large reset phase, every quantum-offset snapshot phase, held reset,
+frame-sampled edits, DC/Nyquist and off-bin cases, NaN/infinite controls,
+subnormal audio and controls, and actual transient spread/peak overshoot.
+
+The isolated packed consumer records its exact source/package/audio hashes,
+three-rate DFT/WOLA errors, restore equality, fixed memory and fresh/warm local
+Node costs. It also emits a CANDIDATE48kHz three-channel WAV: original source,
+N-aligned reference, and gate output, with no per-channel normalization. This is
+an audition artifact, not a human-approved golden. Its Vite build is compilation
+evidence, not browser audio or realtime clearance.
+
+A follow-on21-test gate run extends active tiny-control, normalized-extreme
+headroom and strong/weak partial separation checks to all three rates. It passed
+in16.4seconds with506MB observed process-group RSS. The DSP did not change between
+these runs; the unchanged seven-file suite plus these additions contains56 tests.
+
+
+## Processed-tail correction
+
+Independent review retained a concrete counterexample to the earlier N-zero
+drain statement: N64/H16, an impulse at sample127, threshold0.035 and floor0.
+An N-zero drain ends before sample192, but processed output continues through
+sample223, with a post-cutoff peak around0.02336. This is expected spectral
+spreading, not a framing-state defect. The conservative public drain requirement
+is now2N zero-input samples. A regression checks that the N cutoff loses nonzero
+output and that output is exactly zero after the2N cutoff at all three rates.
+The corrected audition preserves its original source samples and appends another
+N zeros, providing a complete2N drain. Prior truncated audition artifacts must
+not be used as the completed effect candidate.