@denaudio/den 0.0.0-stage → 0.2.0

package/docs/instrument-performance.md

@@ -0,0 +1,191 @@
+# Instrument performance investigation
+
+Correctness follow-up: the former oscillator/filter and amplitude caches also
+flushed recoverable tiny values, independently of the depth-only optimization.
+Those three paths now compose returned Nodes directly. A failing-before/passing-
+after regression checks tiny oscillator → large custom-filter gain, large
+oscillator → tiny amplitude envelope, tiny custom-filter output, smallest f32
+subnormal and negative-zero sign recovery. Private DSL internals are not used.
+Compilation remains possible at 1/4 voices; WASM changes from 804852/1050090 to
+818400/1104282 bytes. Measurements below predate this correctness correction
+unless explicitly labeled otherwise, and are retained as historical evidence.
+The corrected composition passes 124 numerical/state tests and five packed
+consumers. Its local packed four-voice capture has hot wall/CPU medians 445/436
+µs, 26 wall and 32 CPU threshold exceedances, zero frame gaps and raw/release
+residuals 6.140e-9/8.892e-9. This is a correctness fix with observed performance
+cost, not an optimization or a portable real-time guarantee. Underrun/overrun
+counts require separating CPU from non-CPU intervals and observer/host effects;
+they do not alone identify a product defect.
+
+Status: incomplete. Numerical continuity is not a real-time readiness verdict.
+Baseline source is `9a75f9c07e89d0dd77d598bf3e35ee51af1eb26e`, unworklet
+0.4.1, Chromium 151.0.7922.173, 48000 Hz and 128-frame quanta. All audio is
+CANDIDATE. No hardware loopback or listening approval is claimed.
+
+Manual reproductions are in `tests/instrument-performance/`. Each invocation
+creates a separate directory under `artifacts/instrument-investigation/` with
+source copies/hashes, WASM, raw samples, per-block timings and a manifest.
+Preserve all trials, outliers and failed preflights; do not retry in place.
+
+## Cost controls
+
+The direct Node 24 trials retain wall time and **process-wide** CPU, which is
+not render-thread CPU. Chrome trace `dur` and `tdur` measure the enclosing
+Render event, including graph/observer work. They are not instrument-only cost.
+The nominal quantum budget is 2666.667 microseconds.
+
+| Configuration | Node median, microseconds | Chrome median, microseconds |
+| --- | ---: | ---: |
+| 1 voice capacity | 228 | 110–113 |
+| 4 voice capacity, four sounding | 1047–1049 | 351–357 |
+| 4 voice capacity, none sounding | 1064–1072 | 352–364 |
+| 16 voice capacity | 33053–33602 | 1507–1521 |
+
+These are construction capacities, not product limits. Inactive slots currently
+execute DSP. The dynamic voice-policy-only control costs approximately 6, 7 and
+13 microseconds at capacities 4, 8 and 16; it does not explain whole-engine cost.
+Node and Chrome differ substantially. Yielding between blocks did not resolve
+Node's 16-voice cost, so tier installation is not an established explanation.
+
+Materializing the instrument's combined modulation depths and final stereo mix
+reduces WASM from 1083626 to 1049832 bytes and Node median from roughly
+1015–1063 to 570–659 microseconds. Three captured scenarios are bit-identical,
+including modulation, sample-varying cutoff/Q and release. Chrome medians remain
+359–366 microseconds versus baseline 358–360; this is **not** a demonstrated
+browser deadline fix. The candidate remains detached from production source.
+
+## Frame metadata counterexample
+
+Run `2026-10-04T13-37-51.511Z-browser`, trial `trial0-four-active4-poll1`,
+reproduces currentFrame values 131840, 131840, 132096. Entry and exit values
+agree within each callback; currentTime repeats too. All input blocks contain
+128 samples. The complete raw stream matches the independent 440 Hz sinusoid
+with maximum residual 6.1391e-9.
+
+At anomalous quantum 820, normal continuation has maximum residual 5.4479e-9.
+An independently predicted repeated or skipped 128-frame block instead differs
+by 0.06946. This reproduction shows a frame-clock metadata anomaly without
+duplicated/skipped audio in the captured graph. It does not establish hardware
+output continuity, or retroactively explain the old CI failure whose raw data
+was not retained. CI used Chromium 148; this reproduction uses Chromium 151.
+
+The packed test now writes raw/metrics/manifest before asserting frame gaps.
+The CI integration owner should also upload failure artifacts (`always()`),
+because success-only upload loses the evidence needed to diagnose failures.
+
+## Underrun controls without trace or observation worklet
+
+Run `2026-10-04T13-48-23.859Z-browser` uses native Analyser capture of the final
+32768 samples only. This is not full-stream continuity evidence. Chrome tracing
+and the capture AudioWorklet are both absent. Native playbackStats counters are
+sampled at startup, after one audio second, and at the end; differences below
+exclude startup. All three trials per condition are retained.
+
+| Condition | Steady underrun events, trials 0 / 1 / 2 | Duration, seconds |
+| --- | --- | --- |
+| Native AudioBufferSource | 0 / 0 / 0 | 0 / 0 / 0 |
+| Four-voice instrument | 42 / 0 / 81 | 0.42084 / 0 / 0.81162 |
+
+These browser-internal counters are not hardware-loopback measurements. They
+nevertheless prevent dismissing all observed failures as tracing or capture-AW
+overhead. No-trace trials have no per-quantum duration measurement; an empty
+trace must not be interpreted as zero deadline overruns. Aggregate CDP process
+CPU is retained separately and includes initialization and other browser work.
+
+Further work must correlate full raw capture, frame metadata, playbackStats and
+trace/no-trace conditions, then validate any instrument change at the same head.
+Shared filter changes are outside this investigation's production ownership.
+
+Full raw, no-trace follow-up `2026-10-04T13-50-17.498Z-browser` retains one trial
+of each setting: native without timestamp polling, native with polling, four-slot
+instrument silent, and four-slot instrument sounding. Post-warmup underrun
+counts are respectively 12, 2, 101 and 61; durations are 0.12024, 0.02004,
+1.01202 and 0.61122 seconds. Native sample counters have zero breaks. Sounding
+instrument PCM residual is 6.145e-9. The silent instrument has two frame metadata
+anomalies; silence cannot establish whether audio frames were lost. These controls
+show both observation overhead and instrument-associated failures. Full raw graph
+continuity and browser output underrun counters describe different boundaries.
+
+## Instrument-only depth materialization
+
+`2026-10-04T13-56-04.747Z-owned` compares the original source, depth-only
+materialization, and the earlier depth-plus-final-mix candidate. The latter is
+rejected: a valid `gain=1e-35` output becomes zero at the new state write. The
+regression checks its independently expected nonzero value and downstream gain.
+The upstream f32/f64 state and buffer stores flush magnitudes below 1e-30;
+audio output stores do not. No upstream source was changed.
+
+Only combined pitch/cutoff exponents are cached in the selected change. Such
+exponents below 1e-30 already produce an exactly-one rounded octave ratio in
+the existing polynomial. The stored expression is already f32, so other finite
+values gain no extra rounding. Final mix remains an expression. Cache entries
+are overwritten before every read, including reset and restoration.
+
+All 42 combinations of 1/4 voices, 44100/48000/96000 Hz and seven scenarios
+(normal, dynamic, reset, cold-node restore, custom parts, tiny output, tiny
+depth) are bit-identical for the depth-only variant, with zero scrubbed samples.
+The six tiny-output comparisons reject the final-mix variant. Raw PCM and
+source copies are preserved for each variant, not just passing cases.
+
+| Capacity | Variant | WASM bytes | First process, ms | Hot median, µs |
+| --- | --- | ---: | ---: | ---: |
+| 1 | baseline | 813236 | 66.28 | 231.20 |
+| 1 | depth cache | 804852 | 60.43 | 151.61 |
+| 4 | baseline | 1083626 | 120.00 | 1203.85 |
+| 4 | depth cache | 1050090 | 124.10 | 676.40 |
+
+These are single Node timing trials (2500 quanta, hot after 500), with inactive
+voices, held capacity 128 and zero-filled native driver parameter buffers. Every block's wall/process
+CPU is retained. Compile times are 860/858 ms for 1 voice and 962/1012 ms for
+4 voices; instantiate times are 4.21/3.24 and 5.89/5.56 ms. The first process
+includes lazy compilation. No uniform cold-time improvement is established.
+
+Chrome no-trace comparison `2026-10-04T13-58-07.908Z-browser` uses two full-raw
+12-second trials per variant/capacity, all with held capacity 128. All raw
+sinusoid checks pass and frame metadata gaps are zero. The source snapshots
+contain the exact detached baseline/candidate; production changes during the
+run do not affect those compiled variants.
+
+| Capacity / variant | createNode, ms (two trials) | Underrun events | Underrun seconds |
+| --- | --- | --- | --- |
+| 1 baseline | 43.49 / 42.38 | 17 / 25 | 0.17034 / 0.25050 |
+| 1 depth cache | 35.48 / 37.69 | 20 / 40 | 0.20040 / 0.40080 |
+| 4 baseline | 53.42 / 63.84 | 53 / 102 | 0.53106 / 1.02204 |
+| 4 depth cache | 43.96 / 40.62 | 69 / 71 | 0.69138 / 0.71142 |
+
+Average reported latency is 31.29 ms in all eight trials. createNode includes
+module/node setup, not the first audio process. Its reduction is not proof of a
+deadline improvement. These trials do **not** demonstrate an underrun fix.
+Although counters are subtracted at the fixture's warm marker, playbackStats
+`totalDuration` is only 0.002666 seconds there. Unlike the unobserved controls,
+these full-capture deltas can include startup and must not be labeled strictly
+steady-state counts. Trace-based per-quantum hot measurements remain separate.
+
+Trace follow-up `2026-10-04T14-01-35.795Z-browser` (one trial each) gives:
+
+| Capacity / variant | Hot wall median / p99, µs | Wall overruns | CPU overruns | playbackStats underruns |
+| --- | --- | ---: | ---: | ---: |
+| 1 baseline | 111 / 898 | 7 | 8 | 16 |
+| 1 depth cache | 109 / 537 | 3 | 3 | 41 |
+| 4 baseline | 354 / 2189 | 23 | 24 | 53 |
+| 4 depth cache | 356 / 1910 | 13 | 14 | 165 |
+
+All raw continuity checks pass; frame gaps are zero. The four-voice candidate
+still has a 39288 µs maximum hot Render event. Median CPU is 103/101 µs for
+one voice and 346/347 µs for four. Neither the smaller tail count in this single
+trace nor the successful PCM checks justify real-time readiness. Browser median
+cost is unchanged and underruns persist. The change is a Node execution and
+generated-size improvement, not a demonstrated browser performance fix.
+
+Raw-preserving Node repeat `2026-10-04T14-03-30.314Z-owned-timing` records
+2500 inactive quanta per variant, PCM and every CPU/wall sample. Hot medians
+are 245/152 µs (one voice) and 1129/617 µs (four), baseline/cache. First-block
+times are 79/91 and 137/112 ms. The original timing-only subtrial retained
+timings but no PCM; it remains preserved as such rather than relabeled complete.
+
+To reproduce the selected comparison, run `node tests/instrument-performance/owned.mjs`,
+then supply its evidence directory as `PROPOSALS_DIR` to `benchmark-owned.mjs`
+or to `browser.mjs` with `CONTROL_MODE=owned`. `NO_TRACE=1` separates playback
+counters from tracing, `TRIALS` controls repetitions, and `CHROMIUM_PATH` selects
+the browser executable. Original artifacts and source snapshots are immutable;
+new invocations produce new timestamped directories.

package/docs/instrument-settings.md

@@ -0,0 +1,130 @@
+# Bass / Percussion / Pad candidates (GEN-619)
+
+These are three editable settings of `createInstrument`, using the existing
+stock oscillator, filter, envelopes, LFO and voice policy. Every setting and
+render is **CANDIDATE**. There is no approved golden or physical listening
+acceptance. Runtime remains **NOT_CLEARED**; earlier frame gaps and underruns
+recorded in [PR #26](https://github.com/yuichkun/den/pull/26) are not erased by a
+successful run here. This change is stacked on that unmerged integration
+candidate at `a1a6fd768f7f350f1072babefe00859f1330bfe6`, which includes the
+unmerged instrument composition from PR #22 and main's envelope staging fix.
+
+## Use the existing APIs
+
+```ts
+// processor.ts, compiled by @unworklet/unplugin as usual
+import { createInstrument, bassConfig } from '@denaudio/den/instrument';
+export const processor = createInstrument(bassConfig);
+```
+
+```ts
+// Browser host, after the normal user-gesture audio startup
+import { createNode } from '@unworklet/core';
+import { bassParameters } from '@denaudio/den/instrument';
+import processor from './processor.ts?worklet';
+const node = await createNode(context, processor, { initial: bassParameters });
+```
+
+`percussionConfig` / `percussionParameters` and `padConfig` / `padParameters`
+work the same way. All 22 native parameters are explicitly present in each
+object; the complete values live in `src/instrument-settings.ts`. Edit those
+ordinary values or the existing node AudioParams. There is no new preset,
+serialization, MIDI, routing or loader framework, no new export-map entry and
+no changed engine defaults. Browser compilation remains 48 kHz only on
+unworklet 0.4.1; 44.1/96 kHz coverage is offline.
+
+- Bass: one saw voice, last-held mono legato, gain .12, 5 ms amplitude attack,
+  120 ms decay/release, .7 sustain. The filter rises briefly from 300 to 2400 Hz
+  then settles near 455 Hz. Overlapping held notes preserve the transient;
+  this does not implement portamento.
+- Percussion: one retriggering sine voice, gain .16, 1 ms amplitude attack,
+  220 ms decay to zero, 40 ms release. Pitch falls two octaves over 60 ms;
+  note 36 is about 261.6 Hz at onset, settling to 65.4 Hz. Zero attack enters
+  the first decay step, so the first pitch is slightly below that peak. It is
+  tonal kick/tom-like percussion, with no noise generator.
+- Pad: four saw voices, gain .045, 800 ms attack, 1.2 s decay to .7 sustain,
+  2.4 s release. The shared .12 Hz LFO has an 8.333 s cycle, ±3-cent pitch
+  depth, .08 tremolo depth and .2-octave filter depth. The dry output is dual
+  mono; no stereo spread or unison is claimed.
+
+All envelopes are linear. Release and retrigger begin at the previously emitted
+level. Hard reset/retrigger/stealing can be discontinuous; this is not a
+click-free claim. Sustain zero does not free a held MIDI identity. Send the
+balanced note-offs supplied by the fixtures. There is no CC64 sustain.
+
+Use native `snapshot()` / `restore()` for the **same processor/schema/rate**.
+Construction changes are not portable preset migration. Restoring a new node
+must not revive held notes. For a cold in-place restore, restore, emit `reset`,
+render at least one quantum, then send fresh notes. Reset and MIDI in the same
+quantum follow the reset-wins rule.
+
+## Reproduction and evidence
+
+```sh
+npm ci
+npm run check
+npm test
+# Focused packed candidate check with an installed Chromium:
+CHROMIUM_PATH=/usr/bin/chromium node --test tests/sound-candidates-packed.test.mjs
+```
+
+The regular test command discovers both `tests/instrument-settings.spec.ts`
+and `tests/sound-candidates-packed.test.mjs`. The latter packs den into a clean
+locked consumer, checks the public import and TypeScript declarations, compiles
+all three processors through Vite/unworklet, and runs the muted real Chromium
+MIDI, parameter, release/reset/bypass and snapshot probes at 48 kHz. It does
+not publish a site or change the integration preview.
+
+`tests/sound-candidates-consumer/fixtures.mjs` fixes the FIFO MIDI inputs. The
+Bass and Percussion phrases are 262144 frames at 48 kHz. Pad is 768000 frames
+(16 seconds), with note-offs at 8, 9, 10 and 11 seconds. The last 2.6 seconds
+cover silence following the final release. Lower and higher offline rates
+preserve elapsed time by rounding each event to the nearest corresponding
+128-frame quantum; expanded timestamps and frame lengths are retained.
+
+Separate maximum-velocity inputs cover Bass legato and Percussion release
+retrigger; Pad's maximum case uses four coherent A4 notes. Pad also has a
+released-slot reuse / oldest-held steal case and an obsolete note-off that
+must not release the replacement. These stress renders remain separate from
+the three listening phrases.
+
+Each run writes a new `artifacts/sound-candidates/<timestamp>/` directory,
+preserving previous failures. Raw stereo float WAVs are unnormalized and dry;
+static min/max waveforms have fixed ±1 scale. The manifest binds the source
+commit/dirty bit and SHA-256 source hashes, tarball/lock hashes, dependency
+versions, WASM size/hashes, verification results and candidate status. The
+render evidence binds every construction option, parameter, expanded MIDI
+array, rate, channels, seed (null), frame length, PCM/WAV hashes, exact-silence
+boundary and peak/RMS/headroom/clipped/nonfinite measurements. Phrase renders
+are repeated and their full PCM hashes must agree. Full-render and named-window
+measurements are both retained.
+
+Headroom is measured for these settings and inputs. The full-scale gate rejects
+peak ≥1, nonfinite PCM, or scrubbed samples; it is also tested against deliberate
+wrong signals. **The integration diagnostic's .8 analytic bound does not apply
+to these saw/modulated settings.** No limiter or hidden normalization is added.
+Arbitrary edits, resonances, pitches or voice counts are not covered by a
+measurement for these fixed fixtures.
+
+The independent numerical tests use literal candidate values, closed-form
+linear envelope timing and replacement DC/frequency/cutoff probes. Existing
+sine/static-biquad, saw-property, voice-policy and wrong-answer tests remain in
+place. An audio-rate direct-form biquad is not treated as an exact dynamic SVF
+reference. Headless signal checks are not device playback or listening approval.
+
+## Listening and promotion boundary
+
+Review the three canonical 48 kHz `*-phrase-48000.wav` files together, at a
+comfortable user-controlled playback level:
+
+1. Bass: low core and upper-register audibility; brief bright transient;
+   held-note transition/return without restarting that transient.
+2. Percussion: purposeful short pitch drop, velocity contrast, ringing/chirp
+   quality; the burst intentionally truncates decay and retriggers in release.
+3. Pad: smooth growth, clear chord and subtle slow motion; staggered independent
+   long releases, with voice stealing assessed separately.
+
+Any sound-affecting change requires regenerating the raw audio, waveform and
+manifest. Only explicit human approval tied to those hashes, followed by a
+separate reviewed change, can promote a candidate to a golden. This initial
+change does not merge the integration candidate or clear its runtime gate.

package/docs/instrument.md

@@ -0,0 +1,204 @@
+# MIDI instrument composition
+
+`src/instrument.ts` composes the existing voice policy, oscillator, filter,
+Envelope and LFO. `createInstrument(config)` returns an unworklet processor;
+`instrument` is the diagnostic polyphonic default. There is no new MIDI,
+parameter, routing, snapshot, loader or test framework.
+
+The initial sound is **CANDIDATE**, not an approved golden or one of the eventual
+bass/percussion/pad presets. Those sounds will use this same engine.
+
+## Construction and replacement
+
+Pass a required configuration to `createInstrument`:
+
+- `mode`: `mono` or `poly`; `legato`, `capacity`, `heldCapacity` follow the voice
+  policy. Mono uses one voice; poly defaults to 4. Engine capacity is currently
+  limited to 16, held capacity to the underlying policy's 256. These are fixed
+  construction/compilation bounds, not approved product-wide polyphony limits.
+- `waveform`: `sine` (default) or `saw`, using the existing oscillator.
+- `oscillator` and `filter`: optional compatible unworklet `defineSubgraph`
+  declarations, with the same required config and `tick` signatures as the stock
+  modules. Each is instantiated with separate named state for every voice.
+
+`src/instrument-example.ts` demonstrates replacing both parts with custom
+unworklet subgraphs: a half-level sine and backward-Euler one-pole low-pass.
+The example is intentionally sine-only and its filter ignores resonance; it
+illustrates a concrete replacement, not another full instrument or a quality
+upgrade. Its amplitude/response is checked against independent formulas.
+
+The processor uses unworklet's compile-time sample rate. Offline coverage is
+44.1/48/96 kHz; the published 0.4.1 bundler/browser boundary remains 48 kHz.
+The complete 16-voice graph compiles, but the initial real-time trace found
+frequent deadline overruns at that capacity on the validation host. The engine
+therefore starts at four voices; higher capacities require a device-specific
+real-time budget check. A 32-voice probe produced a
+11,614,744-byte process function before completion-expression materialization, exceeding WebAssembly's 7,654,321-byte function
+limit. The first engine keeps a tested ceiling of 16 at construction;
+16 voices with 256 held identities are tested. These checks establish compilation
+and bounded rendering, not a mobile-device real-time CPU guarantee.
+
+## Ports and musical controls
+
+Use native `node.midi.midi.send(event)` for MIDI, `node.params.<name>` for
+AudioParams, and `node.events.reset.emit({value:1})` for panic. Output `main` is
+two identical channels. Mixing is linear, with no limiter, normalization or
+voice-count attenuation; coherent voices can exceed unity. The diagnostic gain
+is 0.15, and the browser fixture remains muted.
+
+`diagnosticInstrumentParameters` is an ordinary initial AudioParam value map,
+usable with unworklet's existing `createNode(..., {initial: ...})`. It is not a
+separate preset/state format. All continuous controls are a-rate:
+
+| Controls | Units / bounds |
+| --- | --- |
+| `gain` | Linear [0,1] |
+| `ampAttack`, `ampDecay`, `ampRelease` | Seconds [0,30] |
+| `ampSustain` | [0,1] |
+| `pitchAttack`, `pitchDecay`, `pitchRelease`, `pitchSustain` | Same ADSR units |
+| `filterAttack`, `filterDecay`, `filterRelease`, `filterSustain` | Same ADSR units |
+| `cutoff`, `resonance` | Hz [20,20000], Q [0.5,10]; actual cutoff limited to 0.45×sample rate |
+| `pitchEnvelopeDepth`, `lfoPitchDepth` | Semitones [-24,24] |
+| `filterEnvelopeDepth`, `lfoFilterDepth` | Octaves [-8,8] |
+| `lfoRate`, `lfoAmpDepth` | Hz [0,20], tremolo depth [0,1] |
+| `bypass` | Values >=0.5 mute output |
+
+Inputs must be finite and within their declared AudioParam domains. Automation
+and any host smoothing use unworklet/Web Audio, not a den wrapper.
+
+Each voice has three instances of the same linear ADSR. The amp envelope governs
+voice lifetime: zero sustain does not free a held voice; release completion does.
+Audio ends on the exact envelope sample. The allocator consumes completion once
+at block end, before the next block-boundary MIDI dispatch; it does not perform
+quadratic allocation-rank maintenance on every audio sample.
+Pitch/filter envelopes may finish earlier or later but cannot keep an amp-silent
+voice allocated. Retrigger/release starts from each envelope's current level.
+Duration quantization, segment latching and zero-duration behavior are those of
+`envelope.ts`; edits affect the next segment except sustain, which tracks while
+held in the sustain stage.
+
+One shared free-running LFO drives finite amp/pitch/filter destinations, with no
+implicit note reset. For voice i:
+
+- Frequency = MIDI equal-tempered A4=440 Hz × 2^(semitones/12), clamped to
+  [0,0.45×sampleRate]. Semitones = pitch-envelope level × envelope depth + LFO ×
+  LFO pitch depth, with the combined amount clamped to [-24,24].
+- Cutoff = base cutoff × 2^octaves, then clamped to the filter bounds. Octaves =
+  filter-envelope level × envelope depth + LFO × LFO filter depth; the combined
+  amount is clamped to [-8,8].
+- Amp = amp-envelope level × normalized MIDI velocity ×
+  (1 - tremoloDepth × (1 - LFO)/2). Depth zero is unity; depth one spans [0,1].
+
+Both pitch and filter depths are combined in their musical units **before** the
+single final destination clamp. A constant 128-note tuning table supplies MIDI
+base pitches; transcendental pitch ratios use the reviewed modulation module.
+
+## Event order, reset and state
+
+MIDI dispatch remains quantum-boundary FIFO in unworklet 0.4.1. Do not claim
+sample-accurate MIDI. On/off pairs in one block can coalesce to no sound.
+Duplicate identities, velocity-zero note-on, steal/release reuse and mono
+last-held-note priority follow `voice-policy.ts`; CC64 is not implemented.
+
+- A note/retrigger resets its oscillator phase and filter history, while its
+  envelopes retrigger from their current levels. Mono legato leaves those states
+  continuous. Hard stealing/retrigger can click; no listening approval implied.
+- CC123 starts release for that channel. CC120 immediately frees its voices and
+  clears their DSP states. If another note reuses a cleared slot in the same
+  quantum, the clearing sample is silent and its attack begins next sample.
+- `reset` wins over every MIDI event dispatched in the same quantum. It clears
+  the held ledger, voice allocation, pending retriggers, envelopes, oscillators,
+  filters and shared LFO. Output is immediately silent. Fresh notes in later
+  quanta can start normally.
+- Bypass mutes only the output. MIDI, phase, modulation and release continue; a
+  held note reappears when unbypassed, while an ended release remains silent.
+- Inactive slots clear their DSP histories. A new note cannot inherit a completed
+  or panicked voice's tail. Live held-note state is transient: same-schema
+  snapshots restored into a new node restore parameters/shared LFO but do not
+  revive held voices. Inactive
+  histories are cleared on the first rendered sample, including when a new note
+  arrives in the first quantum after restore. That clearing sample is silent;
+  the new note begins at phase zero on the next sample. A pristine instance
+  needs no extra clearing sample. Native 0.4.1 **in-place** restore only overlays
+  persistent slots: it does not initialize transient live voices. For a cold
+  in-place restore, send the existing `reset` after restoring, render at least
+  one quantum, then send fresh notes. Sending reset and fresh notes in the same
+  quantum follows the documented reset-wins policy. No restore wrapper is added.
+  Follow the existing
+  rendered-parameter snapshot constraint; schema migration is not added.
+
+## Verification and integration
+
+`tests/instrument.spec.ts` uses an independent direct-form biquad plus analytic
+sines for the complete signal path, direct closed-form envelopes for per-voice
+release/retrigger, and frequency/cutoff probe replacements for modulation units.
+It tests wrong-answer rejection, stereo equality, zero scrubbed samples,
+polyphony, mono legato, steals, channel panic, reset, edits, bypass and snapshots.
+
+The isolated packed fixture checks declarations/build, renders all three offline
+rates, compiles the replacement example, and drives real 48 kHz browser MIDI and
+AudioParams. It produces raw stereo float WAV, a fixed-scale waveform and a
+manifest binding the exact source hashes/commit, package/lock, all diagnostic
+parameters, MIDI, rates, seed and verification. No audio matcher/golden update or
+FFT is used.
+
+The public subpaths are `@denaudio/den/instrument` and
+`@denaudio/den/instrument-example`. The isolated packed fixture imports the
+replacement oscillator/filter example through that public boundary and renders
+it at 48 kHz (the stock instrument is rendered at all three offline rates). It does not reach into package internals.
+
+## Sustained real-time gate
+
+The instrument-specific browser observer records twelve seconds of actual graph
+output at 48 kHz, including four held A4 voices, note-offs and a one-second
+release. Its fixed capture buffer is test instrumentation only. A sinusoid fit
+from the initial steady window predicts the entire steady interval; a separate
+first-difference bound detects discontinuities and the known release law
+predicts the tail. A separate native `AudioBufferSourceNode` supplies an exactly
+representable reference ramp to the observer's second input. The test requires
+4,500 complete 128-sample blocks and exact ramp progression through all 576,000
+samples, including the silent tail. Duplicate, dropped, reordered, zeroed and
+short-block counterexamples verify the observation contract.
+
+Published `currentFrame` entry/exit values and output timestamps remain in the
+raw evidence. Repeated/skipped published frame values are reported separately
+as `CLOCK_METADATA_ANOMALY_REQUIRES_REVIEW`: a hosted failing and passing capture
+had byte-identical complete WAVs despite different frame metadata. Chromium's
+worklet-scope clock publication can skip a lock-contended update; this mechanism
+does not by itself establish the cause of an individual anomaly. Native ramp
+progression and the independent audio oracle establish the captured graph's
+sequence, not hardware continuity. The artifact retains `NOT_CLEARED`, the raw
+WAV/reference data, waveform, native errors and timestamps. The expected 0.4.1
+`sab-unavailable` notification is recorded; traps and queue/length errors fail.
+
+Chrome audio trace is also collected to inspect per-quantum render durations.
+Raw graph continuity alone cannot establish that the hardware output met its
+real-time deadline. Neither this fixture nor offline correctness substitutes for
+hardware-loopback/device testing or listening approval.
+
+The trace report includes generated WASM sizes/hashes, wall and CPU render
+durations, and counts above the 128-frame budget (2.667 ms). It excludes the
+first second when reporting steady timing and tests the detector with an
+explicit over-budget counterexample. Any observed steady wall-time overrun
+sets `QUANTUM_OVERRUNS_REQUIRE_REVIEW`; passing numerical assertions does not
+override this readiness finding. A four-voice measurement on the validation
+host had median 0.344 ms, p99 0.992 ms, maximum 14.752 ms and 9 steady wall-time
+overruns. Sixteen voices had median 1.447 ms, p99 4.583 ms and 221 overruns.
+These are host-specific observations, not portable capacity guarantees. The
+raw trace and each run's exact figures are preserved with the candidate WAV.
+
+Bounded pitch/cutoff modulation signals and control predicates use existing
+transient unworklet state, because expression reuse alone can expand the graph.
+Oscillator output, filter output and amplitude-envelope level stay expressions:
+native floating-point state writes flush magnitudes below 1e-30, which would
+destroy finite tiny values recoverable by a later custom filter or gain.
+No private memoization API, altered flush threshold or custom-value restriction
+is used. Regression cases include subnormal input, large oscillator/tiny amp,
+tiny filter output and signed zero observed by a replacement filter.
+Transient layout changes are not a migration for snapshots from older revisions;
+the snapshot contract remains identical processor/schema/rate only.
+Voice completion is committed once per block after
+sample processing; this avoids running allocator rank maintenance at audio rate
+while preserving exact sample silence and availability at the next MIDI drain.
+Shared DSP modules remain unchanged; the common expression-expansion/runtime
+performance investigation is still outstanding.

package/docs/integration-candidate.md

@@ -0,0 +1,114 @@
+# Mobile integration candidate
+
+The initial integration candidate is based on reviewed candidate
+`196a1c3ef0e8eda9a007a2474c9d06f7f654acfa` (PR26, including PR28/PR29)
+and main `9fd730bf9afb786edaae808d41208904fb3c844d`. This integration completes
+public subpath access and the permanent packed-site build without changing DSP,
+settings or dependencies. It is not a registry release or a real-time clearance.
+
+The owner supplied positive feedback on the three dry sounds and the integrated
+sound/FX preview on 2026-10-05. That candidate listening feedback is recorded in
+[the acceptance record](initial-acceptance.md). No identical listening request is
+pending. Exact-hash golden promotion remains separate; general physical-device
+stability and the instrument runtime gate remain NOT_CLEARED.
+
+The isolated `tests/integration-consumer` imports the public `./instrument` and
+`./delay-fx` and `./delay-settings` subpaths from the installed package. The instrument is a processor;
+the delay uses a small processor adapter around the existing subgraph. Its stereo
+Web Audio path is MIDI → instrument → delay → master gain → analyser → destination.
+MIDI remains the existing unworklet quantum-boundary interface. No new MIDI,
+parameter, snapshot, serialization, routing or preset framework is introduced.
+
+The sound selector offers Diagnostic, Bass, Percussion and Pad. The three sound
+candidates are the unchanged public `createInstrument` configurations and all 22
+native parameters from PR28, merged into this candidate branch at
+`e87e51f25052d0ad474efe1a928f80908cf3bcaf`. Source SHA-256 checks pin their audio
+identity. These remain sound candidates: no golden promotion or general runtime clearance
+is recorded by this integration. Existing candidate listening feedback is retained
+separately from machine-generated evidence.
+
+Diagnostic retains four sine voices, gain .05, fixed 1 kHz/Q=.5 low-pass and
+10 ms attack/200 ms release. Bass is mono last-held legato and Percussion mono
+retriggered; both show low-register keys and a single C2 hold/trigger button.
+Their controls do not promise a chord. Pad has four saw voices with a slow
+attack/release, and C3/G3/C4/E4 keys plus their chord. Every selector is disabled
+during loading, playback and teardown. Active synthetic changes are ignored,
+without resetting held notes, parameters or the graph. Stopped sound selection
+updates the labels/notes only; Start creates the selected public processor with
+its exact native initial parameters. FX selection restores that FX's mix and
+feedback defaults.
+
+The stereo effects remain Diagnostic delay, Chorus and Rhythmic delay.
+Diagnostic taps are 125/187.5 ms with one-second allocation. Chorus and rhythmic
+use the exported GEN-621 constants: 18 ms chorus taps with .65 Hz/3 ms modulation
+and feedback 0/mix .45; rhythmic uses 120 BPM dotted-eighth/quarter taps, 3.2 kHz
+feedback low-pass and feedback .48/mix .35. Both allocate two seconds. Feedback
+is limited to 0–.5 and wet mix to 0–1. No effect was added.
+
+Output gain now spans 0–1, default 1. The previous diagnostic-only 2× ceiling
+was reduced visibly in the UI because its .8 bound cannot be transferred to
+saw/modulated sources. All raw instrument parameters and gain values remain
+unchanged; there is no normalization, limiter or hidden per-sound compensation.
+See [the sound/FX headroom evidence](sound-audition-headroom.md) for the distinct
+bounds and measured 4×3 matrix. Both stereo channels must be finite, unscrubbed,
+unclipped and within the explicit fixture bounds. The analyser display remains
+a mono monitor with fixed −1 to +1 scale.
+
+Start unlocks a fresh 48 kHz AudioContext in a real gesture. Holds may begin during
+asynchronous loading and retain their latest intent. Release sends note-offs and
+allows the delay tail to decay. Clear sends the existing instrument reset and a
+delay-adapter reset event. Stop fades master gain for 20 ms, disposes both nodes,
+and closes the context. Partial startup failure/cancellation cannot connect a
+late node. Hidden-page teardown and touch/keyboard cancellation are retained.
+
+Run `CHROMIUM_PATH=/usr/bin/chromium node --test tests/integration.test.mjs` on a
+host with that browser, or omit the variable for the pinned Playwright browser.
+The fixture uses the existing pack/install/build helper, a separate locked
+consumer, independent analytic/direct-form references, and browser taps of the
+actual connected instrument/FX outputs. It retains candidate WAV, settings,
+source/package/WASM hashes, every numerical peak, browser results and failures
+under `artifacts/integration`. Generated evidence is never an approved golden.
+`npm run build:integration` produces a standalone integration-only local build.
+The previous public UI has been removed. `npm run build:site` now clears the
+public output and writes only a minimal rebuilding notice, with no old page or
+audio asset retained. Historical combined pages are staged only by
+`tests/site-fixture-build.mjs` in a temporary directory for automated checks.
+Their locked package integrity/collision guards remain unchanged.
+
+`tests/site-fixture.test.mjs` retains the former selected sound/FX, silent
+snapshot, audition, navigation and asset assertions. The full matrix and
+interrupted/repeated lifecycle checks remain in `tests/integration.test.mjs`.
+`tests/site.test.mjs` separately verifies the public deletion and removed-route
+404s. No production branch/project, authentication, access or header setting
+change is needed. Removal publication follows independent review and exact-head
+CI; verification fixtures do not retain the former UI as a product.
+
+The packed and realtime browser gates use Vite preview with `configFile:false`,
+without COOP/COEP headers. The integration manifest records response isolation
+headers, `crossOriginIsolated`, SharedArrayBuffer availability, and the actual
+transport passed to each native AudioWorkletNode. Both instrument and delay are
+verified using `postMessage`. `vercel.json` does not configure isolation headers;
+production browser observation reported the same fallback warning. Direct public
+response-header inspection from this workspace was blocked by the network proxy
+(CONNECT 403), so upstream hosting/proxy headers are not independently verified.
+This establishes fallback coverage, not identical phone scheduling or physical
+audio behavior. No hosting/header settings are changed.
+
+## Verification coverage
+
+The packed numerical matrix covers all four sounds and three FX at dry, default,
+and maximum wet/feedback. Poly cases include coherent four-voice stress; Pad
+runs beyond a full slow-LFO cycle. Existing independent diagnostic oscillator,
+filter and delay references remain, and the new matrix compares each FX against
+an independent per-sample reference using its actual input.
+
+Packed browser checks exercise all twelve selected graphs, all 22 native initial
+parameters, mono/poly note labels, stopped-only selectors, no autoplay, mobile
+layout, default/dry/max-wet-feedback stereo peaks, mute, release, reset and clean
+restart. Existing startup-failure, partial-load cancellation, touch cancellation,
+keyboard renewal, context cleanup, and 15 ms target/20 ms Stop-fade checks remain.
+Screenshots and measurement JSON are retained with candidate artifacts. Browser
+CI is required; a local numerical pass is not a browser pass. Runtime remains
+NOT_CLEARED and generated evidence remains CANDIDATE. Production branch/project
+settings are unchanged; merging this reviewed build configuration deploys the
+initial candidate through the existing Vercel integration.