reasampler/docs/product/audit-notes/q-w0-t3-env-constants.md

Q-W0 Track 3 — env-coupled-constant domain-modeling audit

Static analysis, 2026-07-28, branch pq-w0-audit. Scope: any value stored in an environment-coupled domain — frames, sample rate, DPI, pixels, tick cadence — that should be stored rate-free / device-free and resolved at the point of use (docs/product/code-organization.md §2c.3 env-coupled bullet; the load-bearing sample_map seconds invariant, documented in src/core/instrument/CLAUDE.md). Findings are domain-modeling calls, not "rescale by rate" patches. The judgment bar applied: a finding requires (a) an env-coupled stored domain AND (b) an environment that can actually change under it. Frame counts computed transiently from seconds at the use site are correct and are not reported.

Waves referenced for disposition: Q-W1..Q-W6 open bank_panel.cpp, main.cpp, actions.cpp, persist.cpp, and relocate the clean pure libs — no downstream wave opens reasampler_processor.cpp / sampler_core.h / reasampler_editor.cpp for logic change, so fix-now findings in those files must be remediated in Q-W0 itself.

---

Findings

T3-01 — master-gain ramp step is a frame-domain constant anchored to 48 kHz

• Location: src/vst/reasampler_processor.cpp:46-51 (kGainRampRate = 1.0f / 960.0f, kGainRampSnap), applied per-sample at :1069-1085 (stereo) and :1114-1126 (mono).
• Stored vs. correct domain: stored as a per-sample linear step — 960 is literally 20 ms × 48 000 Hz, and the comment says so ("960 samples @ 48 kHz ≈ 20 ms"). The intended quantity is a wall-clock ramp time (~20 ms); the correct model is a seconds/ms constant with the per-sample step derived from sampleRate_ at setupProcessing — exactly the pattern the same file already uses two paragraphs away for kPreserveWindowMs (:618-623, :733-735).
• What breaks when the environment shifts: the ramp's wall-clock length halves at 96 kHz (~10 ms) and quarters at 192 kHz (~5 ms); at 44.1 kHz it stretches to ~21.8 ms. The FB1 "no zipper" contract degrades silently as the host rate rises. Not persisted, so no on-disk breakage — but it is a live hardcoded-rate assumption in src/, which Daniel's standing ruling forbids.
• Severity: Med.
• Disposition: fix-now, remediated in Q-W0. Rationale: trivial, isolated, behavior-identical at 48 kHz; no downstream wave opens this file, so deferring means keeping a named violation of the no-hardcoded-rate ruling through the whole reorg. Store kGainRampSeconds = 0.020, derive the step from the live rate where sampleRate_ is set.

T3-02 — takeover-declick decay is a per-frame coefficient (documented deliberate)

• Location: src/vst/sampler_core.h:409-410 (kDeclickDecay = 0.95, kDeclickFloor = 1e-4), applied per output frame in sampler_core.cpp:514-519, :643-645.
• Stored vs. correct domain: a per-output-frame exponential coefficient; the implied wall-clock decay-to-floor is ~4.2 ms at 44.1 kHz and ~1.9 ms at 96 kHz. The strict domain-model form would be a time constant in seconds resolved to a coefficient at engine build.
• What breaks when the environment shifts: the takeover-blend residue fades ~2× faster at 96 kHz. Audibly negligible for a declick micro-ramp — and the in-code comment (sampler_core.h:397-401) already documents this as a deliberate per-frame DSP micro-ramp, "not a stored wall-clock quantity", with the 44.1–96 kHz variance stated and accepted.
• Severity: Low.
• Disposition: document-and-defer. Rationale: the coupling is already an explicit, written, bounded design decision in the code; converting it buys no audible improvement. Triage should ratify the in-code note as the record.

T3-03 — Trigger-fade UI throw ceiling hardcodes 2 s × 44 100 as 88200.0 frames

• Location: src/vst/reasampler_editor.cpp:395 (constexpr double kFadeMaxFrames = 88200.0), used by controlValue/the commit path to normalize the Trigger fade-in/out knobs.
• Stored vs. correct domain: the fade storage domain (int64 SOURCE frames, persisted in the zones payload) is settled and correct — a source-timeline fact, invariant under project- rate change (docs/ARCHIVE.md §S15). The UI ceiling, however, encodes a wall-clock intent ("2-second max fade throw") as a frame count at an assumed 44.1 kHz source. 88200 is a rate-derived literal in src/, brushing the no-hardcoded-rate ruling even though it never touches disk.
• What breaks when the environment shifts: the environment here is the source file's rate: a 96 kHz capture's maximum fade throw is ~0.92 s; a 22.05 kHz file gets 4 s. The knob's full-scale meaning silently varies per loaded sample.
• Severity: Low (UI-only, not persisted, comment flags it as a "build-time residual — one place to retune").
• Disposition: fix-now, remediated in Q-W0. Rationale: small and contained — replace with kFadeMaxSeconds = 2.0 resolved against the loaded source's rate at the two normalize sites (the editor already threads frameCount + rate through the pack/unpack path, envelope_edit.cpp:148); storage domain unchanged. If triage prefers zero UI-feel change, the fallback is document-and-defer with the comment amended to name the 44.1 k assumption.

T3-04 — drop-hint banner duration stored in sync-timer ticks

• Location: src/vst/reasampler_editor.cpp:2920-2923 (dropHintTicks_ = 6), decayed in onSyncTimer (:244-245); field at reasampler_editor.h:457.
• Stored vs. correct domain: a wall-clock intent ("a few seconds of banner") stored as a count of kSyncTimerIntervalMs ticks (6 × 500 ms). Correct model: a duration in ms, ticks derived — or a GetTickCount-style deadline like the bank panel's tooltip already uses.
• What breaks when the environment shifts: retuning the sync cadence (a plausible perf tweak — the 500 ms value is itself a tuning constant) silently changes the banner duration. The comment does state the coupling.
• Severity: Low.
• Disposition: document-and-defer. Rationale: cosmetic, self-documenting at the single site, and the cadence and hint decay live three lines apart; a fix is fine to fold in opportunistically if the file is ever opened, but does not justify a Q-W0 edit on its own.

T3-05 — systemic: no DPI/content-scale support in either UI surface

• Location: systemic. VST3 editor: reasampler_editor.cpp:150-153 (ViewRect(0,0,840,620) default and the size floor at :816), all editor_geometry / knob_deck / curve_popup / envelope_overlay px constants (e.g. the 8 px node min-separation, the 28×28 curve button), cached font sizes in draw_kit. Extension side: the LICE-drawn bank_panel dock and its geometry modules. No implementation of VST3's IPlugViewContentScaleSupport anywhere in src/vst/ (grep: zero hits for content-scale/DPI), no scale factor threaded through the pure geometry modules.
• Stored vs. correct domain: every layout constant is a physical device pixel that silently assumes ~96 DPI. Correct model: logical units × one scale factor resolved at draw time (the pure geometry modules take widths/heights as parameters already, so a scale factor threads through cleanly — the constants are centralized, which is the good news).
• What breaks when the environment shifts: on a 150–200 % Windows display the editor and dock render physically small (or get bitmap-stretched by the host, blurring text); hit targets like the 8 px min node separation shrink below comfortable pointer accuracy. Usability, not correctness — nothing mis-plays and nothing persisted is wrong.
• Severity: Med (usability on modern displays; Windows-only product makes high-DPI common).
• Disposition: document-and-defer. Rationale: a proper UI-scaling pass is a feature wave of its own (scale plumbing through ~15 geometry modules + font cache + both shells), far outside Q-W0's remediation budget; deferral should be recorded as a named future phase, and Q-W1's relocation of the geometry modules should keep the constants centralized so the eventual scale factor lands in one place.

T3-06 — legacy v3 zone-payload lift divides by the current project rate

• Location: src/vst/sample_map.cpp:601-605 (v3 lift inside readZonesPayload), format note at sample_map.h:439-456, :510-513.
• Stored vs. correct domain: the v3 blobs (Daniel's beta projects) stored wall-clock times as frames — the prior incident itself. The lift converts frames → seconds by dividing by the live projectRate threaded in at read time. That is exact only if the project rate today equals the rate in effect when the S15/S16 editor wrote the frames; the write-era rate was never recorded, so a project whose rate changed since lifts skewed times (old/new ratio, e.g. ~8.8 % for 44.1→48 k).
• What breaks when the environment shifts: already broken by construction for rate-changed-since-write projects; a one-time lift residue, after which v5+ re-saves in seconds and the skew is frozen in, silently.
• Severity: Low (legacy-only, beta-project blobs, envelope-time magnitudes; unrecoverable in principle — the missing datum was never written).
• Disposition: document-and-defer. Rationale: no better conversion exists; this is the documented residue of the incident that motivated the seconds invariant. Worth one sentence in the code-quality-audit report so the skew is a recorded known, not a mystery bug later.

T3-07 — SOLA correlation-segment cap of 512 frames (deliberate CPU bound; cross-ref T1)

• Location: src/vst/pitch_shift.cpp:72 (corrFrames_ = max(1, min(dLow_ - 1, 512)); rationale comment at :64-67).
• Stored vs. correct domain: borderline by design. The quantity being bounded is work per splice (multiply-accumulates), which is genuinely frame-domain — a CPU bound should be in frames. The side effect is that the correlation segment's wall-clock span halves at 96 kHz (512 frames ≈ 11.6 ms at 44.1 k, ≈ 5.3 ms at 96 k), raising the lowest frequency the alignment search can lock onto at high rates. All other shifter geometry correctly derives from kPreserveWindowMs resolved at the live rate.
• What breaks when the environment shifts: alignment quality for low-frequency content degrades somewhat at high host rates; no correctness or persistence impact.
• Severity: Low.
• Disposition: document-and-defer, and hand to the T1 DSP audit for the quality call. Rationale: the frame domain is arguably correct for a compute bound; whether 512 is the right number is an algorithm-quality question (T1's territory), not a domain-modeling one.

---

Surfaces checked clean

• sample_map v5+ persistence (the reference implementation): AHDSR + pitch-env times as SECONDS doubles; no rate constant anywhere in the read/write paths (kLegacyV3NominalRate deliberately does not exist); legacy v3 lift takes the rate as a parameter. Clean.
• ComponentState envelope v6–v11 fields: channel mode, assign generation, preview velocity, voice count/mode/trigger, masterGainLinear (dimensionless linear), explicit flag, SampleRefs (paths + root/loop/channels intrinsics), instanceGuid — all rate-free or file-fact domains. Clean.
• Trigger fadeInFrames/fadeOutFrames/startPoint/SampleLoop.start/end persisted as int64 SOURCE frames: deliberate, settled source-timeline facts (docs/ARCHIVE.md §S15; bank_model.h:66-72 documents the loop rationale) — frames of the file are invariant under project-rate change; the file's own rate is stored alongside and resolved at decode. Correct domain, not a finding.
• trigger_seam: frames↔fraction with startFrame threaded both directions; the overlay's fraction domain is expressly rate-invariant. Clean.
• kPreserveWindowMs (50 ms): resolved to frames against the live host rate at both call sites (reasampler_processor.cpp:618-623, :733-735) — the correct pattern, cited here as the model T3-01 should copy.
• pitch_shift internal geometry: ring length, fade, lag band, delay band all derived from the rate-resolved window_; ratio-scaled live fade length. Clean (T3-07 cap noted above).
• Tail system: TailSetting.manualMs persisted in ms; kMaxTailSeconds/kMaxTailMs wall-clock; trim threshold in dB with the linear ratio derived (render_settings.h:59-86); the realtime decay scan resolves frames against the file's own authoritative rate (capture_realtime.cpp:384-408). Clean.
• wav_trim: frame counts are parsed file facts and transient truncate plans. Clean.
• bank_model persisted metadata: source bounds in seconds + PPQ (both stored, each for its consumer); loudness in dB; sampleRate/channelCount are recorded facts about the file, not assumptions; capture tempo + meter stamped at capture time deliberately so the bars.beats read-out is stable under later project meter changes (card_meta). Clean.
• Ext-state wires (banks JSON, view-mode model, owned manifest, assignment_request, rsusage_*): no frame-domain values; the rate field in the assign wire is a recorded fact. Clean.
• Envelope schematic (envelope_overlay/envelope_edit): param-domain px↔seconds scale derived from the live rect (gatePxPerSecond), sample-length-free; editor time-slider ceiling is kEnvTimeMaxSeconds = 2.0 (seconds). Clean (pixel constants themselves fall under the systemic T3-05).
• Timers: bank_panel tooltip delay uses GetTickCount() ms against kTooltipDelayMs = 500 (wall-clock — the pattern T3-04 should copy); editor sync timer is a 500 ms SetTimer interval (ms, not ticks); the new-content detector is an event diff per tick with no wall-clock meaning encoded in tick counts; retireIdleDrain is idleness-driven, not time-driven. Clean.
• peaks / waveform_view / master_gain / velocity_curve / keyboard_strip: bins and columns derived from rects at use; dB↔linear taper and curve math dimensionless; key rects from the passed strip rect. Clean.

Summary

ID	Location	Stored domain	Severity	Disposition
T3-01	reasampler_processor.cpp:46-51 gain-ramp step	per-sample step (20 ms @ 48 k baked in)	Med	Fix-now (Q-W0) — store seconds, derive step from sampleRate_
T3-02	sampler_core.h:409-410 declick decay	per-frame coefficient	Low	Document-and-defer — deliberate, already documented in-code
T3-03	reasampler_editor.cpp:395 fade throw ceiling	88200 source frames (2 s @ 44.1 k)	Low	Fix-now (Q-W0) — seconds ceiling resolved vs. source rate at use
T3-04	reasampler_editor.cpp:2923 drop-hint duration	sync-timer ticks	Low	Document-and-defer — cosmetic, coupling stated in-code
T3-05	systemic (both UI surfaces)	physical px, ~96 DPI assumed; no content-scale	Med	Document-and-defer — a UI-scaling phase of its own; keep geometry constants centralized through Q-W1
T3-06	sample_map.cpp:601-605 v3 legacy lift	frames ÷ current project rate	Low	Document-and-defer — unrecoverable legacy residue; record as known skew
T3-07	pitch_shift.cpp:72 correlation cap	512 frames (CPU bound)	Low	Document-and-defer — frame domain arguably correct for a compute bound; hand to T1 for the quality call

Two fix-now findings (T3-01, T3-03), both assigned to Q-W0 itself — no downstream wave opens those files for logic change. Five deferrals, each with a recorded rationale. The persistence surfaces — the highest-stakes case — are clean: every wall-clock quantity written to disk since the S12 remediation is in seconds or ms, and every frame-domain persisted value is a source-file fact whose rate travels with it.