@denaudio/den 0.0.0-stage → 0.2.0

package/docs/contracts.md

@@ -0,0 +1,141 @@
+# Entry contract for parallel DSP work
+
+This document preserves the original G0 entry proposals and their provisional
+bounds. It is historical design context, not a statement that only the gate exists
+or that later public exports are unavailable. Current module contracts and the
+implemented initial package/site boundary are linked from [the README](../README.md)
+and [the acceptance record](initial-acceptance.md). Later reviewed module-specific
+contracts supersede the provisional choices below.
+
+The current package uses unworklet **0.6.0**. Its entry gate renders in real
+Chromium at 44.1/48/96 kHz, and snapshots include current AudioParam values even
+before rendering or while suspended. The 0.4.1 rate restriction and suspended-edit
+workaround below are historical. Incompatible slot types are now skipped instead
+of reinterpreted; live restore applies saved AudioParams before persistent state.
+See [dependency findings](dependency-findings.md) for the checked regressions and
+remaining constraints. Snapshots still require the same processor/schema, sample
+rate and render quantum; this upgrade does not imply general automation rollback,
+cross-target migration, transient-state clearing or human audio approval.
+
+## Authority and provisional choices
+
+The approved initial-scope specification says that individual DSP methods and
+numeric upper bounds are not yet determined. GEN-610 asks the entry work to make
+those boundaries concrete for review; it does not approve a particular voice
+count, delay capacity, filter law, or musical behavior.
+
+The numbers and engine policies below are **provisional implementation proposals**,
+not user-approved product limits or tested defaults. In particular:
+
+- **16 voice slots** is a candidate starting capacity for testing chord overlap,
+  release reuse, and deterministic stealing. It is not derived from a measured
+  CPU/memory budget. GEN-616 must select/benchmark capacity and expose it as fixed
+  construction configuration, rather than assuming 16 is a product-wide ceiling.
+- **Two seconds per delay channel** is a candidate starting allocation for short
+  effects and delay fixtures. At 96 kHz, stereo f32 buffers with two guard samples
+  use 1,536,016 bytes. This is not a validated product memory budget. A whole note
+  at 30 BPM requires eight seconds, so the candidate capacity does not cover all
+  rhythmic settings. GEN-615/GEN-620 must jointly choose capacity and explicit
+  out-of-capacity behavior; silent tempo-time clamping is not accepted as correct
+  rhythmic playback. Keep maximum delay as fixed construction configuration.
+- All other stated ranges, signal shapes, voice priorities, interpolation,
+  feedback/mix, and bypass policies have the same provisional status. Later lanes
+  must validate or revise them with independent numerical evidence and review.
+  Review-approved code decisions still do not imply human sound approval.
+
+The gate proves only the public package/subgraph boundary, mono one-sample memory,
+linear gain [0,1], actual parameter edits, and same-schema snapshot continuation.
+It contains no 16-voice allocation or two-second delay implementation. DSP lanes
+can propose revisions without seeking a new product decision for every engineering
+choice, but must coordinate changes that affect shared consumers/contracts.
+
+## Composition and state
+
+- One ESM package, `@denaudio/den`; current exports are `gateCell` at the root and
+  `gate` at `/gate`. Subsequent module exports require integration review.
+- Reusable DSP is an existing `defineSubgraph` declaration. Use required config
+  arguments (no default parameter), and `instantiate(unit, config, {name})` with
+  stable, unique instance names. Audio-rate inputs/outputs use unworklet
+  `Node<'f32'>`; boolean controls use `Node<'bool'>`. No custom graph or routing API.
+- Configuration is immutable per instantiation: sample rate, fixed capacities,
+  selected DSP mode. Continuous controls use existing a-rate AudioParams and
+  graph inputs. No den parameter registry or preset format.
+- Internal phase, history, and buffers use unworklet state. Persistent slots have
+  stable names/types; use existing snapshot profiles, codec, and migration APIs.
+  Gate restoration is verified only for the identical processor/schema and rate.
+  Never treat same byte width as type compatibility (#79). A schema change needs
+  an explicit reviewed migration and its own tests before old snapshots are used.
+- Native transient state is excluded from snapshots, not automatically reset by
+  an in-place restore. Fresh-driver offline restore starts from declaration
+  defaults; browser `node.restore()` leaves current excluded notes/controllers
+  unchanged. A cold live restore requires the composition's explicit reset,
+  followed by a rendered quantum before fresh notes. Do not infer live clearing
+  from fresh-instance offline evidence.
+- Save after AudioParam edits have actually rendered, while controls are stable
+  (#78). A suspended snapshot is not a reliable capture of pending edits in 0.4.1.
+  This gate does not solve suspended preset editing or in-flight automation recall.
+- Live `node.restore()` in core 0.4.1 is not an atomic state/AudioParam transaction.
+  The worklet copies persistent slots before acknowledging; only then does the
+  host restore AudioParam values. A running quantum can use restored history with
+  old controls. For the frozen-tail composition, first set every saved control,
+  confirm those values have rendered (including completed freeze transition),
+  then restore history while controls remain stable. This is a scoped caller
+  protocol, not a generic atomic-restore API or a guarantee for arbitrary graphs,
+  automation, external inputs or pending events. See [freeze restore](freeze-reverb.md#live-browser-restore-ordering).
+- Worklet compilation is sample-rate-specific. Offline rendering is verified at
+  44100, 48000, and 96000 Hz, with 128-frame quanta. The existing 0.4.1 Vite plugin
+  compiles at 48000 and exposes no sample-rate option; real browser contexts at
+  44100/96000 are verified to reject creation. Browser rendering is proven only
+  at 48000. Non-48-kHz browser loading remains an upstream limitation, not a requirement
+  of this entry gate and not a blocker for den development. Do not bypass the
+  mismatch guard or claim multi-rate browser readiness. The supported browser
+  scope is explicitly 48 kHz; offline multi-rate coverage is separate.
+- State allocation is fixed at graph creation. No dynamic audio-thread allocation.
+  Reset uses existing node/event control, clears histories/voices/phase immediately
+  at its dispatched sample, and may create a discontinuity. Reset is not bypass.
+
+## Module boundaries and provisional defaults
+
+| Lane | Graph boundary and units | Proposed policy for first integration |
+| --- | --- | --- |
+| Envelope (GEN-611) | Gate/retrigger → normalized unipolar level [0,1] and completion flag. Attack/decay/release seconds [0,30], sustain [0,1]. | One state per voice/use; zero time is instantaneous. Retrigger from current level; note-off releases from current level. Completion only when release reaches zero. Lane selects/documents curve law; no second envelope engine for pitch/filter. |
+| LFO/modulation (GEN-614) | Rate Hz [0,20], phase cycles [0,1), reset → bipolar unit signal [-1,1]. Depth is applied at the destination in its own units. | Rate 0 holds phase. Free-running or explicit phase reset; no implicit note reset. First shape sine; further shapes need lane tests. Pitch depth semitones [-24,24], cutoff depth octaves [-8,8], delay depth seconds [0,0.05]. Clamp the composed destination to its bounds. |
+| Filter (GEN-612) | Mono normalized audio → mono audio; cutoff Hz [20,min(20000,0.45×sampleRate)], resonance Q [0.5,10]. | One low-pass method selected and justified by this lane. Independent state per voice/channel. Reset clears history. No hidden gain normalization; response/peak bounds must be established before integration. |
+| Voice policy (GEN-616) | Existing MIDI events → per-voice note, gate/retrigger, velocity [0,1], release completion. | Candidate default 16 slots, fixed per construction; mono uses one. Mono last-note priority, legato preserves envelopes until an explicit retrigger. Poly reuse free, then oldest releasing, then oldest active voice; deterministic slot-index tie break. Duplicate note-ons allocate separately; note-off releases oldest matching active channel/note. Velocity-zero note-on means note-off. Completion returns a voice to free; reset/all-sound-off clears all. |
+| Oscillator (GEN-613) | Frequency Hz [0,0.45×sampleRate], phase reset → mono signal nominally [-1,1]. | Per-voice phase cycles [0,1); rate 0 holds. MIDI tuning A4=440 Hz, equal temperament. Lane selects one band-limited method and documents alias/level limits. Reset phase 0. No new MIDI receiver. |
+| Delay read-head (GEN-615) | Mono input and delay seconds [1/sampleRate,2] → delayed mono output. Two independent instances form stereo FX. | Candidate allocation ceil(maxDelaySeconds×sampleRate)+2 samples per channel, initially proposing maxDelaySeconds=2; no resizing. Linear fractional interpolation with wrapped adjacent reads. Continuous moving head (Doppler behavior), not dual-head crossfade. Clamp time after modulation; reset clears buffer and pointers. |
+
+Methods and exported types for unfinished modules are deliberately not stubbed:
+use each lane's own tested unworklet subgraph with reviewed boundaries, then bring
+public exports through integration review. `tests/consumer/contract.ts` demonstrates
+composition from the packed public entry. The small gate's actual `tick(input,
+gain)` is solely a packaging example, not an imposed interface for every module.
+
+## Engine integration targets
+
+One instrument: existing MIDI input `midi`, stereo audio output `main`, mono DSP
+per voice feeding equal L/R initially; amp and velocity gains are linear, no
+limiter or automatic loudness normalization. Mono/poly is immutable configuration
+for the first engine. Voice stealing hard-retriggers from current envelope level;
+its click behavior needs numerical and listening evidence before sound approval.
+
+One stereo delay: audio input/output `main`; mono callers duplicate L/R explicitly.
+Feedback gain [0,0.95], low-pass tone in the feedback path, dry/wet linear crossfade
+[0,1]. Input stop preserves decay. Bypass emits unity dry only, feeds zero new input
+to delay, and lets internal feedback decay; unbypass can expose a remaining tail.
+Reset clears that tail immediately. BPM [30,300], note durations converted to
+seconds; out-of-capacity behavior remains a joint read-head/tempo decision and
+must not silently alter a requested rhythm. Tempo changes provisionally use the
+same moving-head policy.
+Feedback stability and stereo/tempo details are later integration tasks, not claims
+established by this one-sample gate.
+
+## Acceptance each lane must supply
+
+Use unworklet offline rendering and existing test helpers after checking their
+behavior. Provide independent formulas/reference oracles, endpoint and modulation
+cases, sample-rate/capacity boundaries, reset tests, and exact input/settings.
+No expected waveform may be copied from the implementation as its correctness
+oracle. Counterexamples must fail. Human hearing can remain pending independently
+of code/numerical work; artifacts stay candidates. Envelope/LFO/filter/oscillator/
+voice/read-head work can proceed in parallel only after this entry contract review.

package/docs/control-modulation.md

@@ -0,0 +1,194 @@
+# Control modulation candidates
+
+Catalog §5, additive `@denaudio/den/modulation` entry. Existing `envelope` and
+`lfo` implementations and contracts are unchanged. These are graph-native fixed
+state modules for instruments and FX, not a transport, routing layer, arbitrary
+scheduler, MIDI framework, approved sound library, or real-time guarantee.
+
+## Shared execution contract
+
+Instantiate during graph construction, with an integer sample rate from 8,000
+through 192,000 Hz where a rate is required. Call each instance's `tick` exactly
+once per audio sample. All dynamic numeric inputs must be finite. Audio/event
+rates are not silently smoothed or converted to control-block rates. Changing
+sample rate requires reconstruction; same-schema snapshots continue an instance
+at the same sample rate and construction settings. No cross-configuration or
+cross-rate snapshot compatibility is claimed. Give independent instances distinct
+unworklet names.
+
+Construction checks reject nonfinite values, unsupported modes, invalid bounds,
+or capacities. Fixed capacities are at most 16 MSEG segments and 64 sequence
+steps. Arrays are copied at construction; no dynamic graph/buffer growth occurs.
+
+Scalar histories that can contain tiny f32 controls use exact power-of-two f64
+scaling. This avoids core 0.4.1's tiny scalar-state write flush without introducing
+a control dead zone. Sample-and-hold preserves the entire finite f32 input range,
+including subnormals and values above full scale.
+
+## Musical clock
+
+`musicalClock({ sampleRate, mode, steps, stepsPerBeat? })` exposes
+`tick({ rate, reset, seek, position }) -> { step, phase, tick }`.
+
+- `mode` is `free` or `tempo`; `steps` is a fixed integer 1..64.
+- Free `rate` is steps per second. Tempo `rate` is BPM. Both clamp to [0,1000].
+- Tempo `stepsPerBeat` defaults to 1 and accepts powers of two from 1/64 to 64.
+  Free mode requires the default 1. Thus the maximum step rate is below the
+  minimum sample rate and at most one boundary can occur per sample.
+- `step` is an integer-valued f32 in [0,steps); `phase` is an f32 fraction in
+  [0,1), capped at the largest f32 below 1 to keep the public range exact.
+- Output describes the current sample before integrating its rate. The initial
+  sample ticks, even at rate zero. Subsequent zero rate holds the current phase.
+- Rate changes preserve phase. The sample receiving a new rate uses that rate
+  for the next sample's phase. A pending boundary tick remains observable if
+  the new rate becomes zero on the boundary sample.
+- Held `reset` pins step/phase to zero and suppresses all ticks. The first
+  reset-low sample emits the start tick and starts integrating again.
+- `seek` applies only on its rising edge. Held seek does not freeze phase or
+  retrigger. `position` is in steps, explicitly clamped to [-1048576,1048576],
+  then wrapped to [0,steps). Negative positions wrap backward. A seek emits a
+  tick on that sample, including a seek into the middle of a step.
+- Reset wins over seek and consumes the seek level. A seek held across reset
+  release needs another low→high edge to take effect.
+
+Internal phase uses compensated f64 accumulation in frequency units. It avoids
+rounding a noninteger samples-per-step period and divides only for phase output.
+There is no growing global position counter or global duration limit. This is a
+numerical design, not a proof of perpetual drift-free behavior: the accompanying
+tests compare measured boundary samples against independent schedules at
+44.1/48/96 kHz, with documented observation lengths.
+
+## Fixed step sequence
+
+`stepSequence({ sampleRate, mode, stepsPerBeat?, steps })` accepts 1..64 fixed
+`{ value, gate }` entries. Values are [-1,1], gate fractions [0,1]. Its `tick`
+uses the clock controls and returns `{ value, gate, step, phase, tick }`.
+
+Value changes exactly with step selection. Gate is true while the internal f64
+phase is strictly less than the selected gate fraction: zero never opens and one
+stays open for the whole step. Reset always gates off but exposes step zero's
+value. Release opens the gate according to the first step. Tempo/free zero holds
+a currently open gate; callers wanting a stop must use reset. Adjacent gate-one
+steps can stay continuously high, while `tick` still identifies step starts.
+Gate decisions use f64 phase, not the rounded public f32 phase. No interpolation,
+swing, arbitrary ordering, note allocation, or implicit smoothing is provided.
+
+## MSEG
+
+`mseg({ sampleRate, initial, segments, loop? })` accepts `initial` and segment
+`target` values in [-1,1], and 1..16 `{ seconds, target, curve }` entries.
+Durations are fixed at construction, in [0,30] seconds, rounded to the nearest
+sample with half-samples rounded up. Curves on normalized segment time t are:
+
+- `linear`: t
+- `easeIn`: t²
+- `easeOut`: 2t−t²
+- `smoothstep`: 3t²−2t³
+
+`tick({ trigger, reset })` returns `{ value, done, segment }`. A rising trigger
+starts from `initial`, emitting step 1 on that sample. A positive N-sample segment
+reaches its target on step N. A held trigger does not retrigger. A new rising
+trigger restarts from initial even while already running, intentionally permitting
+a jump. Reset wins, consumes the trigger level, emits initial, and sets done.
+Idle segment is zero; active segment is an integer-valued f32 list index.
+
+Zero-duration segments collapse at their exact boundary in list order, including
+those after a positive segment's endpoint; the last coincident zero segment wins.
+A nonlooping all-zero MSEG reaches its last target and becomes done on its trigger
+sample. Otherwise done becomes true on the final endpoint sample and the final
+value remains held. No threshold tail detection is used.
+
+Whole-envelope looping emits the final endpoint before the next iteration's
+first step. It can jump when the final target differs from initial. There is no
+implicit crossfade or smoothing. An all-zero loop is rejected. This first version
+does not add sustain-point, release-segment, partial-loop, or runtime duration
+editing semantics.
+
+## Sample-and-hold and correlated random
+
+`sampleAndHold({ initial })` has `tick(input, trigger, reset)`. Initial is bounded
+to [-1,1], but sampled input is any finite f32. Trigger is level-sensitive: each
+high sample stores that sample's input. Low trigger holds finite f32 numeric values; the native scalar-state write
+canonicalizes negative zero to positive zero. All nonzero finite values, including
+subnormals, remain bit-exact. Reset wins, restores initial, and holds it throughout a held reset.
+
+`randomModulator({ seed, initial })` has
+`tick({ trigger, reset, correlation })`. Seed is an integer 1..2147483646;
+initial is [-1,1]. On every high trigger it advances the Park–Miller recurrence
+`s = (16807*s) mod 2147483647` using exactly represented f64 integers, maps
+`u = 2*(s−1)/2147483645−1`, then outputs
+`correlation*previous + (1−correlation)*u`. Correlation clamps to [0,1].
+
+Zero correlation is seeded uniform S&H. Positive correlation makes a bounded
+first-order correlated sequence. One holds the value but still advances the seed;
+returning to zero therefore resumes at the advanced random position. Reset
+restores both seed and initial, with no PRNG advance even if trigger is high.
+Independent instances do not share random state. No cryptographic suitability,
+Gaussian distribution, variance normalization, target spectral color, or sound
+quality equivalence is claimed.
+
+## Evidence and limits
+
+`tests/control-modulation.spec.ts` uses independent closed-form curves, exact
+BigInt PRNG arithmetic, sample-index timing schedules, boundary/held-control
+checks, seed isolation, snapshots, and bounds. The packed consumer installs the
+actual tarball using its pinned npm lock, imports only the public entry, typechecks
+strictly, compiles and renders actual DSP at 44.1/48/96 kHz, and checks zero scrub.
+Any emitted evidence is CANDIDATE. No new human-approved golden or browser/hardware
+real-time claim is made.
+
+The native MIDI probe in `tests/probes/control-midi-output.mjs` verifies offline
+note-on/off at samples 127/128 when explicit absolute `atSample` is supplied.
+This is only a native emitted-event entry proof. Browser bridge, WebMIDI device,
+and external host delivery are not verified. An output declaration alone is not
+host integration proof. The bounded arp below builds only on the proven native
+emitted-event path.
+
+
+## Fixed-note arpeggiator candidate
+
+`fixedArpeggiator({ sampleRate, mode, stepsPerBeat?, channel, notes })` accepts a
+fixed list of 1..64 `{ note, velocity, gate }` entries. Channel is an integer
+0..15, note 0..127, velocity 1..127, gate fraction [0,1]. The list plays in its
+specified order. It does not capture incoming chords, allocate voices, alter
+transport, or add another MIDI queue.
+
+`tick(output, { rate, reset, seek, position, atSample })` receives a native
+`MidiOutputHandle` created by `event.midi({ to: 'main', ... })`. It returns
+`{ note, gate, step, phase, tick }` and conditionally emits native note events.
+The clock/reset/seek contracts above apply unchanged.
+
+- Gate zero is a rest and never produces a note-on.
+- At each step-start tick, an existing note is turned off before the new note
+  is turned on, even for repeated pitches and gate-one adjacent steps.
+- When the selected gate closes, the active note is turned off once.
+- Seeking turns the old note off first; it starts the new note only if the
+  seeked phase lies within that step's gate. A held seek does not retrigger.
+- Reset turns the active note off once, suppresses starts while held, and
+  starts step zero on reset release if that step is not a rest.
+- Rate zero holds phase and any active note. Send reset and process that sample
+  before stopping/disconnecting. This module cannot guarantee a note-off after
+  the host abruptly stops calling it, loses queued events, or loses a device.
+- The caller supplies the absolute `atSample` timestamp as a `Node<'i32'>`
+  containing native unsigned 32-bit timestamp bits. The native reader interprets
+  the bits unsigned: the signed 2^31 boundary is preserved, and 2^32 wraps to 0.
+  This is the native format limit, not an indefinitely monotonic timestamp API.
+  Caller and host own epoch/transport interpretation. The module does not add
+  a global timestamp counter or another transport. No implicit lookahead exists.
+- At most one off plus one on can be emitted by this producer on any sample.
+  A dedicated output capacity of at least 256 covers the conservative two-event
+  bound for a 128-sample quantum when drained every quantum. Native tests verify
+  all 256 slots are usable. This is not a lossless guarantee if the host stops
+  draining or additional producers share that ring. Native overflow drops the
+  oldest event, which can lose a note-off; host diagnostics and lifecycle matter.
+- Same-schema snapshot continuation is demonstrated only when the external MIDI
+  recipient has the matching note state. Restoring a DSP snapshot into an empty
+  or different MIDI device state does not reconstruct that device's notes.
+
+`tests/control-arpeggiator.spec.ts` checks actual native event payloads/order,
+zero/full gates, reset/seek/tempo changes, stopped-rate hold, reset-before-stop,
+repeated pitches, same-schema continuation, signed timestamp crossing and uint32
+wrap at 44.1/48/96 kHz. A bounded burst test proves 256 usable native ring slots
+and retains an undersized-128 counterexample that loses the first half of the
+burst. These are offline native-event tests; browser bridge, WebMIDI devices,
+external host delivery and human musical approval remain unverified.

package/docs/convolution.md

@@ -0,0 +1,50 @@
+# Bounded uniform convolution candidate
+
+`partitionedConvolution({ blockSize, impulse, renderQuantumSize: ctx.renderQuantumSize }).tick(input, reset,
+everyNSamples)` uses the existing stride-1 `forSample` scheduler. This is a small
+uniform-partition frequency-domain convolution, not a direct FIR relabeled as
+FFT processing. It is CANDIDATE and has no human or realtime acceptance.
+The initial B<=32 and IR<=128-sample range is a bounded partitioning/FIR proof,
+not a practical convolution-reverb or complete catalog §10 capability.
+
+## Contract
+
+- Pass `ctx.renderQuantumSize` from the enclosing processor. Dispatch runs every
+  `gcd(B, renderQuantumSize)` samples, and the persistent cursor commits only at
+  true B-sample boundaries. This preserves block-atomic snapshot phase even when
+  the quantum does not divide B. Off-phase work is eager; small or coprime
+  quanta increase cost and do not gain realtime clearance.
+- B is a construction-fixed power of two in 4..32; N=2B. The original/fixed IR has
+  1..4B taps, each finite in [-1,1], and sum of absolute tap values <=4. Input is
+  finite normalized audio [-1,1]; output is not clipped or gain-normalized.
+- The IR is split into at most four B-sample partitions, each zero-padded to N.
+  Its complex spectra are calculated from the DFT formula at graph construction.
+  Runtime uses the internal radix-2 FFT, frequency-delay line, complex products,
+  normalized IFFT and overlap-add. No dependency, loader, alternate runtime,
+  dynamic allocation, runtime IR update or new snapshot system is introduced.
+- At sample t=mB, the previous input block [t-B,t) is transformed. For output
+  block m the spectral sum is Σ H_p X_(m-p), then its 2B time samples are added
+  to [t,t+2B). Algorithmic latency is exactly B samples. The IR's own leading
+  zeros/predelay and tail of L-1 samples are additional, separate properties.
+- Reset immediately outputs zero, discards its input sample and pre-reset tail,
+  invalidates history and earlier partitions, and preserves native hop phase.
+  The partial first block after reset is zero-padded before the reset boundary.
+  Held reset remains silent. Flush with B+L-1 zero samples to hear the full tail.
+- Fixed f64 buffers use exact 2^128 scaling for input/history/spectra, avoiding
+  0.4.1's 1e-30 buffer-write flush discarding f32 subnormal audio. IR coefficients
+  are double constants. No treatment of arbitrary nonfinite inputs is promised.
+- Persistent history, overlap, spectra and indices use native full snapshots.
+  FFT/mixed-spectrum scratch is transient and rewritten before use. Same graph
+  and rate/quantum are required. Changing IR/configuration requires a new graph; no
+  migration, IR swap, crossfade, stereo adapter or long-room support is implied.
+
+## Required evidence
+
+Three-rate direct time-domain FIR comparison covers one tap, partial final
+partitions, all partition counts, taps at partition boundaries, random original
+IRs, impulse/full tail, all reset hop phases, zero IR and linearity. Snapshot
+continuation must be bit-identical, no output scrub is accepted, and instance
+memory must stay fixed. Packed consumer and generated-worklet checks remain
+separate gates. Measured local cold/warm quantum costs are diagnostic only.
+The shared N64 FFT/STFT proof measured a 298-ms cold first quantum locally;
+this is a startup hazard, not a runtime-safe building block certification.

package/docs/curve-shaper.md

@@ -0,0 +1,117 @@
+# Editable curve shaper
+
+Status: **CANDIDATE**.
+
+This additive catalog §7 module is a bounded piecewise-linear user curve/LUT.
+It uses only unworklet 0.4.1 graph nodes and native state. No additional parameter,
+asset, snapshot, routing, loader, or test system is introduced.
+
+## Public entry
+
+`@denaudio/den/curve-shaper` exports `curveShaper`, `CurveShaperConfig`,
+`CurveShaperControls`, and `CurveShaperQuality`.
+
+- Config: `sampleRate` finite in [8000,192000] Hz; `pointCount` integer in [2,17];
+  immutable `quality: 'direct' | 'adaa'`, default `'adaa'`.
+- `tick(input, controls)` is called once per sample. `input` is f32. Controls are
+  `gain`, `mix`, `reset`, and `ordinates: readonly Node<'f32'>[]` with exactly
+  `pointCount` entries. Ordinates may be constants, native params, or graph signals.
+- Equally spaced immutable input knots cover [-1,1], including both endpoints.
+  Each audio-rate ordinate is clamped to [-1,1]. NaN becomes zero; infinity
+  saturates. Values outside the knot domain use the nearest endpoint ordinate.
+- Input clamps to [-8,8], gain to [0,32], mix to [0,1], with NaN becoming zero.
+  Gain is a linear multiplier; no automatic loudness compensation is applied.
+- Direct quality evaluates linear interpolation of the current ordinates.
+- ADAA averages the **current sample's curve** over the previous/current driven
+  input interval by summing overlap trapezoids. It never differences primitives
+  computed under different ordinate values. At almost equal inputs a midpoint
+  replacement uses distance <= 1e-6/(pointCount-1). Since each segment has
+  slope magnitude <= pointCount-1, the mean-versus-midpoint error is bounded by
+  slope*distance/4 <= 2.5e-7, including knot crossings.
+- Gain and ordinate edits are immediate. This antialiases the input interpolation
+  for a fixed curve; rapid curve edits can still produce sidebands and aliasing.
+  There is no smoothing, edit crossfade, arbitrary-graph oversampling, higher-order
+  ADAA, or guarantee of a bandlimited output.
+- Direct dry is immediate. ADAA dry is the same two-sample mean as a linear curve,
+  with half-sample group delay and cosine rolloff. Mix zero is not transparent
+  bypass in ADAA mode. Arbitrary asymmetric curves can generate DC; no DC blocker
+  is built in.
+- Reset clears input and dry histories before the current sample. The first ADAA
+  interval therefore begins at zero. Same-schema native snapshots preserve those
+  histories. Point-count or quality migration is not promised.
+- Output is bounded by the blend of |dry|≤8 and |wet|≤1. State uses exact binary
+  scaling to retain recoverable f32 subnormals through native state-write flush.
+
+## Evidence and limits
+
+Independent scalar interpolation and knot-segmented quadrature, 44.1/48/96 kHz,
+minimum and maximum point counts, asymmetric and folded user curves, knots and
+endpoint extension, finite/extreme/non-finite controls, gain/mix/ordinate editing,
+reset, same-schema snapshot continuation, independent instances, tiny inputs,
+linear dry alignment and measured fixed-curve folded-alias comparisons.
+
+The packed isolated consumer must compile only public declarations, render actual
+WASM, check the independent oracles and record source/package/audio hashes.
+Generated audio is **CANDIDATE**, never an approved golden. Browser deadline,
+listening approval, and oversampling are separate claims.
+
+The independent integration owner approved this bounded entry before DSP
+implementation. Existing `/drive`, reduction, and all other DSP remain untouched.
+
+## Numerical implementation
+
+Internally, t=(pointCount-1)*x makes knot locations exact integers separated by
+2. Sign-changing segments use a barycentric zero-crossing anchor, with explicit
+zero-valued endpoint branches and protected zero-slope division. This avoids
+spurious nonzero output at symmetric zero crossings when the original x spacing
+is not exactly representable in binary. Same-sign segments use ordinary linear
+interpolation. Histories retain the driven x rather than a rounded LUT index.
+
+The rejected fractional-knot/root implementation is retained only in a test
+fixture. Its four-point symmetric curve creates about 5.55e-17 of spurious DC
+at exact zero; the silence oracle must continue rejecting it. It is not shipped.
+The corrected implementation is checked for exact silence and signed recoverable
+f32 tiny inputs at every point count from 2 through 17.
+
+## Example construction
+
+Use three native f32 AudioParams named `negative`, `center`, and `positive`, with
+initial values -1,0,1 and bounds [-1,1]. Use native `instantiate(curveShaper,
+{sampleRate, pointCount:3, quality:'adaa'}, {name:'shaper'})`, then pass their
+`.at(i)` values as `ordinates` inside `forSample`.
+Changing the center ordinate makes the curve asymmetric; editing both endpoints
+alters polarity or folds the transfer without replacing the graph. The point
+count remains fixed. This is an example of graph composition, not a custom
+parameter manager or curve-asset loader.
+
+The focused suite has 17 tests. Actual native offline rendering at 44.1,48,96 kHz
+passes the interpolation/quadrature, edit, reset, state, non-finite, tiny-signal,
+and alignment checks above. Two fixed five-point curves, [-1,-1,0,1,1] and
+[-0.5,-0.5,0,1,1], are measured with coherent 8192-frame sines at bins 997 and
+1709, amplitude 3, after one full period of warmup. Projection removes DC and
+only harmonics below Nyquist. The remaining folded RMS decreases by 8.64–9.47 dB
+in ADAA versus direct quality, exceeding the test's fixed 6 dB requirement.
+Fundamental amplitudes are recorded without loudness normalization. These are
+specific fixed-curve fixtures, not guarantees for arbitrary edits or signals.
+
+`tests/curve-shaper-packed.test.mjs` installs the actual package tarball into a
+locked isolated consumer, checks public TypeScript, and renders the minimum and
+maximum point counts in both modes at all three rates. Gain, mix and every
+ordinate are written through native a-rate parameter blocks, including edits
+inside a block. An independent scalar interpolation/segmented Simpson reference
+has maximum f32 error below 6e-8 in this fixture; the fixed limit is 8e-7. Reset and
+exact same-schema continuation are checked in the native offline renderer, whose
+whole output must also exactly match the manually driven public WASM instance.
+
+The maximum 17-point ADAA graph is about 0.79 MB of serialized graph and 78,938
+bytes of WASM. Each test instance retains fixed 65,536-byte WASM memory. Local
+128-frame process timings include cold execution and host jitter, with observed
+maxima above the quantum budget in some runs. These diagnostics are not a browser
+or real-time capacity approval. Host composition and simultaneous instance count
+need their own measurements; a small LUT can cost substantially less than 17
+points. There is no browser worklet or listening approval in this lane.
+
+Oversampling, explicit interpolation/decimation FIRs, integer latency compensation,
+and higher-order AA remain unimplemented. This candidate closes the bounded
+editable-LUT part of catalog §7 only; it does not establish a new oversampling
+quality for existing `/drive` or arbitrary stateful graphs.

package/docs/delay-fx-capture-findings.json

@@ -0,0 +1,134 @@
+{
+  "status": "NUMERICAL_DIAGNOSTIC_NOT_LISTENING_APPROVAL",
+  "sourceCommit": "2ada71cfdb785d8940dae2f655abda180ea7eeaa",
+  "engineWasmSHA256": "25202e821cecfc39de34a7c6e153d89091ff5b29db893856d22861370c21b6f1",
+  "method": "Simultaneous engine-internal fixed-buffer snapshots and downstream ScriptProcessor capture; separate run with internal capture only; separate ten-second native source. No thresholds changed. Recordings compared to independent feedback/biquad reference.",
+  "results": [
+    {
+      "mode": "paired",
+      "externalInput": {
+        "first": 7201,
+        "last": 198559,
+        "span": 191358,
+        "recurrenceMax": 0.09555476785926614,
+        "gaps": [
+          73728,
+          73729,
+          73856,
+          73857,
+          81920,
+          81921,
+          131200,
+          131201,
+          147456,
+          147457
+        ]
+      },
+      "internalInput": {
+        "first": 7201,
+        "last": 199199,
+        "span": 191998,
+        "recurrenceMax": 1.7585315980131466e-07,
+        "gaps": []
+      },
+      "internalOracle": [
+        {
+          "ch": 0,
+          "max": 7.450580596923828e-09,
+          "first": -1
+        },
+        {
+          "ch": 1,
+          "max": 0,
+          "first": -1
+        }
+      ],
+      "externalOracle": [
+        {
+          "ch": 0,
+          "max": 0.0973740704357624,
+          "first": 73728
+        },
+        {
+          "ch": 1,
+          "max": 0.3697686046361923,
+          "first": 73728
+        }
+      ],
+      "alignmentOffset": 0,
+      "externalVsInternal": [
+        {
+          "ch": 0,
+          "max": 0.09630811214447021,
+          "first": 73728
+        },
+        {
+          "ch": 1,
+          "max": 0.05186933092772961,
+          "first": 73728
+        },
+        {
+          "ch": 2,
+          "max": 0.2157386764883995,
+          "first": 73728
+        }
+      ]
+    },
+    {
+      "mode": "internal",
+      "externalInput": {
+        "first": -1,
+        "last": -1,
+        "span": 0,
+        "recurrenceMax": 0,
+        "gaps": []
+      },
+      "internalInput": {
+        "first": 7201,
+        "last": 199199,
+        "span": 191998,
+        "recurrenceMax": 1.7585315980131466e-07,
+        "gaps": []
+      },
+      "internalOracle": [
+        {
+          "ch": 0,
+          "max": 7.450580596923828e-09,
+          "first": -1
+        },
+        {
+          "ch": 1,
+          "max": 0,
+          "first": -1
+        }
+      ]
+    },
+    {
+      "mode": "native",
+      "externalInput": {
+        "first": 7201,
+        "last": 487199,
+        "span": 479998,
+        "recurrenceMax": 1.795446433333625e-07,
+        "gaps": []
+      }
+    }
+  ],
+  "fileSHA256": {
+    "native-external-2.f32le": "c33ce044995ae068c9ec702bf90499a3f0ff0f737415aabef23e324e1487ce2f",
+    "native-external-1.f32le": "c33ce044995ae068c9ec702bf90499a3f0ff0f737415aabef23e324e1487ce2f",
+    "native-external-0.f32le": "c33ce044995ae068c9ec702bf90499a3f0ff0f737415aabef23e324e1487ce2f",
+    "internal-capturedRight.f32le": "da393ab21b1351f79886509730ba257baf90826b3ce3773e66b6b1be26deb2de",
+    "internal-capturedLeft.f32le": "9340b04f14ec1b10cf470ced283be59f421bb29218ffae29e10bb1f07d72b0b2",
+    "internal-capturedInput.f32le": "041f4c9538b9a1871bfef691105315c168287630ab662daab2c3a1d278d91d45",
+    "internal-external-2.f32le": "5647f05ec18958947d32874eeb788fa396a05d0bab7c1b71f112ceb7e9b31eee",
+    "internal-external-1.f32le": "5647f05ec18958947d32874eeb788fa396a05d0bab7c1b71f112ceb7e9b31eee",
+    "internal-external-0.f32le": "5647f05ec18958947d32874eeb788fa396a05d0bab7c1b71f112ceb7e9b31eee",
+    "paired-capturedRight.f32le": "da393ab21b1351f79886509730ba257baf90826b3ce3773e66b6b1be26deb2de",
+    "paired-capturedLeft.f32le": "9340b04f14ec1b10cf470ced283be59f421bb29218ffae29e10bb1f07d72b0b2",
+    "paired-capturedInput.f32le": "041f4c9538b9a1871bfef691105315c168287630ab662daab2c3a1d278d91d45",
+    "paired-external-2.f32le": "f658b8375c49984cf924067a88048d9817a263fe6469612b0169a744e5dff12f",
+    "paired-external-1.f32le": "f93c655f9ba42e80bd9b2bf7db1d5aa83ebcd822219b8f80196fa9fd8929492a",
+    "paired-external-0.f32le": "9d7567d989e6563813433dd71752d6bd680dc754855d88f6bff02a92927e101c"
+  }
+}