@denaudio/den 0.0.0-stage → 0.1.0

package/docs/dynamics.md

@@ -0,0 +1,180 @@
+# Dynamics and envelope follower candidate
+
+Status: **CANDIDATE**. Implements the single-band detector/gain-law part of
+[catalog sections 5 and 9](https://app.notion.com/p/3ef449b4e81d817db1acf1fff48779b3).
+It is not a lookahead/true-peak limiter, multiband processor, or an assertion of
+listening approval. The original voice feedback concerned earlier candidates,
+not these algorithms or generated clips. Independent final review and aggregate integration verification remain
+separate gates.
+
+## Composition and boundaries
+
+Public candidate subpath: `@denaudio/den/dynamics`, added with integration-owner
+approval. The packed fixture requires this export and records its tested import. No new routing, parameter, snapshot, asset or runtime API is
+introduced. Use the existing unworklet `instantiate` and stable unique names.
+
+- `envelopeFollower`: reusable mono peak or RMS detector. Configuration is
+  `{ sampleRate, mode: 'peak' | 'rms' }`; `tick(input, controls)` returns a
+  nonnegative f32 amplitude. Controls are `attack`, `release`, `reset`.
+- `compressorGainDb(levelDb, controls)` and `expanderGainDb(levelDb, controls)`:
+  stateless downward gain laws, returning dB gain in `[-rangeDb, 0]`.
+- `dynamics`: stereo feedforward composition. Configuration adds
+  `operation: 'compressor' | 'expander' | 'gate' | 'duck'` and optional fixed
+  `hysteresisDb` (default 3 dB, allowed 0–24 dB).
+- Call `tick(left, right, sidechainLeft, sidechainRight, controls)` exactly once
+  per sample. Results are `left`, `right`, `envelope`, linear `gain` and `gainDb`.
+  Pass the program L/R again as sidechain L/R for internal detection. Mono callers
+  duplicate their input explicitly. An external key never becomes audible audio.
+- Controls use existing f32 Nodes. `reset` is a boolean Node. Construction rate
+  must be an integer in 8000–192000 Hz and must match the processor's compile rate.
+  Mode and operation are construction-time choices, not dynamic CPU bypasses.
+
+No makeup gain, automatic normalization, mix, bypass, sidechain filter, hold,
+lookahead, feedback topology, channel adaptation or latency compensation is
+hidden in this composition. The program path has zero sample delay. Finite
+program audio is not clipped at full scale, and gain never exceeds unity.
+
+## Detector and gain ballistics
+
+For a peak detector, the target is `abs(input)`. RMS uses `input²` as its target,
+smooths **power**, then returns the square root. RMS is an exponentially weighted
+power measurement, not a rectangular finite window or a true-peak estimate.
+
+For either target, choose attack when target exceeds prior state and release
+otherwise. With positive time `t`, the one-pole coefficient is
+`c = 1 - exp(-1 / max(1, t * sampleRate))`; update by `(1-c)*previous + c*target`.
+Times are seconds, clamped to 0–30. Positive sub-sample times use one sample as
+the time constant. Exactly zero is instantaneous. A constant rising peak step
+reaches `1-exp(-1)` after one time constant; an RMS power step reaches its square
+root at that time. These meanings differ from a 10–90% timing convention.
+
+In `dynamics`, `detectorAttack`/`detectorRelease` control the above measurement.
+`attack`/`release` separately smooth the requested positive attenuation in dB:
+
+- Compressor/duck: attack increases attenuation; release returns toward unity.
+- Expander/gate: attack opens the gain; release increases attenuation.
+
+Time edits take effect on the current sample without clearing history. There is
+no implicit gain smoothing in the two standalone gain-law functions. Using zero
+times or editing range/threshold abruptly can create discontinuities. Gain
+smoothing prevents a hard keyed jump when its times are nonzero, but this is not
+a perceptual guarantee against pumping, clicks or modulation artifacts.
+
+## Static laws and stereo behavior
+
+`DynamicsGainControls` contains:
+
+| Control | Unit and range | Nonfinite fallback |
+| --- | --- | --- |
+| thresholdDb | dBFS, -120…24 | 0 |
+| ratio | 1…100 | 1 |
+| kneeDb | full width, 0…48 dB | 0 |
+| rangeDb | maximum attenuation, 0…120 dB | 120 |
+
+For compressor input level `x` and threshold `T`, the hard-knee output level is
+`x` below threshold, and `T + (x-T)/ratio` above it. Within a positive knee width
+`W`, the gain is `(1/ratio-1)*(x-T+W/2)²/(2W)`. The outer pieces meet with
+continuous value and first derivative.
+
+For downward expansion, the output slope below threshold is `ratio`, and the
+slope above threshold is 1. Within the knee, gain is
+`-(ratio-1)*(x-T-W/2)²/(2W)`. The attenuation of both laws is capped by `rangeDb`.
+Ratio 1 or range 0 gives unity. Gain-law level inputs are bounded to -900…900 dB,
+with -900 dB substituted for nonfinite values. This is a defined numerical
+boundary, not a limiter ceiling.
+
+Gate/duck use a hysteretic comparator. The key becomes active at or above
+threshold; it stays active until its measured level reaches or drops below
+`threshold-hysteresisDb`. Gate requests zero attenuation when active and
+`rangeDb` otherwise; duck does the reverse. Ratio and knee are ignored by these
+two operations. There is no separate hold timer. At nonzero levels the meter
+uses unworklet 0.4.1's approximate logarithm, so its threshold transition has
+small numerical uncertainty, approximately 0.0001 dB within tested ranges.
+
+Both operations use the same detector linkage: maximum absolute L/R **before**
+power/peak ballistics. This deliberately preserves a unilateral transient; it
+is not a summed or mean-power stereo RMS measurement. Both program channels
+receive precisely the same gain. Opposite polarity keys cannot cancel one
+another. Sidechain filtering can be composed outside this module.
+
+## Reset, finite inputs and state
+
+Reset clears detector and attenuation histories and clears the gate/duck active
+flag **before consuming the current sample**. Current input can immediately
+reopen the key. The attenuation history starts at zero (unity); a cold/reset gate
+with a silent key therefore closes according to release, not instantly unless
+release is zero. A reset can change gain abruptly and is not bypass.
+
+Every nonfinite audio or sidechain sample (NaN/±Infinity) is explicitly replaced
+by zero. All finite f32 magnitudes, including values above full scale and
+subnormals, remain valid. Nonfinite time controls use zero; finite out-of-range
+controls clamp. Tests require `scrubbedSamples == 0`, so upstream output scrubbing
+is not accepted as evidence of finite processing.
+
+The detector's two fixed f64 slots are a scaled history and an exponent scratch
+slot. The full composition has seven fixed scalar slots, no buffers and no
+runtime allocation. unworklet 0.4.1 flushes scalar stores smaller than `1e-30`;
+RMS power would otherwise lose recoverable audio below roughly `1e-15`. Histories
+are therefore stored with the exact power-of-two scale `2**256`. Squared minimum
+f32 input remains representable above that flush boundary even with a 30-second
+attack; maximum scaled f32 power stays below `2**512`. Any eventual flushed tail
+is already too small to return as f32 audio. Scale/unscale is exact in binary64.
+
+Coefficient evaluation uses a degree-13 polynomial for `1-exp(-x)` on `(0,1]`,
+with remainder at most `1/14!`. This avoids cancellation and long-time stalling
+from `1-f32(exp(-x))`. History uses a convex weighted sum to preserve a tiny
+instantaneous target after a large prior level. dB-to-linear gain uses the pinned
+unworklet exp approximation; measured gain error is covered by independent tests.
+The -600 dB meter floor affects only the gain-law level, not the returned envelope
+or the program audio. Supported thresholds are at least -120 dB.
+
+Same-schema, same-rate snapshots preserve detector, attenuation and hysteresis
+continuation. Cross-mode/rate/schema migration is not promised. There is no
+serialized preset format in this module.
+
+## Verification and remaining gates
+
+`tests/dynamics.spec.ts` independently checks analytical peak/RMS responses,
+step/burst/reset and a-rate time edits, hard/soft knee transfer curves, ratio-one
+and range limits, stereo swapping/tracking, external keys, hysteresis, snapshot
+continuation, malformed controls, full finite f32 range, subnormals, large→tiny
+transitions and finite diagnostics. All three routine rates (44100/48000/96000)
+are covered; RMS steady sine energy and very slow tiny attacks are checked too.
+State count and a <64 KiB compiled-artifact guard bound construction growth.
+
+`tests/dynamics-packed.test.mjs` packs the actual package, installs a fresh
+locked consumer, type-checks declarations strictly, and renders all four modes
+at those three rates against independently computed detector and input/output
+transfer formulas. It writes 12 stereo WAV candidates and a hash manifest under
+`artifacts/dynamics/<trial>/`; repeated runs keep earlier trials rather than
+overwriting timing outliers. Generated audio is never an approved golden. Snapshot
+continuation, stereo ratios and zero scrub diagnostics are mandatory assertions.
+
+The packed fixture also records 2048 warmed 128-frame Node-driver wall-clock
+measurements per operation, artifact bytes and fixed memory size at 48 kHz.
+These are local diagnostics, exclude I/O copies and browser scheduling, and are
+**not** an AudioWorklet deadline gate. Worst observations are retained.
+
+Not yet established by this lane: browser rendering or controls, hardware-output
+continuity, cross-browser deadline behavior, listening judgement of pumping,
+transients, release, low-frequency distortion or stereo image, and aggregate public API
+integration. This candidate adds no
+true-peak, multiband or overall sound-quality claim. Full repository verification,
+independent final review and exact-head CI belong to integration before merge.
+
+## Initial local verification record
+
+Node 24.19.0 with locked unworklet 0.4.1: clean `npm ci --offline`, strict
+`npm run check`, and all 45 focused tests passed using Vitest's supported threads
+pool. The isolated packed consumer also passed all 12 renders. Its worst observed
+audio/reference residual was 1.280e-6, gain residual 9.538e-6 dB and envelope
+residual 2.979e-8, with zero scrubbed samples. This does not claim the full
+repository aggregate suite ran in this lane; integration owns that check.
+
+The initial local Node diagnostic measured 8,683–12,335-byte WASM and a fixed
+65,536-byte memory for the packed consumer (including its audio and parameter
+ports). Median 128-frame process time was approximately 35–57 microseconds. One
+expander wall-clock observation exceeded the nominal 2.667 ms quantum budget
+(maximum 3.250 ms); other operations in that trial had zero such observations.
+This is retained evidence under a shared host, not a pass/fail deadline verdict
+or a reason to infer a DSP defect without isolating scheduling effects.

package/docs/envelope-integer-staging.md

@@ -0,0 +1,64 @@
+# Envelope integer expression staging
+
+`envelope.tick` captures the previous `stage` and `remaining`, then temporarily
+stores `active` and `count` in those existing integer slots. Reading each staged
+value materializes its expression through unworklet's supported lexical read
+capture. Old-history decisions use the captured old values. The original final
+writes still run unconditionally, including reset. No declaration, snapshot
+schema, floating-point intermediate store, or upstream dependency changes.
+
+The subgraph exposes only `tick`. Its returned Nodes and caller-supplied control
+Nodes capture memory reads before subsequent stores. Worklet snapshot requests
+execute outside synchronous DSP execution. Direct concurrent inspection of raw
+working memory in the middle of processing is not a compatibility guarantee.
+
+## Regression evidence
+
+- `envelope.spec.ts` and the closed-form ADSR and maximum-i32-count tests in
+  `envelope-integer-staging.spec.ts` use independent numerical expectations.
+- The other staging tests compare against a frozen copy of the pre-change
+  implementation from `c65e2a8586eb0325cbccc3963af3764c7f15c926`. This is a
+  differential baseline, not an independent numerical oracle. Do not update
+  that fixture to match production.
+- Tests cover 44.1/48/96 kHz, reset/retrigger/automation, tiny and extreme finite
+  controls, complete state bytes, schema hash, bidirectional restore at five
+  boundaries, continuous-vs-restored output, a cold-start negative control,
+  independent instances, and delayed returned Nodes after caller state writes
+  and a second tick. Multiple ticks are an adversarial capture-order probe,
+  not a change to the once-per-sample usage contract.
+
+Reproduce numerical regressions with:
+
+```sh
+npm ci
+npm run check
+npx vitest run tests/envelope.spec.ts tests/envelope-integer-staging.spec.ts
+```
+
+## Limited performance evidence
+
+One fixed A/B/B/A diagnostic used main `c65e2a8` dependencies with the unchanged
+instrument fixture from `baa4bd50` (instrument is not present on that main).
+Chrome 151.0.7922.173, 48 kHz / 128 frames, four held A4 notes, identical controls,
+five seconds warmup then six seconds measurement, no capture/recording/analyser.
+All trials, including outliers and failures, were retained.
+
+| Trial | Callback CPU median, us | Kernel CPU/callback, us | CPU overruns / callbacks | Output underruns |
+| --- | ---: | ---: | ---: | ---: |
+| Baseline A1 | 426 | 508.85 | 3/2249 | 0 |
+| Candidate B1 | 322 | 446.85 | 11/2242 | 0 |
+| Candidate B2 | 322 | 421.15 | 11/2187 | 6 |
+| Baseline A2 | 434 | 577.72 | 10/2214 | 1 |
+
+Median callback CPU decreased 24–26% in this workload. One-second medians were
+415–438 us for baseline and 316–332 us for the candidate. Instrument WASM shrank
+from 1043330 to 936570 bytes. These are workload-specific sustained-cost results,
+not a universal performance guarantee or a runtime-gate pass.
+
+Tail latency and output underruns remain unresolved: candidate maximum callback
+CPU was 39105/7492 us. A separate existing realtime audition gate also failed
+with two output underruns and was not retried. The prior done-only reuse proposal
+had no sustained timing improvement and is not included. Initial verification
+failures from missing browser installation and temporary disk exhaustion were
+retained; after correcting those environment issues, the seven packed checks
+passed. None of these results constitutes listening approval.

package/docs/filter-materialization-results.json

@@ -0,0 +1,71 @@
+{
+  "baseCommit": "e12adc5019307183a68e7f8ff08aaa5a33562033",
+  "delayFixtureCommit": "7ef7ce670531b1230111f1d2c89302bfe44935b2",
+  "runtime": "unworklet 0.4.1; Node v24.19.0; Chromium 151.0.7922.173; Linux x64",
+  "sampleRate": 48000,
+  "framesPerQuantum": 128,
+  "secondsPerTrial": 12,
+  "compatibility": {
+    "filterRates": [
+      8000,
+      44100,
+      48000,
+      96000,
+      192000
+    ],
+    "inputLevels": [
+      1,
+      1e-20,
+      1e-28,
+      1e-29,
+      1e-30,
+      1e-31,
+      1e-38,
+      1e-44
+    ],
+    "delayCases": 18,
+    "delayPCMAndSnapshotBytes": "identical",
+    "schema": "unchanged"
+  },
+  "limitations": [
+    "Host-specific measurements with trace overhead, no CPU profiling.",
+    "All eight completed trials retained; no warmup exclusion from cold reporting.",
+    "No hardware-output deadline or sound approval."
+  ],
+  "filterSourceSHA256": "61d49d6b1e52b17791237e00dec5c5089e594ee0030ecaa37f2c632ecb441278",
+  "settings": {
+    "timeLeft": 0.075,
+    "timeRight": 0.1,
+    "feedback": 0.95,
+    "mix": 1,
+    "cutoff": 1000,
+    "sync": 0,
+    "bpm": 120,
+    "beatsLeft": 1,
+    "beatsRight": 1.5,
+    "rate": 2,
+    "depth": 0.001,
+    "bypass": 0,
+    "reset": 0
+  },
+  "wasm": {
+    "baseline": {
+      "bytes": 45935,
+      "sha256": "25202e821cecfc39de34a7c6e153d89091ff5b29db893856d22861370c21b6f1"
+    },
+    "candidate": {
+      "bytes": 24707,
+      "sha256": "74ab305c15c932d3d7bc32e7d4a0499439adfdfb107355f329e46d1ffea9fdb0"
+    }
+  },
+  "browserTrials": [
+    {"label":"baseline","trial":0,"audioSeconds":12.016,"quanta":4506,"firstWallMs":3.071,"firstCpuMs":2.849,"hotWall":{"meanMs":0.09881576026637134,"p99Ms":0.217,"maxMs":2.166},"hotCpu":{"meanMs":0.09697758046614784,"p99Ms":0.215,"maxMs":2.164},"overBudget":[{"quantum":0,"wallMs":3.071,"cpuMs":2.849,"clockAnomaly":false}],"lazyCompile":[{"name":"wasm.CompileLazy","dur":1115,"tdur":1114,"withinFirst":true}],"trace":"baseline-0-trace.json","traceSha256":"ff79728834d1426b8570072aecdc8f1f9a9cef35e55968e3764bcc5b05e7dde7"},
+    {"label":"candidate","trial":0,"audioSeconds":12.016,"quanta":4506,"firstWallMs":1.9,"firstCpuMs":1.897,"hotWall":{"meanMs":0.09993407325194262,"p99Ms":0.194,"maxMs":1.863},"hotCpu":{"meanMs":0.09836825749167738,"p99Ms":0.189,"maxMs":2.435},"overBudget":[],"lazyCompile":[{"name":"wasm.CompileLazy","dur":609,"tdur":608,"withinFirst":true}],"trace":"candidate-0-trace.json","traceSha256":"536c163ec4ed26943707605efe036a3c2b6f2e40172d9ca6f452714fa6e2cd8e"},
+    {"label":"candidate","trial":1,"audioSeconds":12.016,"quanta":4506,"firstWallMs":1.857,"firstCpuMs":1.855,"hotWall":{"meanMs":0.09728479467258735,"p99Ms":0.176,"maxMs":0.719},"hotCpu":{"meanMs":0.09542264150943501,"p99Ms":0.174,"maxMs":0.53},"overBudget":[],"lazyCompile":[{"name":"wasm.CompileLazy","dur":599,"tdur":598,"withinFirst":true}],"trace":"candidate-1-trace.json","traceSha256":"898b0abe99a1cdf4dc17199ba3f3d0da2387cb7ca1ff622b156efd838a18af9c"},
+    {"label":"baseline","trial":1,"audioSeconds":12.016,"quanta":4506,"firstWallMs":2.815,"firstCpuMs":2.743,"hotWall":{"meanMs":0.09903240843507195,"p99Ms":0.227,"maxMs":2.553},"hotCpu":{"meanMs":0.09767635960044414,"p99Ms":0.223,"maxMs":2.552},"overBudget":[{"quantum":0,"wallMs":2.815,"cpuMs":2.743,"clockAnomaly":false}],"lazyCompile":[{"name":"wasm.CompileLazy","dur":1120,"tdur":1119,"withinFirst":true}],"trace":"baseline-1-trace.json","traceSha256":"df0af807969fad55a30f796c8204cdbeb566eb41fa7c41af23fa9d1a86e5d939"},
+    {"label":"baseline","trial":2,"audioSeconds":12.016,"quanta":4506,"firstWallMs":2.959,"firstCpuMs":2.948,"hotWall":{"meanMs":0.09628768035516228,"p99Ms":0.172,"maxMs":1.476},"hotCpu":{"meanMs":0.09439134295227555,"p99Ms":0.171,"maxMs":1.41},"overBudget":[{"quantum":0,"wallMs":2.959,"cpuMs":2.948,"clockAnomaly":false}],"lazyCompile":[{"name":"wasm.CompileLazy","dur":1221,"tdur":1212,"withinFirst":true}],"trace":"baseline-2-trace.json","traceSha256":"37ac48f5dfc304181c61935f8a23734b1331358ad69264223dcf3c0c1efea6b5"},
+    {"label":"candidate","trial":2,"audioSeconds":12.016,"quanta":4506,"firstWallMs":1.68,"firstCpuMs":1.678,"hotWall":{"meanMs":0.09407169811320897,"p99Ms":0.183,"maxMs":1.043},"hotCpu":{"meanMs":0.09290166481687012,"p99Ms":0.183,"maxMs":2.289},"overBudget":[],"lazyCompile":[{"name":"wasm.CompileLazy","dur":604,"tdur":603,"withinFirst":true}],"trace":"candidate-2-trace.json","traceSha256":"7de84358f73ff46cd6d3cac5f524d1e4e7e0270749c31711cc29dcb77b5a2e3f"},
+    {"label":"candidate","trial":3,"audioSeconds":12.016,"quanta":4506,"firstWallMs":1.659,"firstCpuMs":1.656,"hotWall":{"meanMs":0.09528990011098971,"p99Ms":0.19,"maxMs":1.942},"hotCpu":{"meanMs":0.09338046614872407,"p99Ms":0.189,"maxMs":1.941},"overBudget":[],"lazyCompile":[{"name":"wasm.CompileLazy","dur":553,"tdur":551,"withinFirst":true}],"trace":"candidate-3-trace.json","traceSha256":"a530dfa4dc293a431f7f4011bbb2ae7341d63776d7949ac28d4b8f765c6fd786"},
+    {"label":"baseline","trial":3,"audioSeconds":12.016,"quanta":4506,"firstWallMs":6.584,"firstCpuMs":2.92,"hotWall":{"meanMs":0.09562841287458462,"p99Ms":0.184,"maxMs":1.514},"hotCpu":{"meanMs":0.09368967813540517,"p99Ms":0.178,"maxMs":1.512},"overBudget":[{"quantum":0,"wallMs":6.584,"cpuMs":2.92,"clockAnomaly":false}],"lazyCompile":[{"name":"wasm.CompileLazy","dur":1180,"tdur":1180,"withinFirst":true}],"trace":"baseline-3-trace.json","traceSha256":"b32ca895b5844f0e73e2c4b112f07800a08931c2a3ce04389db631d0187deb59"}
+  ]
+}

package/docs/filter-materialization.md

@@ -0,0 +1,135 @@
+# Filter coefficient materialization
+
+The low-pass expression repeats its Taylor-polynomial coefficient when unworklet
+0.4.1 lowers the expression tree. Materializing only `g` reduces emitted WASM and
+first-callback lazy compilation without changing coefficient arithmetic.
+
+`band.read()` and `low.read()` first capture the old integrator values into WASM
+locals. The existing `band` slot then stages `g`; a subsequent read captures that
+coefficient, and the original final integrator writes replace the staged value
+before `tick` returns. There are no added declarations, persistent/transient
+slots, sample delays, changed coefficients, or reordered final integrator updates.
+Snapshot schema, slot names/types, and saved bytes remain identical. The method
+still runs exactly once per sample per instance, on the existing audio thread.
+
+Only the bounded positive coefficient is staged. Across the supported sample-rate
+and cutoff range, `g` exceeds 3e-4, far above the pinned runtime's 1e-30 state-write
+flush threshold. Audio intermediates `v1`/`v2` must not be materialized via new
+scalar states: doing so introduces an extra flush before a caller can amplify the
+returned sample. For example, at 48 kHz, cutoff 1000 Hz, Q 0.707, input 1e-30,
+and a finite post-filter gain of 1e30, the original output is nonzero whereas that
+alternative becomes zero. Adding transient declarations also changes the schema
+hash, even when saved slots appear unchanged.
+
+## Verification
+
+`tests/filter-materialization.spec.ts` compares against the frozen pre-change
+implementation from main `e12adc5`; this is a compatibility reference, not a new
+correctness oracle. The existing independent biquad/response tests remain intact.
+The compatibility tests cover:
+
+- 8/44.1/48/96/192 kHz, cutoff/Q clamps and per-sample modulation;
+- eight input levels from 1 to 1e-44, plus finite post-filter gains;
+- resets around quantum boundaries, isolated instances and same-sample cascades;
+- identical schema, saved bytes, and bidirectional snapshot continuation;
+- the amplified tiny-constant counterexample and a 262144-sample resonant tail,
+  preserving the existing flush behavior including any tiny residual.
+
+The separate Delay FX fixture at `7ef7ce6` was packed with each filter version.
+All four output/status channels and complete snapshot bytes matched across 18
+cases: 44.1/48/96 kHz × low/high/dynamic tone × modulation off/on, 8192 samples
+per case, including varying times/mix, bypass, reset and rejected sync requests.
+Its independent 31 numerical tests and corrected 48-kHz packed browser gate also
+passed. Offline rate coverage remains distinct from 48-kHz browser coverage.
+
+## Timing reproduction
+
+The fixture is in **this repository**, on the separate Delay FX PR #23 history;
+it is not a file on this filter PR's main-based checkout. Fetch its exact commit
+before looking for it:
+
+- Repository: <https://github.com/yuichkun/den>
+- Fixture commit: `7ef7ce670531b1230111f1d2c89302bfe44935b2`
+- [Packed test at that commit](https://github.com/yuichkun/den/blob/7ef7ce670531b1230111f1d2c89302bfe44935b2/tests/delay-fx-packed.test.mjs)
+- [Consumer directory at that commit](https://github.com/yuichkun/den/tree/7ef7ce670531b1230111f1d2c89302bfe44935b2/tests/delay-fx-consumer)
+- Filter/probe revision: `ca3f18ee516cdf477260e7ab88ea0780c6bd049f`
+
+Run this Bash recipe with Node 24, npm and Chromium's system dependencies
+available. Optionally export `CHROMIUM_PATH` to an installed Chromium executable;
+otherwise the recipe installs Playwright's pinned Chromium. The clone and all
+worktrees are disposable. The candidate starts at the same fixture commit as the
+baseline and receives **only** `src/filter.ts` from the specified filter revision.
+Separate `TMPDIR` directories make both generated consumer paths unambiguous.
+
+```bash
+set -euo pipefail
+repro_root=$(mktemp -d)
+export npm_config_cache="$repro_root/npm-cache"
+export PLAYWRIGHT_BROWSERS_PATH="$repro_root/playwright"
+fixture_rev=7ef7ce670531b1230111f1d2c89302bfe44935b2
+filter_rev=ca3f18ee516cdf477260e7ab88ea0780c6bd049f
+git clone https://github.com/yuichkun/den.git "$repro_root/repo"
+git -C "$repro_root/repo" fetch origin "$fixture_rev" "$filter_rev"
+git -C "$repro_root/repo" worktree add --detach "$repro_root/baseline" "$fixture_rev"
+git -C "$repro_root/repo" worktree add --detach "$repro_root/candidate" "$fixture_rev"
+git -C "$repro_root/repo" worktree add --detach "$repro_root/tools" "$filter_rev"
+git -C "$repro_root/repo" show "$filter_rev:src/filter.ts" > "$repro_root/candidate/src/filter.ts"
+(
+  cd "$repro_root/tools"
+  npm ci
+  if [ -z "${CHROMIUM_PATH:-}" ]; then
+    npm exec -- playwright install chromium
+  fi
+)
+mkdir -p "$repro_root/tmp/baseline" "$repro_root/tmp/candidate"
+for variant in baseline candidate; do
+  (
+    cd "$repro_root/$variant"
+    npm ci
+    TMPDIR="$repro_root/tmp/$variant" node --test tests/delay-fx-packed.test.mjs
+  ) > "$repro_root/$variant-packed.log" 2>&1
+done
+baseline_consumers=("$repro_root/tmp/baseline"/den-delay-fx-*)
+candidate_consumers=("$repro_root/tmp/candidate"/den-delay-fx-*)
+test "${#baseline_consumers[@]}" -eq 1
+test "${#candidate_consumers[@]}" -eq 1
+test -f "${baseline_consumers[0]}/package-lock.json"
+test -f "${candidate_consumers[0]}/package-lock.json"
+node "$repro_root/tools/tests/probes/filter-browser-timing.mjs"   "${baseline_consumers[0]}" "${candidate_consumers[0]}" "$repro_root/evidence"   > "$repro_root/timing.log" 2>&1
+printf 'Retained reproduction directory: %s\n' "$repro_root"
+```
+
+A failed packed gate stops the recipe; inspect the corresponding `*-packed.log`
+and retained `artifacts/delay-fx` directory rather than selecting a passing retry.
+`evidence/browser-timing.json` includes every timing trial, WASM hash/size and raw
+trace hash. Expect the same packed WASM sizes/hashes recorded below; timing values
+are machine-dependent and must not be required to match the original numbers.
+
+The probe appends a recorder-free entry to the disposable consumer pages, rebuilds
+with the existing plugin, and alternates four fresh-browser trials per variant.
+Each trial runs for 12 seconds at 48 kHz. It retains every trace and reports the
+first callback separately from all later callbacks; no initial samples or slow
+trials are removed. CPU profiling is disabled. Chromium tracing can still affect
+timing, and thread-CPU durations occasionally exceeding wall time are explicitly
+flagged as clock/accounting anomalies. No hardware-output deadline guarantee or
+listening approval follows from these diagnostics.
+
+## Observed results
+
+On Node 24.19.0 / Chromium 151.0.7922.173, with all eight trials retained:
+
+| Measurement | Original | Coefficient-only staging |
+| --- | --- | --- |
+| Packed Delay WASM bytes | 45,935 | 24,707 |
+| First callback wall time, four runs | 2.815–6.584 ms | 1.659–1.900 ms |
+| First callback thread CPU, four runs | 2.743–2.948 ms | 1.656–1.897 ms |
+| Later callback wall mean, range across runs | 0.0956–0.0990 ms | 0.0941–0.0999 ms |
+| Later callback wall p99, range across runs | 0.172–0.227 ms | 0.176–0.194 ms |
+
+The original first callback contains synchronous `wasm.CompileLazy`; the smaller
+artifact reduces the observed startup cost. These results do not establish a
+hot-path speedup or a universal deadline guarantee. The separate direct-driver
+benchmark measured means of 0.0784 ms (original) and 0.0849 ms (candidate), excluding
+browser scheduling and copy overhead; it likewise does not support a hot-speedup
+claim. Full per-trial timings, settings, WASM hashes, outliers and trace hashes are
+in [filter-materialization-results.json](filter-materialization-results.json).

package/docs/filter-oscillator.md

@@ -0,0 +1,126 @@
+# Filter and oscillator numerical contract
+
+GEN-612 and GEN-613. Implemented as unworklet 0.4.1 `defineSubgraph`
+declarations, with required immutable configuration and independent named state.
+Call each instance's `tick` once per sample, inside `forSample`. All signal
+arguments are finite `Node<'f32'>`; reset is `Node<'bool'>`. Configuration rate
+must equal the compiled/rendered rate. The numerical construction domain is
+8000–192000 Hz; acceptance renders are separately 44100, 48000 and 96000 Hz.
+No parameter, MIDI, routing, state codec, noise generator or loader is added.
+For percussion noise, compose the existing unworklet `noiseSource` in the engine.
+
+## Low-pass
+
+`instantiate(filter, { sampleRate }, { name })` returns
+`tick(input, cutoffHz, resonanceQ, reset) -> Node<'f32'>`.
+
+The two-integrator trapezoidal state-variable method preserves meaningful
+integrator state during coefficient edits. Cutoff clamps to
+`[20, min(20000, 0.45 * sampleRate)]`; Q clamps to `[0.5, 10]`.
+Reset clears both histories **before** consuming the input at that sample.
+There is no smoothing, gain compensation, saturation or limiter. The caller
+owns modulation depth and gain staging. Slots `band` and `low` are f64 to avoid
+low-cutoff cancellation/accumulation; audio output remains f32.
+
+Let `g=tan(pi*cutoff/rate)` and `k=1/Q`. Solving the trapezoidal integrator pair
+simultaneously gives `band=(s1+g*(input-s2))/(1+g*(g+k))`,
+`low=s2+g*band`, followed by `s1=2*band-s1`, `s2=2*low-s2`.
+This is derived from the integrator equations in Andrew Simper's
+[trapezoidal SVF analysis](https://cytomic.com/files/dsp/SvfLinearTrapOptimised2.pdf)
+(2013, updated 2016). No reference source code or PDF is vendored; repository
+MIT/Apache notices are preserved. Compared with direct-form coefficient edits,
+the SVF retains integrator coordinates; compared with forward-Euler SVF it avoids
+an explicit-step high-cutoff stability restriction.
+
+The independent oracle is a direct-form biquad from the bilinear transform of
+`H(s)=1/(s²+s/Q+1)`, not a copy of the SVF recurrence. Its magnitude is
+`1/sqrt((1-u²)²+(u/Q)²)`, `u=tan(pi*f/rate)/tan(pi*cutoff/rate)`.
+DC gain is one; gain at cutoff is Q. The static response peak is one for
+Q <= 1/sqrt(2), otherwise `Q/sqrt(1-1/(4Q²))` (10.013 at Q=10).
+Consequently a feedback multiplier of 0.95 with Q=10 is **not** a guaranteed
+stable delay loop. Use Q <= 1/sqrt(2) for a nonpeaking fixed feedback tone, or
+prove the complete engine's loop gain separately. Time-varying coefficients
+require complete-loop testing even at low Q; the module tests are not that proof.
+
+Numerical acceptance: absolute impulse/direct-form error <2e-6 over cutoff
+20/1000/maximum and Q 0.5/1/sqrt(2)/10; steady sine response uses independent
+sample expectations and gain error <0.02 at 250/1000/8000 Hz. Alternating
+minimum/maximum cutoff every sample with Q edits remains finite, peak <25 for
+unit 173-Hz input, and reset removes all residual output. This peak is a fixture
+bound, not a universal amplitude guarantee. DC, slowest-pole decay, reset with
+nonzero input, clamp equivalence, silent second instance, and exact snapshot
+continuation have separate assertions.
+
+unworklet 0.4.1 lowers transcendental functions through f32 approximations even
+for f64 input. The initial tan call failed the 2e-6 reference budget. Instead,
+coefficient construction evaluates degree-13 sine / degree-14 cosine Taylor
+polynomials in f64 on `[0, 0.45*pi]`. The first omitted terms bound sine error by
+`(0.45*pi)^15/15!` and cosine error by `(0.45*pi)^16/16!`.
+No upstream code is changed and the reference tolerance remains unchanged.
+
+## Oscillator
+
+`instantiate(oscillator, { sampleRate, waveform: 'sine' | 'saw' }, { name })`
+returns `tick(frequencyHz, reset) -> Node<'f32'>`.
+
+One f64 `phase` slot stores cycles in `[0,1)`. Emit current phase, then advance
+by clamped frequency/rate. Frequency clamps to `[0, 0.45*sampleRate]`; zero and
+negative frequencies hold phase. Reset uses phase zero for that sample, then
+advances normally. A continuously true reset pins the emitted phase. A4=440 Hz
+is supplied by the caller; equal-tempered MIDI mapping is `440*2^((note-69)/12)`.
+There is no second MIDI receiver or tuning state.
+
+Sine uses quadrant folding and a degree-13 Taylor polynomial on
+`[-pi/2,pi/2]`, whose first omitted term is <7e-10. This avoids the dependency's
+sine overshoot while retaining the original sample-error budget (<2e-6) and
+nominal unit amplitude. Saw uses a four-sample polynomial step correction:
+convolve four unit-width boxes to obtain the cubic B-spline kernel, integrate
+it, and correct both sides of the periodic discontinuity. For distance x>=0
+in sample intervals, the step complement is
+`C(x)=1/2-2x/3+x³/3-x⁴/8` for x<1,
+`C(x)=(2-x)^4/24` for 1<=x<2, otherwise zero.
+The saw is `2p-1+2*(C(p/dt)-C((1-p)/dt))`. Both corrections are added when
+supports overlap near Nyquist. No mutable BLEP buffer is required.
+
+This is an independently derived polynomial smoothing kernel, not an ideal
+brick-wall bandlimit. [Finke's published PolyBLEP example](https://www.martin-finke.de/articles/audio-plugins-018-polyblep-oscillator/)
+illustrates the shorter two-sample alternative and the additive tradeoff.
+No code from that example is included. The two-sample candidate measured
+-43.43 dBFS folded RMS at bin 37/8192 and missed the -50 dBFS bass/pad criterion.
+The four-sample method is selected by the same orthogonal-projection test:
+
+| Fundamental / rate | Folded RMS dBFS | Improvement over naive saw |
+| --- | ---: | ---: |
+| 37/8192 | -53.38 | 26.01 dB |
+| 997/8192 | -45.37 | 31.89 dB |
+| 3501/8192 | -71.41 or lower | 62.57 dB or better |
+
+All three sample rates pass. Projection removes only below-Nyquist integer
+harmonics, so the remaining RMS measures aliased energy (plus numerical/DC
+error). The naive counterexample must be >=12 dB worse. Fundamental amplitude
+is independently checked against `(2/pi)*sinc(pi*f/rate)^4` within 0.002.
+The kernel intentionally attenuates high harmonics and high-pitch fundamental;
+there is no hidden normalization. Saw output stays within [-1,1]. At zero Hz
+it emits the held naive ramp value (phase zero gives -1); starting/stopping can
+therefore change the corrected value even though phase is preserved.
+
+Bass and pad can use the saw; sine supplies percussion body/pitch sweeps.
+Hard reset, abrupt pitch changes and arbitrary audio-rate FM are discontinuous
+and do not inherit the stationary alias bounds. They require engine envelope
+and listening assessment. No hard-sync/PM anti-alias guarantee is made.
+
+## Packaging and integration
+
+`npm test` covers numerical tests and a packed isolated locked consumer, including
+strict declaration checking and actual oscillator -> filter rendering against
+analytic sine plus the independent biquad. It emits raw f32 candidate audio,
+static SVG plots, alias measurements and a manifest with source commit/hashes,
+package integrity, dependency lock hash, rates and all fixture settings.
+Snapshot tests are same-schema/rate only. Nothing is an approved golden.
+The separate existing browser gate stays at 48000 Hz.
+
+The packed test imports `@denaudio/den/filter` and `@denaudio/den/oscillator`
+through their public package subpaths. It checks strict declarations and renders
+both modules together from an isolated, locked installation. No installed-file
+path escape is required. These are the same shared implementations used by the
+instrument and Delay FX.

package/docs/filterbank-vocoder-entry.md

@@ -0,0 +1,58 @@
+# Fixed filter-bank vocoder candidate
+
+Catalog group 11 explicitly includes a filter-bank vocoder. This entry is a bounded native implementation on unworklet 0.4.1, using the reviewed den TPT state-variable filter and peak envelope follower. It is independent of the STFT/phase-vocoder processors. It does not claim speech intelligibility, commercial equivalence, or human-approved sound quality.
+
+## Contract
+
+`filterBankVocoder({ sampleRate, bands })` constructs a mono processor. `sampleRate` is an integer from 8,000 through 192,000 Hz and must equal the actual processing rate. `bands` is a dense array of 1–8 `{ frequencyHz, q, gain }` records. Centers must be strictly increasing, from 20 Hz through `min(20000, .45 * sampleRate)`; Q is .5–10 and gain is a nonnegative linear factor from 0–4. Invalid values, empty/oversized/sparse arrays, duplicate centers and descending centers reject at graph construction. Values are copied into the graph; mutating the configuration later does not retune it. Structural changes require a new graph.
+
+For every band, one second-order unity-peak bandpass analyzes the modulator, and an identical second-order bandpass filters the externally supplied carrier. The center/Q controls use the existing SVF's f32 rounding, bounds, and bounded coefficient approximation. There is no automatic logarithmic placement, channel adaptation, unvoiced/noise source, high-frequency bypass, or crossover-perfect reconstruction claim.
+
+`tick(modulator, carrier, { attack, release, reset })` is called exactly once per sample. It returns `{ output, envelopes }`, with envelopes in configuration order. All sample operations and persistent histories are native unworklet graph operations. JavaScript loops construct the graph; they do not process audio on the host.
+
+For band `i`, the output is exactly the implemented f32 endpoint of:
+
+    analysis_i = BP_i(modulator)
+    carrier_i = BP_i(carrier)
+    target_i = abs(analysis_i)
+    envelope_i = previous_i * (1 - coefficient) + target_i * coefficient
+    output = sum_i(gain_i * carrier_i * envelope_i)
+
+The recurrence uses f64 history, the exposed envelope and bandpass endpoints are f32, and the output sum uses f64 before its f32 endpoint. No hidden band-count division, automatic gain control, peak/RMS calibration, makeup gain, clipping, or limiter is present. Gains of zero still process the band's history. Parallel bands overlap and have phase, so their sum is not a flat unity transfer. A constant carrier gain does not imply a constant output gain.
+
+## Envelope and gain interpretation
+
+The peak follower here smooths rectified amplitude, not windowed peaks or RMS. Attack is selected when the current target exceeds previous envelope; otherwise release is selected. Each time is in seconds, clamped to 0–30; nonfinite times become zero. Zero time is immediate. A positive time uses `tauSamples = max(1, seconds * sampleRate)` and `coefficient = 1 - exp(-1 / tauSamples)`, with the reviewed bounded polynomial implementation. One time constant traverses approximately 63.2% of a constant target difference. Filter ringing also affects a band envelope after a burst.
+
+For a center-frequency sine of amplitude A, the unity-peak filter preserves the settled sine amplitude. Under equal, slow attack/release, the envelope approaches the sampled rectified mean with ripple. `2A/pi` is the ideal continuous-time rectified-sine mean, not an exact finite sampled mean or a calibration applied by this module. Unequal attack/release can produce a different average. With both times zero, the envelope is the instantaneous absolute band sample. The user-specified gains control synthesis level explicitly.
+
+Finite input is not clipped, including values above full scale. Nonfinite modulator/carrier samples become zero before entering their filters; earlier finite filter/envelope histories continue. The caller must provide practical headroom: finite extreme inputs/products/sums can exceed f32 output range. There is no arbitrary-overload guarantee. Ordinary IEEE product underflow can occur at tiny levels even though reused filter/follower history scaling preserves their respective histories.
+
+## Reset and persistence
+
+Reset clears both bandpass integrators and the envelope history before the current sample. The current sample is still processed; reset is not an output mute. Holding reset high recomputes the first-sample response for each input. It does not switch off processing.
+
+All histories live in unworklet state under stable per-band analysis/synthesis/envelope names. Same-schema snapshot/restore continues filter ringing and envelopes. Tests must compare noninitial continuation, output and final state, including quantum boundaries. No custom snapshot codec or migration is introduced. Changing band count/order/centers/Q/gain or sample rate is a new configuration; cross-configuration restore compatibility is not promised.
+
+Core 0.4.1 restores persistent worklet state before the host restores saved
+AudioParams. In-place restoration across different live controls is not atomic.
+The browser composition renders every saved control before calling restore.
+It saves a nonzero slowly decaying envelope with zero modulator input, clears
+the live history, then proves that the stable saved controls leave that mutation
+silent. Restoration must recover both the envelope and actual carrier output.
+Measured native-clock brackets bound the expected 30-second exponential decay,
+with eight quanta allowed for delivery/publication and analyser alignment. This
+is an observation allowance, not increased DSP accuracy or restored timing;
+exact sample-aligned filter/history continuation remains an offline assertion.
+
+There is no block lookahead or explicit delay buffer. Filter phase and attack/release cause frequency-dependent temporal response, so this is not a zero-phase or transient-transparent effect.
+
+## Validation boundary
+
+The targeted gate checks 44.1/48/96 kHz against independent RBJ direct-form-I bandpasses and a direct exponential envelope recurrence, plus center transfer, out-of-band rejection, carrier modulation, no implicit normalization, malformed configuration, reset-current-sample behavior, held reset, snapshot continuation, and instance isolation. The packed consumer must typecheck the public subpath, render actual native WASM, and compile the worklet with unworklet 0.4.1. Candidate audio, cost data and source/package hashes are evidence, not approved goldens. Browser/realtime, concurrency and listening acceptance remain separate.
+
+The hosted 48 kHz browser gate uses native sine sources and a one-band worklet.
+It checks rectified-amplitude calibration, doubled modulation, a silent carrier,
+rendered control telemetry, the noninitial restore described above and reset.
+It does not establish speech intelligibility or maximum-bank deadline capacity.
+The explicit local browser-skip switch is rejected in hosted CI.