@denaudio/den 0.0.0-stage → 0.2.0

package/docs/live-buffer.md

@@ -0,0 +1,163 @@
+# Rolling live sample buffer candidate
+
+Status: **CANDIDATE / NOT_CLEARED**. Catalog §3 calls out fixed-capacity live
+history, its age and read/write competition. This module provides that native
+storage/read contract. It adds no microphone/device capture, host transport,
+streaming, overdub, sample loader, grain scheduler, normalization or limiter.
+Audio and builds produced by its tests are not listening-approved goldens.
+
+## Entry and coordinates
+
+Import `liveSampleBuffer`, `LiveSampleBufferConfig`, `LiveSampleBufferControls`,
+`LiveSampleBufferRead`, `LiveSampleBufferStatus` and `LiveSampleBuffer` from
+`@denaudio/den/live-buffer`. Instantiate once in a native processor:
+
+```ts
+const history = instantiate(liveSampleBuffer,
+  { capacity: 65536, sampleRate: ctx.sampleRate }, { name: 'history' });
+// Within forSample, choose the order deliberately:
+const previous = history.readAge(f64(0));
+const status = history.tick({ input, record, reset });
+const current = history.readAge(f64(0));
+```
+
+Capacity is an immutable integer in 1–65,536 mono frames. `sampleRate` is the
+incoming processor rate in [8,000,192,000] Hz, without resampling. At capacity
+65,536, continuous recording retains approximately 1.486 s at 44.1 kHz, 1.365 s
+at 48 kHz or 0.683 s at 96 kHz. Rate conversion, stereo pairing and routing are
+the caller's composition. There is no automatic input-monitor output.
+
+`readAge(ageFrames: Node<'f64'>)` returns `{output,available}`. Ages count
+**accepted writes**, not elapsed processor frames or wall-clock time:
+
+- Age 0 is the newest accepted write at this call's statement position; age 1
+  is the write immediately before it. Fractional age interpolates toward older
+  writes. For history [10,20,30] in chronological order, age .25 returns 27.5.
+- A finite age in inclusive [0,length−1] is available. At an integer age, the
+  exact recorded frame is returned. At the oldest valid integer, the older tap
+  is held at that frame. Capacity one therefore supports only age 0.
+- Negative ages, NaN, infinities, unfilled ages and ages beyond retained history
+  return zero with `available:false`. No endpoint clamping, zero-padded blend,
+  extrapolation or wrap from oldest to newest is applied to unavailable ages.
+- The circular storage address wraps, but the age coordinate does not. An age
+  just above length−1 is unavailable even if stale bytes exist at that address.
+  Fractional reads never interpolate into overwritten or unfilled history.
+- Pausing freezes all ages and bytes. It does not insert silent frames. A fixed
+  age is a moving delay tap while recording, then a frozen sample while paused.
+  After another write, a surviving sample's age increases by one; at capacity,
+  the former oldest sample expires.
+
+This interface intentionally is **not `ResidentSample`**. It has no `load`,
+chronological `read`, or `sourceSampleRate` member, and must not be passed to
+existing `samplePlayer`, `multisamplePlayer` or `granularSource` through a type
+cast. Those readers interpret stable asset positions; rotating chronological
+indexes would silently change an active grain's meaning. Stable captured takes
+remain the separate `residentTakeRecorder` contract. The separate
+[`liveGranularSource`](live-granular.md) reader explicitly tracks accepted-write
+motion and expiry, with writer-before-reader order and a shared reset.
+
+## Writer, ordering and revision
+
+Call `tick({input,record,reset})` exactly once per incoming sample:
+
+- Initially length, head and revision are zero; every read is unavailable.
+- When record is true and reset false, accept one input frame. Before capacity,
+  length grows by one. At capacity, length stays fixed and the oldest frame is
+  overwritten. A false record pauses without modifying exposed history.
+- Reset is level-sensitive and wins over record. It sets head and length to
+  zero and accepts no input. A held reset stays empty. Still-high record resumes
+  on the first non-reset tick, beginning a new history at frame zero.
+- The returned `{written,full,length}` describes the operation's result.
+  `written` includes accepting zero or sanitizing invalid input to zero; `full`
+  becomes true on the write that first fills capacity and remains true through
+  later overwrites or pauses until reset.
+- Native statement order is the visibility boundary. A read before `tick` sees
+  the previous history, including before reset; a read afterward sees the
+  complete write or empty reset. PCM is written before head and length advance.
+  Calling several readers between writes is supported. This is not a concurrent
+  host writer or cross-thread consistency contract.
+- `length()` returns the current retained count. `revision()` is a wrapping i32
+  mutation serial incremented once for each accepted write or reset tick.
+  Pause leaves it unchanged. Reset+record increments once, not twice. Compare
+  revisions for equality/inequality, never numeric ordering; 2^32 mutations can
+  revisit the same value. Revision is neither an absolute timestamp nor a stable
+  frame identity, and no compatibility with resident asset revisions is implied.
+
+Read-before-write age 0 is the last accepted frame, not the current input.
+Read-after-write age 0 is current input when accepted, including at ring wrap.
+This order matters for zero-delay and feedback composition. No implicit delay,
+feedback loop, read/write safety margin or click-free transition is supplied.
+
+## Amplitude, storage and snapshots
+
+All finite f32 input is supported, including values beyond ±1, full f32 extrema
+and subnormals. NaN and ±Infinity are recorded as zero, without depending on the
+output scrubber. Input signed zero records as positive zero. Linear reads use
+f64 intermediate arithmetic, so opposite full-range taps do not overflow their
+difference. Interpolation is not anti-alias filtering; rapid age changes can
+click or alias, and downstream gain or feedback can overflow independently.
+
+Core 0.4.1 scalar stores flush magnitudes below 1e-30. The native persistent
+buffer therefore stores `f64(input) * 2^128`, decoding by the same exact binary
+factor. This is a storage encoding, not signal gain or normalization. Every
+finite nonzero f32 is above the store floor and far below f64 overflow when
+encoded. The transient age cache is likewise scaled by 2^192 to retain tiny
+fractions that can make a representable f32 difference against full-range PCM.
+
+Storage is one fixed C+1 f64 buffer: exactly `8*(C+1)` bytes, or 524,296 bytes at
+capacity 65,536, plus three persistent i32 states (head/length/revision), a
+transient f64 read cache and normal runtime/IO overhead. The extra cell is an
+unreachable sentinel. Paused/reset ticks write zero only there because native
+`select` evaluates both branches. Processing allocates no growing history or
+new per-sample buffers; writes and each read use fixed bounded work.
+
+Reset is **logical invalidation, not secure erasure**. Old history remains in
+snapshot bytes until overwritten but cannot be read through `readAge`. Snapshot
+state includes the buffer, head, length and revision; the read cache is excluded.
+Exact continuation applies only to the same graph, configuration and sample
+rate with the same subsequent input/control sequence. No new serializer or
+cross-configuration migration is provided. Core 0.4.1 live state restore and
+host AudioParam restore are not atomic; this module does not fix that boundary.
+Establish safe host controls before restoring a live writing graph. Offline
+continuation evidence is distinct from an arbitrary live-control restore claim.
+
+## Verification and limits
+
+`tests/live-buffer.spec.ts` compares all pre/post-read, availability and writer
+status samples to an independent chronological-array reference at 44.1/48/96
+kHz. It covers capacity one/two/17, every physical wrap position, fractional ages
+adjacent to newest/oldest retained samples, invalid/unfilled/expired reads,
+pause, held reset, tiny/full-range PCM, tiny f64 ages, revision wrap, snapshots
+while partial/full/paused/reset, stale-byte exclusion, and maximum fixed storage.
+The reference does not use a circular buffer or production addressing helpers.
+
+`tests/live-buffer-packed.test.mjs` installs the actual tarball into a locked
+isolated consumer, checks the public types, renders all-sample references and
+same-schema continuation at three rates, then builds actual Vite worklet/WASM
+assets. Its 65,536-frame memory diagnostic actively records through two wraps,
+checks the oldest-age output and confirms constant native memory. Source,
+tarball, lock, audio and build hashes are retained with failure phases.
+
+These are bounded offline/build checks, not browser execution, device capture,
+real-time deadline or listening approval. There is no streaming, long-form
+recording, live granular playback, overdub or fixed-latency host integration
+claim. Audio candidates preserve raw gain; no normalization or limiter masks
+their output.
+
+## Small actual-browser composition
+
+The separate `tests/live-buffer-browser.test.mjs` requires an actual 48 kHz
+worklet. A native fixture counter gates exactly 3, then 20, accepted writes into
+capacity 8, independently of host timer delays. This counter is test composition,
+not a capacity stop in the rolling-buffer API. An exact binary ramp exposes both
+wraps, every retained sample, fractional/expired reads, pause and reset/resume.
+Native accumulated pre/post-read sums verify statement order during the brief
+writing intervals rather than inspecting only a later silent/paused window.
+
+For in-place state restoration, the fixture saves a full wrapped positive
+history and replaces it with a short negative one. It first renders recording
+off, then renders all saved controls and proves the negative mutation remains.
+Restore must recover the original PCM, length, cursor-dependent continuation,
+revision and accumulated sums; every retained age is read back. No microphone,
+host transport, arbitrary live-control atomicity or hardware continuity claim
+is involved. Three-rate native chronological references precede browser execution.

package/docs/live-granular.md

@@ -0,0 +1,179 @@
+# Live history granular reader candidate
+
+Status: **CANDIDATE / NOT_CLEARED**. This bounded catalog §3 reader consumes the
+native rolling history from `@denaudio/den/live-buffer`. It supplies a fixed grain
+pool and windows, without an input device, loader, density scheduler, random
+jitter, host transport or streaming contract. Existing resident sample readers
+remain separate; do not cast rolling history to `ResidentSample`.
+
+## Public composition and statement order
+
+Import `liveGranularSource`, `LiveGranularConfig`, `LiveGranularControls`,
+`LiveGranularResult` and `LiveGranularSource` from `@denaudio/den/live-granular`.
+Construction accepts `{history: LiveSampleBuffer, maxGrains: number}`. `maxGrains`
+is an integer in 1–8; the history has fixed capacity 1–65,536 and a finite processor
+sample rate in [8,000,192,000] Hz. The reader adds no PCM buffer. Instantiate once:
+
+```ts
+const history = instantiate(liveSampleBuffer,
+  { capacity: 65536, sampleRate: ctx.sampleRate }, { name: 'history' });
+const grains = instantiate(liveGranularSource,
+  { history, maxGrains: 8 }, { name: 'grains' });
+// Within every stride-1 forSample iteration:
+const status = history.tick({ input, record, reset });
+const result = grains.tick({
+  written: status.written, reset, trigger,
+  ageFrames, rate, durationSeconds,
+});
+output.write(result.output);
+```
+
+Call the writer exactly once, then each reader exactly once per sample. Pass the
+writer's actual `status.written` and the **same reset signal**. Several readers can
+share that result; no intervening write/reset is allowed. `record` is not a
+substitute for `written`: reset suppresses a write, while an accepted invalid
+input still writes sanitized zero. The history sample rate must match the
+processor. No source-rate conversion is performed. Skipping calls, mismatching
+reset, or supplying a fabricated write status is unsupported.
+
+## Launch controls and pool policy
+
+`trigger` is level sensitive: each true non-reset sample requests one new grain.
+A held trigger requests every sample. No gate, automatic onset, density clock or
+queue is implied. The following f32 controls are latched only on successful launch:
+
+- `ageFrames`: finite accepted-write age in [0,capacity−1], also currently within
+  [0,history.length()−1]. Zero means the newest frame after this sample's write.
+- `rate`: finite signed history frames per output sample in [−16,16]. Positive
+  moves toward newer source material; negative moves toward older material.
+- `durationSeconds`: finite [0,2]. Duration is
+  `clamp(floor(durationSeconds * history.sampleRate + .5),3,round(2*sampleRate))`
+  output samples. Zero is valid and produces a three-frame grain; negative,
+  NaN and infinite values are rejected.
+
+Invalid controls or an unavailable onset set `rejected:true`. They do not clamp
+to a source endpoint, steal a slot, or alter current grains. Internal eager
+branches use safe operands before integer conversion, including on rejected
+NaN/infinite requests. Valid requests use the first free slot in stable index
+order. A full pool sets `dropped:true`; no stealing, restart or delayed retry
+occurs. `launched` means allocation succeeded. `dropped` and `rejected` are mutually
+exclusive; all three are false without a request or during reset.
+
+An existing unavailable grain is terminated before allocation, so its slot is
+available for a new grain on that same sample. Changing age/rate/duration while a
+grain runs only affects later requests. There is no implicit output gain control.
+
+## Accepted writes, movement and expiry
+
+Let `a[n]` be a grain's read age at processor sample n. At launch it is exactly
+`ageFrames`, measured **after the current write**, without adding that write again.
+For a surviving grain on the next sample:
+
+```
+a[n+1] = a[n] + ((written[n+1] ? 1 : 0) - latchedRate)
+```
+
+The increment is formed before addition. Continuous writing at rate 1 therefore
+preserves even a tiny representable onset fraction; computing `(tinyAge+1)-1`
+would lose it. At rate 0, the grain stays at the same source identity, whose age
+increases with accepted writes until overwritten. Under continuous writing, rate
+1 holds a fixed delay age. Pausing freezes history, **not** the grain clock or
+source movement: a positive-rate grain moves toward the newest retained edge and
+may expire. Resuming recording cannot revive a terminated grain.
+
+Every read must be in the inclusive interval [0,currentLength−1]. The shared
+reader interpolates toward older frames and holds the oldest valid integer tap.
+There is no implicit newest/oldest safety margin, extrapolation, zero-padded blend
+or wrap of the age coordinate. An out-of-range read immediately terminates that
+grain and increments `expiredGrains`; it does not clamp or resume later. A valid
+launch at age 0 while paused, with positive rate, can have only its silent onset
+and expire next sample. A valid launch does not promise a full audible window.
+
+Natural completion wins on the sample after the final window endpoint: a grain
+whose duration ended is already inactive and is not reported as expired. Reset
+has highest priority, immediately silences and clears all grain state, and zeros
+all result flags/counts. It must also reset the shared writer. A held reset keeps
+the graph empty; a still-high trigger requests again on the first non-reset sample.
+
+## Windows, gain and finite precision
+
+A grain of N output samples has indices k=0…N−1 and triangular weight
+`max(0,1-abs(2*k/(N-1)-1))`. Both endpoints are exactly zero. Odd lengths reach 1;
+even lengths have a smaller peak. `activeGrains` counts valid reads on the current
+sample, including the zero-weight endpoints and successful launches.
+
+Each linearly interpolated f32 history read is weighted and summed in f64. The sum
+is divided by **fixed maxGrains**, then converted once to f32. This is fixed pool
+headroom, not active-count normalization, content normalization or a limiter. A
+single grain in an eight-slot pool is attenuated by eight. Magnitude stays within
+the largest active read magnitude, subject to rounding. Finite PCM above unity,
+f32 extrema and subnormals remain supported; the writer sanitizes NaN/infinite
+input to zero. No clipping masks the candidate audio.
+
+Cursor and latched-rate stores use exact binary scaling by 2^192 to avoid core
+0.4.1's 1e−30 scalar-store floor. The scale is storage encoding, not gain. It does
+not increase f64 precision: movement smaller than a large cursor's representable
+spacing may round away. Linear interpolation is not anti-alias filtering. Window
+cancellation, read-edge expiry, pauses and reset can change sound or truncate
+transients. This is not pitch-perfect, time-transparent or streaming-continuity
+processing, and there is no real-time/device/listening clearance.
+
+## State and verification
+
+Each slot has five persistent scalars: active bool, window index i32, duration
+i32, scaled read age f64 and scaled rate f64. The first-free allocation cache is
+transient. The history retains its own fixed buffer/head/length/revision and
+transient read cache. Work and storage are bounded by capacity and maxGrains;
+processing creates no growing history or per-sample buffers.
+
+Snapshots must include the writer **and every reader sharing it** together.
+Continuation is exact only for the same graph/configuration/sample rate and
+identical subsequent inputs/controls. Partial-graph restore is unsupported.
+Native live-state restore and AudioParam restore are non-atomic; establish safe
+host controls before restoring. The writer's reset is logical invalidation, not
+secure PCM erasure. These constraints are unchanged by this reader.
+
+`tests/live-granular.spec.ts` uses an independent chronological array plus
+absolute rational source positions. It avoids both the ring addressing and the
+production age recurrence; exact rational positions retain tiny fractions while
+accepted-write and playback movements cancel. Evidence covers 44.1/48/96 kHz,
+variable accepted writes, paused/resumed recording, first-free saturation,
+same-sample expiry/relaunch, zero endpoint counts, natural completion, latching,
+invalid eager operands, wrap/read margins, full finite/tiny PCM, snapshots,
+capacity one and maximum capacity with eight slots. The maximum fixture remains
+active across ring wrap and records through two wraps.
+
+`tests/live-granular-packed.test.mjs` packages the actual public subpath, installs
+an isolated consumer with pinned core 0.4.1, checks public types, renders the
+independent three-rate reference and same-schema continuation, and builds actual
+Vite worklet/WASM assets. Source/tarball/lock/audio/build hashes and failure phases
+are retained. The runner defaults to a fresh `npm ci` consumer. An explicitly
+approved local-only `DEN_LIVE_GRANULAR_REUSE_LOCKED_CONSUMER` path instead links
+unchanged matching locked dependencies and extracts only den from the real new
+tarball; it rejects this mode in CI, archives and verifies the original package,
+tarball and lock, and records reuse honestly in provenance. These are offline/build candidates, not human-approved goldens or
+browser/device/real-time evidence. A separately verified browser composition may
+add bounded browser evidence without changing that limit.
+
+## Small actual-browser composition
+
+`tests/live-granular-browser.test.mjs` uses a muted 48 kHz graph with one grain
+and a 64-frame history. Native counters bound the writer and a three-sample
+request burst, so a delayed host callback cannot change the expected fill or
+drop counts. A paused original ramp supplies a known constant source identity.
+Every observed output sample is compared to its independent triangle-window
+value using a native frame/launch counter, rather than fitting output RMS.
+Changing onset controls while that grain runs must preserve its latched motion
+and duration.
+
+The fixture saves a noninitial positive grain, clears the shared graph, and
+creates a different negative history/grain. It renders recording and triggering
+off with every saved control before restoring the entire graph; the negative
+mutation must still be audible in the muted observation path until restore.
+The recovered positive history and window phase must match the sample oracle.
+Resumed writes then overwrite the original source identity and must permanently
+expire the grain. Empty-history rejection and held reset remain separate checks.
+An independent chronological/source-identity oracle exercises the composition
+at three rates before the actual browser gate. This is bounded native behavior,
+not device capture, scheduling infrastructure, runtime clearance or an acoustic
+listening judgment.

package/docs/lookahead-multiband.md

@@ -0,0 +1,183 @@
+# Lookahead limiter and three-band dynamics candidates
+
+Status: **CANDIDATE**. These additive modules extend catalog section 9 with a
+bounded sample-peak lookahead limiter and a phase-compensated three-band
+composition. They reuse unworklet 0.4.1 and the existing reviewed peak follower,
+LR4 crossover and dynamics. Generated audio is not a golden or human-approved
+sound. Offline correctness is not browser or hardware real-time clearance.
+
+## Measured real-time boundary
+
+The first clean packed proof (`a2f2b0e`, 2026-10-05) measured the full
+17-output three-band fixture at 44.1/48/96 kHz. It exceeded the local 128-frame
+quantum budget in **28/512, 66/512 and 221/512 blocks**, respectively. P99 times
+were 4.59/5.01/4.40 ms. At 96 kHz its median was 1.277 ms against a 1.333 ms
+quantum. **This multiband graph is not real-time cleared.** The maximum-2048-sample
+limiter had no budget exceedances in the same local diagnostic, which also does
+not establish browser or device clearance.
+
+These are local Node-driver wall times after 128 warm-up blocks, repeating the
+first 128-frame input/control block, excluding audio I/O copies and browser
+scheduling. They are useful negative evidence, not a universal capacity limit or
+an acceptance benchmark. Stage materialization reduced the separate mixed-mode
+comparison fixture from 6,752,682 to 153,584 WASM bytes while preserving all
+17 output channels byte-for-byte at three rates. That compile-size improvement
+does not remove the measured runtime boundary.
+
+## Entry contracts
+
+- `@denaudio/den/lookahead-limiter`: `lookaheadLimiter`,
+  `LookaheadLimiterConfig`, `LookaheadLimiterControls`.
+- `@denaudio/den/multiband-dynamics`: `multibandDynamics`,
+  `MultibandDynamicsConfig`, `MultibandDynamicsControls`,
+  `MultibandDynamicsBandConfig`, `MultibandDynamicsBandControls`.
+
+Instantiate with stable unique names and call each instance exactly once per
+sample. `sampleRate` is an integer from 8000 through 192000 Hz and must equal the
+enclosing processor's compile rate. All runtime numeric inputs are native f32
+Nodes and reset is a native boolean Node. There is no alternate runtime,
+parameter, snapshot or routing framework. State restoration requires the same
+schema, construction configuration and rate.
+
+## Limiter: exact window and fixed latency
+
+Configuration is `{sampleRate, lookaheadSamples}`. The delay is a required integer
+in **0..2048**; it cannot be changed at runtime. Latency is exactly that many
+samples, exposed as construction-time `latencySamples` and `latencySeconds`.
+The capacity is a resource boundary, not a claim that every setting is real-time
+safe. At 44.1/48/96 kHz, the maximum is about 46.44/42.67/21.33 milliseconds.
+
+`tick(left, right, {ceilingDb, release, reset})` returns limited `left`/`right`,
+latency-matched `dryLeft`/`dryRight`, and `windowPeak`, `envelope`, `gain` and
+`ceiling` diagnostics. There is no implicit makeup, mix or bypass. Dry mixing or
+another processor after the limiter can violate the ceiling.
+
+Let N be the delay and p[n] be the larger absolute current L/R input. On sample n,
+the detector target is the **inclusive maximum of p[n-N] through p[n]**, bounded
+by the latest reset. The output program sample is input[n-N]. Processing order:
+
+1. If reset, invalidate all preceding audio and detector history.
+2. Insert current L/R and their peak in the ring and max tree.
+3. Recompute the tree path and obtain the inclusive window maximum.
+4. Update the existing peak follower with zero attack and requested release.
+5. Apply the current ceiling/envelope ratio to the N-sample-old program.
+6. Advance the ring cursor.
+
+Attack is immediate. Lookahead conservatively attenuates audio up to N samples
+before a transient emerges; it does not interpolate a gain ramp. The follower
+release is the reviewed one-pole amplitude detector recurrence, not linear-gain
+or dB-gain release: `c=1-exp(-1/max(1,release*sampleRate))` for positive release,
+otherwise c=1. The envelope never falls below the current window maximum.
+Release is clamped to 0..30 seconds, with nonfinite values falling back to zero.
+Abrupt ceiling/release edits can cause discontinuities and pumping is possible.
+
+`ceilingDb` is clamped to -120..0 dBFS, with nonfinite values falling back to zero.
+Its f32 exponential amplitude is returned as `ceiling`. The exact discrete
+contract is `abs(output[channel][n]) <= ceiling[n]`, not an infinite-precision dB
+identity. A downward ceiling edit constrains **the output sample at that moment**,
+including previously buffered audio; ceilings are not delayed with the program.
+The gain is `min(1,ceiling/envelope)`, or one for a zero envelope. Multiplication
+stays binary64 until final output conversion, so maximum finite f32 audio at a
+-120 dB ceiling is not multiplied by a quantized subnormal f32 gain. Returned
+`gain` is a rounded f32 diagnostic; it may underflow or have poor relative
+precision at extreme inputs and must not substitute for the actual audio path.
+The final output clamp guards floating-point ceiling rounding.
+
+All finite f32 program inputs, including subnormals and above-full-scale values,
+are preserved on the dry path. As in native unworklet state, negative zero is
+normalized to positive zero. Nonfinite program samples become zero. This
+limiter measures samples, not intersample reconstruction peaks. It performs no
+oversampling, true-peak estimation or certification.
+
+### Reset and memory
+
+Reset invalidates history before the current input. An N>0 limiter then emits N
+silent samples while filling; N=0 processes the current sample immediately with
+fresh detector history. Holding reset high thus keeps N>0 output silent, whereas
+N=0 continues limiting each current sample independently. Reset is not a
+click-free bypass operation. Dry and wet always share the same delay/reset rule.
+
+There are N+1 stereo ring positions and a power-of-two max tree. Every sample
+updates only one leaf and `ceil(log2(N+1))` ancestors. No data-dependent search,
+allocation, epoch counter or reset-time full-buffer scan occurs. At maximum N,
+three binary64 buffers occupy 98,320 bytes plus a fixed small scalar history.
+All audio/peak buffer values use exact power-of-two scaling, preserving f32
+subnormals through unworklet's less-than-1e-30 state-write flush.
+
+The reset-validity invariant is an initially empty prefix of leaves. During
+sequential refill, an included sibling subtree starts before the valid-prefix
+end and has already been rebuilt since reset; a sibling starting at or beyond
+that end is read as zero. The prefix expands by one leaf per sample. After full
+refill, all real leaves remain valid through wraps, while padding leaves are
+always excluded. This also holds at N=0, non-power-of-two window lengths,
+first wrap, repeated resets and repeated wraps. No stale pre-reset peak can
+reappear. Rings, tree, cursor, prefix count and follower state are persistent in
+native snapshots.
+
+## Three-band phase-compensated dynamics
+
+Configuration is `{sampleRate, bands:[lowConfig,midConfig,highConfig]}`. Each band
+configuration has the existing `DynamicsConfig` mode, operation and optional
+hysteresis, excluding sampleRate. Controls are `{lowCutoffHz,highCutoffHz,bands,
+reset}`; each of the three control records is `DynamicsControls` without reset.
+Each band uses its own filtered L/R program as a max-absolute linked stereo
+sidechain. There is no external sidechain or lookahead in this composition.
+
+Finite audio is passed without input clipping; nonfinite samples become zero.
+The **caller headroom precondition for the tested boundary is |L|,|R| <=16**.
+This is not an arbitrary-full-f32-input guarantee. Recombination and transients
+can exceed input or full-scale peaks even when all dynamics gains are at most
+one. This processor has no output ceiling. Apply the separate limiter afterward
+if a discrete sample ceiling is needed.
+
+Cutoffs use finite fallbacks of 200 and 2000 Hz respectively, clamp individually
+to `[20,min(20000,0.45*sampleRate)]`, then sort ascending. Reversed controls are
+therefore equivalent to sorted controls. Equal cutoffs are permitted; the middle
+branch does not vanish merely because the cutoffs coincide. Each edit takes
+effect on the current sample without clearing filter or dynamics history.
+
+At fixed cutoffs, writing Lf/Hf for the existing LR4 low/high transfers and
+Af=Lf+Hf for their positive-polarity allpass sum, the bands are:
+
+- Low: `Llow * Ahigh` (the extra high-crossover sum compensates its phase).
+- Middle: `Hlow * Lhigh`.
+- High: `Hlow * Hhigh`.
+
+At unity dynamics gains, the complete transfer is **Alow * Ahigh**, of unit
+magnitude with frequency-dependent phase. The low-band compensation is essential;
+naively splitting only the high branch a second time does not reconstruct this
+transfer. No explicit integer sample delay is added, but IIR phase/group delay
+is frequency dependent. This is not identity PCM or a linear-phase crossover.
+Static transfer guarantees do not imply flat magnitude under moving cutoffs.
+
+The results contain `left`, `right`, phase-matched `dryLeft`/`dryRight`, three
+existing dynamics result records `low`/`mid`/`high`, and effective sorted cutoff
+Nodes. The dry outputs are the unprocessed **allpass recombination**, not original
+PCM. Dry/wet mixing can use this phase-matched reference, but dynamically unequal
+band gains still change phase and magnitude. No implicit output normalization is
+performed. All six crossover instances and three dynamics instances reset before
+the current sample; their native state is independent and snapshot-persistent. Two fixed five-element
+scaled binary64 scratch buffers materialize existing f32 crossover stage
+boundaries once instead of re-expanding them at each consumer. They add 80 bytes
+and are transient: every element is overwritten before use on each sample, so
+they need no saved history. Exact scaling preserves nonzero f32 values and the
+original stage rounding; native signed-zero normalization still applies.
+
+## Verification scope
+
+The focused tests use an independent naive timeline maximum for the limiter,
+independent exponential recurrence for its detector, RBJ direct-form-I filter
+references for static bands, and complex transfer products for recombination,
+including DC. They cover 44.1/48/96 kHz, capacity endpoints, first-fill and repeated
+wraps, reset and held reset, current-output ceiling automation, malformed inputs,
+full-range and subnormal limiter audio, per-band gain controls, cutoff sorting
+and equality, same-schema snapshot continuation, finite caller headroom and zero
+scrub diagnostics. A maximum-capacity compile/memory check is bounded evidence,
+not a deadline assertion.
+
+The isolated consumer installs the actual packed public exports, strict-checks
+TypeScript and renders the same candidate surface with independent numerical
+assertions. Its manifests record exact source/package hashes, rates, controls,
+raw candidate audio and native diagnostics. Browser, external-device and
+maximum-capacity real-time support are not established by offline evidence.
+Independent review and exact-head aggregate CI remain required before merge.

package/docs/loop-crossfade.md

@@ -0,0 +1,99 @@
+# Crossfaded resident loop candidate
+
+Status: **CANDIDATE**. This additive reader uses the existing resident PCM ingress,
+native state and linear interpolation. It does not change `samplePlayer`.
+No listening approval, seamless arbitrary-content claim, antialiasing, streaming,
+loader, time-stretching or browser/realtime deadline proof is implied.
+
+## Entry and effective period
+
+Import `crossfadedLoopPlayer` and `CrossfadedLoopConfig` from
+`@denaudio/den/loop-crossfade`; import `residentSample` and the shared
+`SamplePlayerControls` from `@denaudio/den/sample`.
+
+Construction accepts `{ sampleRate, sample, startFrame = 0,
+endFrame = sample.capacity, crossfadeFrames, releaseFrames = 0 }`.
+The fixed slice is `[startFrame,endFrame)`; `crossfadeFrames` is an integer in
+`[0,floor((endFrame-startFrame)/2)]`. Zero explicitly disables the overlap.
+Resident and host rates follow the existing [8,000,192,000] Hz contract.
+`releaseFrames` is an integer in `[0,ceil(sampleRate*10)]` output samples.
+
+For the currently loaded asset define:
+
+- `S = startFrame`, `E = min(endFrame, sample.length())`, `L = max(0,E-S)`
+- `F = min(crossfadeFrames,floor(L/2))`
+- `P = L-F`, the **effective loop period in source frames**
+
+The playback phase `q` traverses `[0,P)`. The primary read position is
+`x = S+F+q`. In the last `F` source frames of that cycle (`q >= P-F`),
+read the tail at `x`, read the head at `S+q-(P-F)`, and linearly blend
+`(1-w)*tail + w*head`, where `w = (q-(P-F))/F`. Outside the overlap,
+read only the primary position. Overlap taps use nonwrapping resident linear
+interpolation, which holds the last endpoint between `E-1` and `E`.
+At the phase seam the head approaches `S+F`, the next primary start.
+When `F=0`, use ordinary wrapping linear interpolation over the whole slice.
+
+This makes the repeated cycle `L-F` source frames long, rather than `L`.
+For fixed nonzero rate, the cycle lasts `P / abs(rate*sourceRate/hostRate)`
+output frames (not necessarily an integer). At unit rate with equal rates,
+an eight-frame slice with two overlap frames repeats every six samples.
+The first `F` source frames appear only as the incoming overlap head;
+forward triggering starts at `S+F`, not at the asset attack at `S`.
+Do not use this reader when an unchanged loop duration or dry attack is required.
+
+The law is unity-sum linear, not equal-power. It bounds the output peak by the
+largest finite source tap before release gain. Correlated equal signals do not
+receive a +3 dB bump. Different phases can cancel or comb; mismatched transients
+can soften, repeat or smear. Even though the continuous interpolated overlap
+meets at its endpoints, one-sample overlaps or large playback increments can
+still produce large adjacent output steps. This is not a universal click-remover.
+
+## Timeline, controls and lifecycle
+
+`tick({ gate, trigger, reset, rate })` returns
+`{ output, active, position, phase, periodFrames, crossfadeFrames, missing }`.
+`phase` and `position` describe the current sample before advancement.
+`periodFrames` and returned `crossfadeFrames` report effective `P` and `F`.
+
+- `rate` is signed, clamped to [-16,16], with NaN treated as zero and infinities
+  saturated. Advance by `rate * sample.sourceSampleRate / sampleRate`.
+  Zero holds the current phase. A change in direction changes only advancement.
+- Gate-rise, or a true trigger while gate is high, starts/restarts. Forward/zero
+  starts at `q=0`; negative starts at `q=P-1` (primary position `E-1`). Reverse
+  traverses the **same blended periodic waveform backwards**, including its
+  overlap. It does not choose a different, direction-dependent fade waveform.
+  Holding trigger repeats that initial sample.
+- Reset wins over trigger/gate, is silent, and resets phase to zero and gate
+  memory to low. Releasing reset with gate still high starts again.
+- Gate-off release matches `samplePlayer`: the first off sample subtracts
+  `1/releaseFrames`; zero or one stops immediately. Release never exceeds one.
+  `active` describes the current emitted sample, even when the PCM value is zero.
+  Inactive playback freezes its phase; inactive output is zero.
+- Each resident load, including an empty or identical replacement, invalidates
+  playback and resets its phase. Held gate does not restart the new asset.
+  A fresh gate-rise/trigger on that tick can start the newly loaded data.
+- A shorter replacement clips both heads and reduces `F` and `P`. One available
+  frame gives `F=0`, `P=1` and a constant sample. Empty slice gives missing true,
+  silence, and both reported lengths zero. No stale PCM tail is read.
+- `position` is the primary source position, not a unique representation of both
+  blended taps. While missing it reports `S`; phase is zero.
+
+Use at most one `tick` per player instance per output sample; different named
+players can share one resident and their returned values may be consumed after
+other shared-resident reads. All playing state and resident PCM remain native
+snapshot state. Source interpolation splits local integer/fractional coordinates before adding
+slice/head offsets, preserving meaningful tiny-phase contributions against large
+finite PCM. Phase accumulation uses f64 arithmetic; increments below the f64
+resolution at the current phase can still be lost. Public phase/position
+diagnostics are f32 and are not a higher-precision transport.
+Same-graph/configuration/metadata/rate snapshots resume exactly;
+there is no serializer, asset migration or cross-rate snapshot contract.
+See [resident ingress and replacement constraints](sample.md) before loading.
+
+## Verification
+
+Focused and isolated packed-package checks cover independent scalar timelines,
+source/host conversion at 44.1/48/96 kHz, forward/reverse/fractional and large rates,
+overlap endpoints, short and missing slices, headroom/cancellation/transients,
+reset/release/retrigger, replacement, deferred shared reads and exact snapshots.
+Generated WAV files are CANDIDATE evidence, never approved goldens.