@denaudio/den 0.0.0-stage → 0.1.0

package/docs/freeze-reverb.md

@@ -0,0 +1,179 @@
+# Bounded FDN freeze-tail candidate
+
+Status: CANDIDATE / NOT_CLEARED. Native mechanical evidence does not establish
+musical approval, browser behavior, or realtime deadline safety.
+
+## Catalog fit and public entry
+
+Original [catalog §10](https://app.notion.com/p/3ef449b4e81d817db1acf1fff48779b3)
+separates algorithmic FDN, convolution, and special tails including freeze/shimmer.
+This is a bounded special-tail extension: four unequal integer delays with a
+Hadamard/2 feedback matrix and an excitation/loss transition into a frozen loop.
+It does not finish the whole catalog row or implement shimmer. The existing
+`algorithmicReverb` remains its own damped/interpolated candidate.
+
+Import `freezeReverb`, `FreezeReverbConfig`, and `FreezeReverbControls` from
+`@denaudio/den/freeze-reverb`. Instantiate with the enclosing `ctx.sampleRate` and
+call `tick(left, right, { freeze, reset })` once per audio sample. It returns wet-only
+`left`, `right`, `freezeAmount` (f32 [0,1]) and `frozen` (boolean). A consumer owns
+its dry/wet blend, bypass behavior, gain staging and any separate tone filters.
+No input/output limiter or automatic audio normalization is applied.
+
+## Fixed configuration and bounded capacity
+
+- `sampleRate`: integer 8000..192000, required
+- `roomScale`: finite [0.5,2], default 1
+- `decaySeconds`: finite [0.1,10], default 1.5; nominal unfrozen loop-loss time
+- `transitionSamples`: integer 0..192000, default 256; each direction uses the
+  same speed, one integer progress step per processed sample
+
+Out-of-contract configuration throws at graph construction. Rebuild for other
+configuration. unworklet eagerly captures at 48 kHz as well as the requested
+rate; use `ctx.sampleRate` rather than a captured host rate.
+
+Line lengths are round(sampleRate * roomScale * [0.0297, 0.0371, 0.0411, 0.0437])
+integer samples. Each line allocates exactly that many f64 values, one i32 cursor
+and one i32 valid count, with one additional shared i32 freeze-progress counter.
+Four transient f64 tap slots materialize all reads before any history write.
+At 192 kHz / scale 2 the lengths are 11405, 14246, 15782, 16781: 58214 f64 values,
+465712 history bytes. There are no dynamically growing buffers or per-sample
+allocations. Actual compiled memory includes runtime and port overhead.
+
+There is no predelay, FFT framing, lookahead or host-compensation latency.
+The first wet arrival is the shortest fixed network delay; dry is absent. Delay
+lengths never move, so freeze transitions introduce no moving-readhead Doppler.
+
+## Excitation, loss and transition contract
+
+Let H be the four-row Hadamard matrix, M=H/2, d_i each delay length and
+q_i=10^(-3*d_i/(sampleRate*decaySeconds)). The outgoing delay samples are x_i.
+For a freeze amount a in [0,1], the line feedback gains are a+(1-a)*q_i.
+The new delay samples are M*diag(gains)*x + (1-a)*B*[left,right], where B contains
+the first two orthonormal Hadamard columns. Wet output projects x through the
+last two orthonormal rows. The output is read before the current input is stored.
+
+- Live (a=0): excitation is admitted and each traversal loses energy according
+  to its fixed q_i. There is no damping lowpass or frequency-selective decay.
+- Freezing: progress increments before processing this sample. From live, N true
+  samples reach a=1. Input admission falls while feedback gains rise.
+- Fully frozen (a=1): excitation is exactly suppressed and every feedback gain
+  is 1. Input changes cannot alter the stored tail. Output continues to observe
+  the circulating state; reading output does not consume its stored energy.
+- Thawing: progress decrements before processing this sample. Loss and excitation
+  return over N samples. Reversing direction continues from the current progress;
+  it does not restart a full ramp. Held controls settle exactly at their endpoint.
+- N=0: immediate endpoints. This and abrupt input/mode changes can click. A ramp
+  reduces coefficient jumps but is not a universal click-free guarantee.
+- Reset has highest priority: this sample's wet output is zero, input is discarded,
+  cursors/valid counts and progress become zero even when freeze is held. Repeated
+  reset repeats this behavior. After release, the requested mode ramps from live.
+
+Reset logically invalidates history in constant time; it does not physically
+zero every buffer cell. Valid counts prevent stale data from reappearing. An
+empty network frozen immediately remains silent. A freeze requested immediately
+with a nonzero transition can still admit excitation during that transition.
+
+## Stability, precision and headroom
+
+In real arithmetic, M is orthogonal. With zero excitation, each delay-state update
+is nonexpansive for every permitted gain, even during arbitrary mode reversals.
+The fully frozen network is lossless in that mathematical model. During sustained
+live excitation the fixed q_max<1 supplies a small-gain bound; for finite-energy
+input and initially empty state, the wet l2 norm is at most input l2/(1-q_max).
+This is conservative, not an output-peak limit or a promise of a particular RT60.
+The frozen output can continue indefinitely in the ideal model; there is no finite
+frozen-tail cutoff. Use thaw to decay or reset to silence immediately.
+
+Implementation feedback/history use f64 and output uses f32. Rounding makes
+perpetual exact energy preservation impossible to promise. Native tests measure
+stored-buffer energy drift, rather than treating fluctuating output-window energy
+as the stored energy. Very-small-state handling is also finite. Exact power-of-two
+internal scaling by 2^256 keeps ordinary and tested tiny f32 signals away from
+unworklet's tiny-state scrub threshold; it does not normalize the audio or restore
+precision lost in floating-point arithmetic.
+
+Supply finite normalized audio with known headroom. The feedback network can
+produce wet peaks above 1; tests retain that behavior. No promise is made for
+arbitrary full-scale f32 magnitude, nonfinite inputs, arbitrarily long precision,
+or edited/corrupt snapshots. The implementation neither relies on scrubbing for
+stability nor presents scrubbed renders as passing evidence.
+
+The integer delays avoid interpolation loss, but a four-line undamped frozen FDN
+can sound metallic, sparse, periodic or colored. Orthogonality and numerical
+correctness do not establish attractive room/hall/plate sound, pleasant freeze
+transitions, echo density, stereo image, or musical usefulness. No physical-room,
+commercial-reverb equivalence or high-quality shimmer claim is made.
+
+## Snapshot and verification contract
+
+Use existing unworklet snapshots only. All four delay histories, cursors, valid
+counts and ramp progress persist. Transient tap materialization is recomputed each
+sample. With the same configuration, sample rate, schema and correctly coordinated
+controls/input, native quantum-boundary restoration continues bit-for-bit,
+including snapshots during a transition or fully frozen nonzero history. Cross-rate,
+capacity, configuration or schema migration is not provided by this module.
+
+`tests/freeze-reverb.spec.ts` uses an independent absolute-time scalar history
+model, with expanded matrix formulas and no circular-buffer or DSL implementation.
+At 44.1/48/96 kHz it checks unequal delays and exact impulse arrivals, live/freeze/
+thaw and reversals, transition extremes, one/held reset while frozen, excitation
+suppression, thaw decay, fresh frozen silence, normalized extremes, tiny excitation,
+full-state continuation and measured stored-energy drift. The drift limit is set
+at 2e-10 relative over 262144 frozen samples before collecting results. Numerical
+oracle tolerances are 3e-7 for normal fixtures and 2e-6 for sustained extreme-input
+fixtures. All in-contract native renders require zero scrubs and finite outputs.
+
+`tests/freeze-reverb-packed.test.mjs` packs the actual package, installs it into a
+fresh retained consumer, checks the actual public subpath and types, and executes
+native WASM with a-rate controls at all three rates against the scalar oracle.
+It checks same-schema frozen continuation, fixed memory, all first arrivals at
+maximum allocation, and records source/package/WASM/audio hashes. Candidate WAVs
+retain raw wet gain. Node process timing is diagnostic only, excludes copies and
+is not a browser, hardware, or deadline certificate. Failure logs and consumers
+are retained for inspection. No host-render replacement stands in for native DSP.
+
+Implementation is original TypeScript/unworklet composition. No third-party DSP
+code or audio assets were copied. The catalog's
+[lossless FDN paper](https://arxiv.org/abs/1606.07729) motivates the distinction
+between mathematical losslessness and actual reverb quality; it is not validation
+of this implementation. Listen to hashed CANDIDATE material before musical approval.
+
+The separate `tests/capture-freeze-browser.test.mjs` requires actual 48 kHz
+worklet freeze/thaw, nonzero paired histories, input suppression, divergent live
+state followed by native snapshot restoration, and held reset/empty freeze.
+These functional browser windows do not measure total stored energy or assert
+sample-aligned continuation; the independent offline oracles retain that scope.
+The actual browser stage remains an exact-head CI requirement before merge.
+
+## Live browser restore ordering
+
+Core 0.4.1 `node.restore()` first asks the worklet to copy persistent states and
+buffers, awaits its acknowledgement, then writes the saved values to host
+AudioParams. The operation is **not atomic across DSP state and AudioParams**.
+While the node runs, even one quantum with old live/unfrozen controls can inject
+new excitation into newly restored frozen buffers before the saved freeze value
+arrives. This is a real execution boundary, not a waveform tolerance issue.
+
+The original PR38 and stacked PR39 browser runs observed paired-left residual
+0.2498931884765625 after restoring equal frozen histories into differently excited
+live instances. Independent native reproduction with the identical 48 kHz WASM
+and one stale-control quantum produced that exact value (right residual
+0.4752197265625). Longer gaps also diverged. Excluded wet scratch is recomputed
+every sample and was not the cause: poisoning it with ±1e90 did not alter the
+correctly coordinated result. The failed hosted artifacts remain preserved.
+
+For this frozen-tail composition, prepare **all saved controls before restore**:
+freeze=true, level=0, the saved disturbance/input control, and reset=false. Advance
+the native audio clock until those values have rendered and the configured freeze
+transition has completed. Confirm the two histories still differ, then restore the
+saved persistent history while those controls remain stable. At full freeze, new
+excitation is suppressed during any acknowledgement gap. The actual browser gate
+observes native control telemetry and preserves exact paired-zero/nonzero-tail
+assertions after restoration. Its earlier raw restore remains an observation;
+a deterministic native stale-gap regression supplies reproducible negative proof.
+
+This protocol uses existing controls and restore only. It adds no synchronization
+hook, serializer or upstream patch, and is not a universal recipe for arbitrary
+live graphs, changing automation, pending events or external audio. Fresh-instance
+offline restoration and correctly coordinated native continuation remain separate
+from unguarded browser restoration across different controls.

package/docs/frequency-shifter.md

@@ -0,0 +1,133 @@
+# Bounded frequency shifter candidate
+
+`@denaudio/den/frequency-shifter` exports `frequencyShifter`,
+`FrequencyShifterConfig`, `FrequencyShifterControls`, and
+`FREQUENCY_SHIFTER_LATENCY_SAMPLES` (31). This is an editable unworklet 0.4.1
+subgraph. It remains **CANDIDATE**, with no listening approval or realtime
+clearance. It performs additive signed-Hz translation. Musical pitch-ratio
+shifting, dual-readhead transitions, time stretching and ideal arbitrary-band
+single-sideband processing remain separate work.
+
+## Entry contract
+
+Instantiate with `{ sampleRate }`, an integer in [8000, 192000], using an explicit
+instance name. Call `tick(input, controls)` exactly once per sample inside the
+caller's native stride-1 `forSample`. Compose two instances for stereo; no hidden
+channel routing or shared phase state exists.
+
+- Input: finite normalized mono audio in [-1, 1]. It is not clipped internally.
+- `shiftHz`: finite f32 audio/control node, clamped to [-sampleRate/4,
+  sampleRate/4]. Positive shifts raise each positive input frequency; negative
+  shifts lower it while it remains above DC. Units are Hz, never semitones.
+- `mix`: finite f32 node, clamped to [0, 1], linear blend of delayed real input
+  and shifted output. Dry and wet have matched 31-sample group delay.
+- `bypass`: bool node selecting the **31-sample-delayed dry** path. Input history
+  and modulation phase keep advancing, so returning wet uses current history.
+- `reset`: bool node with level semantics. Every high sample silences the output,
+  discards its input, invalidates all prior history and holds modulation phase
+  zero. The first subsequent low sample is accepted and uses phase zero.
+
+Output is a mono f32 node. Runtime control edits are immediate and unsmoothed.
+Changing mix or bypass can click. Signed shift changes preserve phase, but rapid
+modulation creates additional sidebands. Apply external smoothing/filtering as
+appropriate; there is no hidden parameter framework.
+
+## Filter, phase, latency and headroom
+
+The imaginary path is a fixed 63-tap, odd-antisymmetric, Blackman-windowed
+discrete-time Hilbert FIR. The real path is delayed 31 samples. The two zero
+endpoints and antisymmetry permit 15 paired multiply-adds with 30 history reads.
+The independent reference derives its full kernel from the inverse DTFT of
+`-i sign(omega)` and evaluates absolute-time convolution, without importing DSP
+coefficients or reproducing its circular buffer.
+
+At output sample n, the shifted signal is
+`delayedReal[n] * cos(phase[n]) - hilbert[n] * sin(phase[n])`.
+The phase advances by `2*pi*shiftHz/sampleRate` **after** output. Modulation phase
+is relative to output time; an input cosine at frequency f has delayed real-path
+phase `-2*pi*f*31/sampleRate`. This convention is checked with a complex DFT,
+including both signs of shift.
+
+31 samples is group delay: 0.703 ms at 44.1 kHz, 0.646 ms at 48 kHz and 0.323 ms
+at 96 kHz. It is not a guarantee that the first 31 wet samples are zero. The FIR
+has pre/post ringing around its center and a startup transient. Dry and bypass
+are exact 31-sample delays, with zero unavailable history.
+
+Zero shift holds the existing modulation phase. A fresh/reset instance with zero
+shift is delayed dry identity. Returning to zero after prior shifting generally
+leaves a fixed real/Hilbert phase rotation; it does not force identity.
+
+There is no limiter. The FIR's absolute coefficient sum is approximately
+2.345624. A conservative peak bound is 3.346 for normalized input and the
+documented mix range, including tiny numerical allowance. Tests include an input
+whose output exceeds 2.34, so unity headroom must not be assumed.
+
+History and centered phase use exact power-of-two f64 scaling to avoid the
+upstream 0.4.1 state-write threshold erasing tiny finite f32 input and tiny signed
+phase increments near zero. This does not remove normal floating-point limits:
+an increment below the accumulator's current f64 spacing can still be lost.
+Native snapshots retain history, phase, cursor and history validity. The running
+quadrature sum is transient and recomputed on every sample. Restore is tested
+bit-identically only for the same graph/schema and sample rate.
+
+## Useful band and alias limitations
+
+The numerical acceptance band is input positive frequencies from 0.05 to 0.45
+times sample rate, with desired and image measurement frequencies kept distinct
+and away from DC/Nyquist. At 48 kHz this is 2.4–21.6 kHz; this short FIR is not a
+broadband low-frequency voice pitch shifter.
+
+Independent coefficient DTFT checks sample 4,001 frequencies in that band. The
+complex shifted-sinusoid tests measure five interior/near-edge carriers, in both
+shift directions, at offline 44.1/48/96 kHz. Their acceptance thresholds are:
+
+- Centered Hilbert real leakage below 1e-13 and imaginary gain error below 0.00035
+  on the coefficient grid
+- Desired/image rejection above 70 dB in the rendered probes
+- Desired complex amplitude error below 3e-5 for each 0.15-amplitude carrier
+
+These are bounded measurements, not a proof over every real frequency or an
+arbitrary rapidly changing signal. DC and Nyquist have no usable Hilbert
+quadrature. Near either edge, image rejection degrades; a near-DC rendered
+counterexample intentionally asserts a substantial unwanted sideband.
+
+There is **no input bandpass or output anti-alias filter**. The caller must keep
+every desired `f + shiftHz` strictly between 0 and sampleRate/2 and leave room for
+modulation sidebands. A translation through DC reflects with conjugated phase;
+a translation through Nyquist aliases back into the band. The signed shift clamp
+does not enforce either guard for unknown input content. Tests deliberately
+demonstrate the Nyquist folding case. This module cannot preserve harmonic ratios
+as a pitch shifter would.
+
+Background on finite-duration Hilbert transitions:
+[Julius O. Smith, Hilbert Transform Design Example](https://www.dsprelated.com/freebooks/sasp/Hilbert_Transform_Design_Example.html).
+The implementation and acceptance numbers above are specific to this module's
+own Blackman kernel and tests.
+
+## Evidence and resource boundary
+
+`tests/frequency-shifter.spec.ts` checks construction, direct impulse/convolution,
+signed complex sidebands, immediate automation and clamps, zero-Hz retained
+phase, delayed bypass, held/off-boundary resets, full normalized f32 amplitudes,
+tiny signed controls, output headroom, aliases, and native snapshot continuation
+at three offline rates. Expectations are independently calculated candidates,
+never replacement golden audio.
+
+`tests/frequency-shifter-packed.test.mjs` installs the actual tarball in an
+isolated locked consumer, strict-checks the public entry, repeats three-rate
+convolution/complex-sideband/state tests and builds its Vite worklet. It retains
+the tarball, consumer lock, JSON measurements and source hashes under the
+candidate evidence manifest. Worklet compilation is not browser execution.
+
+Storage is construction-fixed: 63 f64 history cells (504 bytes), three persistent
+scalar state fields (cursor, validity and scaled phase), plus one transient f64
+accumulator. The generated processor adds normal unworklet input/output/runtime
+storage. No runtime allocation, FFT, asset loading, dependency change, oversampled
+path or background scheduler is introduced.
+
+The fresh isolated consumer measures compilation, actual generated WASM size,
+memory, cold/startup 128-frame cost and 256 warm blocks including five input and
+one output copies. Memory growth and nonfinite scrub counts are asserted zero.
+Reported p50/p99/max and deadline exceedances are local Node diagnostics, not a
+portable deadline or browser realtime guarantee. Browser execution, independent
+review and exact-head integration CI remain distinct acceptance gates.

package/docs/frontend-audition.md

@@ -0,0 +1,22 @@
+# Mobile listening room
+
+This historical Envelope/LFO listening room is now a **test-only** fixture.
+It is not included in the public website. `npm run build:consumer` and the
+independent entry/audition tests still build its isolated packed consumer for
+verification; the public `build:site` command does not call them.
+
+The composition uses public `@denaudio/den/envelope`, `/lfo`, and `/oscillator` subpaths. It is one sine oscillator, one linear envelope, and pitch modulation via the existing LFO/depth function. Native unworklet AudioParams carry control changes. It is a module audition, not the full configurable MIDI instrument or delay FX. Oscillator dependency PR #18 and envelope/LFO PR #17 are merged. Delay/voice work is deliberately outside this first frontend slice.
+
+Start creates and resumes a 48 kHz context in the user gesture. Release lowers the envelope gate; Stop fades the native master gain for 20 ms, disposes the node and closes the context. Pointer capture handles finger release/cancellation, keyboard Space/Enter supports the pad, and page hiding stops audio. A start cancelled during asynchronous worklet installation cannot reconnect its node. No microphone is requested.
+
+Output gain defaults to 0.035 and the control caps it at 0.1. This limits digital amplitude, not device sound pressure. The page tells listeners to begin with low device volume. The waveform samples output after this gain and displays it enlarged four times. The page exposes exact composition source, current settings, candidate status and three listening checkpoints. No click or playback action constitutes listening approval.
+
+## Verification
+
+`tests/audition.test.mjs` packs into an isolated consumer, typechecks public imports, production-builds both pages, renders the actual audition processor against an independent sine-times-linear-envelope formula at 48 kHz, and launches Chromium without an autoplay bypass. A 390×844 touch viewport verifies gesture start, output bounds, volume-zero silence, envelope-release silence, repeated Start/Stop, cancelled touch, startup cancellation, context closure and absence of page errors. Native analyser readings are checked independently of the UI status. Physical iOS/Android behavior still needs device listening; touch emulation does not establish that coverage.
+
+Candidate WAV, source/audio hashes, settings, browser results and mobile screenshots are written under `artifacts/audition`. Existing browser validation remains 48 kHz; known 44.1/96 kHz baked-rate rejections remain expected entry-gate checks. No expected audio is changed and no approved golden is introduced.
+
+The combined numerical suite runs with one worker to avoid CPU contention while compiling/rendering WASM. Default and two-worker runs intermittently exceeded the unchanged LFO test’s five-second timeout; sample assertions and timeout values are unchanged.
+
+The initial audible preview exposed a sustained playback deadline failure that numerical and lifecycle checks missed. See [the real-time investigation and regression](realtime-audition.md). The audition now materializes three subgraph boundaries using transient unworklet state; the test command includes a separate real-time capture/deadline stage.

package/docs/gain-schedule-verification.md

@@ -0,0 +1,53 @@
+# Master stop scheduling: argument and clock observations
+
+The instrument's existing stop path captures `AudioContext.currentTime` once,
+cancels scheduled values at that time, sets the current master level at the same
+time, and requests a zero endpoint 20 ms later. This change leaves that runtime
+code and every audio/gain threshold unchanged.
+
+The previous browser assertion compared the endpoint with a second clock read
+inside its recorder. [The Web Audio clock definition](https://www.w3.org/TR/webaudio-1.0/#dom-baseaudiocontext-currenttime)
+allows the rendering clock to advance between those reads. A correct 20 ms
+schedule can therefore fail the old assertion. Conversely, an incorrect duration
+can appear correct when a clock advance masks its error.
+
+## Retained observation
+
+Post-main run [37399904290](https://github.com/yuichkun/den/actions/runs/37399904290)
+on `6e947866f2be5fcf2f74dfc75ea8ebafc90b0258` failed the inherited assertion
+`abs(rampEnd - sampledCurrentTime - .02) < 1e-9`. Full artifact `11385641596`
+has SHA256 `669a4720f7852e9b48dd52add8623cc0f84428528bf817f5e851352624f286f4`.
+The exact recorded argument/clock tuple was not available for comparison, so
+that specific run remains unclassified. The source-based counterexamples below
+do not prove whether its endpoint was still future or had actually become late.
+
+## Corrected invariant
+
+The test records `cancelScheduledValues`, `setValueAtTime`,
+`linearRampToValueAtTime` and `setTargetAtTime` for each individual GainNode.
+Each completed stop must have, in order:
+
+1. A nonfuture cancellation anchor.
+2. A set-value call at exactly the same anchor, within the master gain range.
+3. A zero ramp endpoint exactly 20 ms after that anchor, retaining the existing
+   1e-9-second interval tolerance.
+4. An endpoint that is still strictly future at the independently sampled ramp
+   invocation clock. Correct relative arguments do not excuse a due/past target.
+
+Every recorded master must finish its sequence. Calls from different nodes cannot
+supply each other's anchors. Target smoothing remains exactly 15 ms and its gain
+range is unchanged. Raw calls, scheduled duration, clock advance and remaining
+time are retained; failures print the complete offending sequence.
+
+The small source-extracted Node tests execute the actual stop function and its
+actual recorder with controlled clock reads. One 128/48000-second advance makes
+the old oracle reject a correct schedule even though 17.333 ms remains. Incorrect
+22.6667 ms and 41.3333 ms intervals can pass that old oracle when matching clock
+advances mask them. The corrected invariant rejects those, missing/reordered or
+cross-node calls, wrong endpoints/values, future anchors, and due/past endpoints.
+
+These are scheduling-contract proofs. The unchanged native offline automation
+test still checks the actual 20 ms linear fade, final zero and sample-step bounds.
+The actual browser run separately checks routing, output levels and cleanup.
+Neither valid API arguments nor these functional checks certify a hardware fade,
+general scheduling latency or runtime acceptance. Runtime remains NOT_CLEARED.

package/docs/initial-acceptance.md

@@ -0,0 +1,79 @@
+# Initial candidate acceptance record
+
+Scope: GEN-608's initial shared DSP, one MIDI instrument engine, three instrument
+settings, one Delay FX engine and two effect settings. No new DSP, framework,
+upstream unworklet change or registry publication is included in this integration.
+
+## Current deployment status
+
+This record retains the initial candidate's historical integration/listening
+history. On 2026-10-06, the previous public UI was removed before rebuilding.
+`build:site` now emits only a rebuilding notice; all historical players and
+checks below are isolated test fixtures, not current public routes. See
+[public site removal](deployment-status.md).
+
+## Decision boundary
+
+This is an **initial usable CANDIDATE**. Source and behavior are based on
+`196a1c3ef0e8eda9a007a2474c9d06f7f654acfa`. The final integration adds missing
+public package subpaths, tests those imports, and makes the packed site build a
+maintainable main-branch deployment while preserving the diagnostic pages.
+Source under `src/`, the sound/FX values, dependencies and lockfiles are unchanged.
+Independent review and exact-head CI are required before main merge. This file
+does not claim the pending final merge or its CI has already completed.
+
+The instrument runtime status remains **NOT_CLEARED**. Intermittent frame-clock
+and output-underrun observations have not been attributed conclusively to den.
+Per the owner's 2026-10-05 direction, den-specific reproducible defects warrant
+investigation; open-ended upstream investigation is not a prerequisite for
+continuing the initial candidate. This is not an all-device stability guarantee.
+No test threshold is relaxed and no historical failure is converted into a pass.
+
+## Acceptance criteria and evidence
+
+| Scope | Implementation / evidence | Boundary |
+| --- | --- | --- |
+| Shared Envelope / LFO / filter | Independent numerical/time/phase/reset/response tests; existing shared implementations are used by both engines where applicable | 44.1/48/96 kHz offline; browser 48 kHz only |
+| Voice / oscillator / instrument (GEN-617) | Voice allocation, legato/retrigger, steals, MIDI note end, per-voice envelopes/modulation, bypass/reset and same-schema restoration; `instrument.spec.ts`, `voice-policy.spec.ts`, isolated packed instrument tests | Construction capacity is not a proven real-time product limit |
+| Reusable public API | `filter`, `voice-policy`, `delay-readhead`, and `instrument-example` now join the existing public subpaths; isolated consumers typecheck and render public imports, including the replacement oscillator/filter | No physical `node_modules/.../dist` import escape remains in the fixtures |
+| Three sounds (GEN-619) | One engine with plain Bass / Percussion / Pad construction settings and complete native AudioParam maps; numerical fixtures and packed dry phrase/stress/snapshot tests | All raw audio remains CANDIDATE |
+| Two FX settings (GEN-621) | Same Delay engine with Chorus and Rhythmic delay settings; independent delay-time/modulation/feedback/tempo/tail and bypass/reset fixtures | Moving-head pitch/click behavior follows the documented contract |
+| Integrated sound/FX use | 4×3 packed numerical and browser matrix, all 22 initial sound parameters, stopped-only selectors, release/reset, cancellation/restart/context disposal; source identity assertions preserve raw candidate sounds | Fixed-input headroom measurements do not cover arbitrary edits or every device |
+| Historical deployment boundary | The initial integration combined identical packed packages with instrument, diagnostics and module audition routes; their verification now lives in isolated test fixtures | The current public UI is removed; existing Vercel access/header/project settings remain unchanged |
+| Provenance | Per-run manifests connect source, dependencies, settings/parameters, MIDI/input, seed, rates, WAV/raw PCM, static waveform and verification | Human feedback and golden promotion are recorded separately |
+
+The prior candidate's [exact-head CI 37279030893](https://github.com/yuichkun/den/actions/runs/37279030893)
+passed 226 numerical, 10 packed and 2 realtime tests. That is prior-revision
+machine evidence, not a substitute for this integration's exact-head run.
+[Headroom evidence](sound-audition-headroom.md) records the 90-row matrix maximum
+peak 0.368202865 (8.678 dB headroom) at Master 1 with zero nonfinite/clipped values.
+The numerical assertions and full existing browser/lifecycle suite remain intact.
+
+## Candidate listening feedback received
+
+- 2026-10-05 15:55 JST: the owner replied “よさそう” to the three-sound WAV review.
+  [Original feedback](https://escentier.slack.com/archives/C0C6LD2PH9S/p1791183335912499?thread_ts=1791107749.905829&cid=C0C6LD2PH9S)
+- 2026-10-05 16:57 JST: the owner replied “問題なさそうありがとう” after the
+  integrated preview with sound switching and combined FX.
+  [Original feedback](https://escentier.slack.com/archives/C0C6LD2PH9S/p1791187049139809?thread_ts=1791107749.905829&cid=C0C6LD2PH9S)
+
+These are positive candidate direction and device-use evaluations. Neither
+request is awaiting a reply. They are not exact-source/audio-hash golden
+approval, a general-release decision, or a claim of universal device stability.
+No golden file is added or changed. Future sound changes require new evidence;
+this integration does not silently transfer approval to different DSP/settings.
+
+## Retained failures and limits
+
+The original candidate `334d2db` had a local packed frame-clock failure (8/9
+passed) and normal native/full realtime underrun failures. Later CI passes do
+not erase those observations. The [PR26 historical record](https://github.com/yuichkun/den/pull/26)
+retains the failed logs/archive hash and exact later runs. The
+[instrument investigation](instrument-performance.md) and
+[realtime audition record](realtime-audition.md) retain controls and limitations.
+PR28 also retains local browser/timeout restrictions and the cancelled short-job
+run separately from its eventual successful CI. Do not relabel those runs.
+
+Generated test manifests describe that run's mechanical/physical-listening
+limits; they do not negate the separately linked owner feedback. Hardware
+loopback, broad device coverage and approved golden baselines are not claimed.