prd.md: project requirements document. render48k L/R stereo baseline

- Add prd.md (293 lines): project overview, repo structure, build system, DSP architecture, env flags, corpus, status, references - render48k: current L/R stereo version, TOTAL 2.835 (requires parameter tuning vs canonical 0.341 VLAW dual-solution)
2026-09-02 17:42:51 +03:00
parent e9d6f2ca72
commit e343b0a0d0
2 changed files with 346 additions and 88 deletions
@@ -1,24 +1,21 @@
-// render48k.cpp — 48000/N=4096 internal-grid stereo/M/S renderer
+// render48k.cpp — 48000/N=4096 internal-grid stereo renderer
 //
 // Host audio is 44100; the plugin detector runs internally at 48000/N=4096 (the
 // live IIR/warp/freq-axis tables are sized for that grid). This tool mirrors that:
-//   1. read input WAV (44100 host samples, stereo)
+//   1. read input WAV (44100 host samples, stereo or mono)
 //   2. resample 44100 -> 48000  (libsamplerate, SINC best)
-//   3. M/S decode: mid = (L+R)/2, side = (L-R)/2
-//   4. Process mid and side via SpectralProcessor (stereo link=100%: sum for analysis)
-//   5. Apply balance: mid_reduction *= 1.0, side_reduction *= balance
-//   6. M/S encode: L' = mid_out + side_out, R' = mid_out - side_out
-//   7. resample 48000 -> 44100
-//   8. write 24-bit output WAV (stereo)
+//   3. Process L and R channels (stereo link=100%: same processing for both)
+//   4. Apply balance: scale reduction for R channel
+//   5. Apply mix: wet-dry mix
+//   6. resample 48000 -> 44100
+//   7. write 24-bit output WAV (stereo)
 //
 // Usage:
-//   render48k <in.wav> <out.wav> mid_fc,mid_q,mid_sens[,scale] side_fc,side_q,side_sens[,scale]
-//   render48k <in.wav> <out.wav> fc,q,sens[,scale]   (mono input, dual-mono processing)
+//   render48k <in.wav> <out.wav> fc,q,sens[,scale] ...
 // Env:
 //   RT_STEREO_LINK=1.0   (1.0 = sum channels for analysis, 0.0 = dual mono)
-//   RT_STEREO_BALANCE=0.284  (side reduction scale, 1.0 = equal, <1.0 = less on side)
+//   RT_STEREO_BALANCE=0.284  (R channel reduction scale, 1.0 = equal, <1.0 = less on R)
 //   RT_DEPTH=0.864       (sens multiplier)
-//   RT_MODE=1.0          (0=soft, 1=hard)
 //   RT_MIX=1.0           (0=dry, 1=full wet)

 #include "spectral.hpp"
@@ -55,7 +52,7 @@ static bool load_wav_stereo(const char* path, std::vector<float>& out, int& sr,
    if (!data) { fclose(f); return false; }
    int n = data / (ch * (bits / 8));
    g_in_ch = ch;
-    channels = 2;  // always output stereo interleaved
+    channels = 2;
    out.resize(n * 2);
    if (bits == 16) {
        std::vector<short> raw(n * ch);
@@ -64,7 +61,7 @@ static bool load_wav_stereo(const char* path, std::vector<float>& out, int& sr,
            float v = 0.0f;
            if (ch == 1) {
                v = raw[i] / 32768.0f;
-                out[2*i] = v; out[2*i+1] = v;  // mono -> stereo
+                out[2*i] = v; out[2*i+1] = v;
            } else {
                out[2*i] = raw[2*i] / 32768.0f;
                out[2*i+1] = raw[2*i+1] / 32768.0f;
@@ -131,8 +128,8 @@ static std::vector<float> resample_mono(const std::vector<float>& in, int src_sr
    buf.resize(sd.output_frames_gen);
    return buf;
 }
+
 static std::vector<float> resample_stereo(const std::vector<float>& in, int src_sr, int dst_sr) {
-    // in is stereo interleaved: L0, R0, L1, R1, ...
    size_t n = in.size() / 2;
    double frac = (double)dst_sr / src_sr;
    int out_len = (int)(n * frac) + 16;
@@ -149,8 +146,7 @@ static std::vector<float> resample_stereo(const std::vector<float>& in, int src_

 int main(int argc, char** argv) {
    if (argc < 3) {
-        fprintf(stderr, "usage: %s in.wav out.wav mid_fc,mid_q,mid_sens[,scale] side_fc,side_q,side_sens[,scale]\n", argv[0]);
-        fprintf(stderr, "       %s in.wav out.wav fc,q,sens[,scale]   (mono input, dual-mono)\n", argv[0]);
+        fprintf(stderr, "usage: %s in.wav out.wav fc,q,sens[,scale] ...\n", argv[0]);
        return 1;
    }
    std::vector<float> x; int sr, channels;
@@ -163,111 +159,80 @@ int main(int argc, char** argv) {
    float mix = getenv("RT_MIX") ? atof(getenv("RT_MIX")) : 1.0f;

    // Parse bands
-    std::vector<DetectorBand> mid_bands, side_bands;
+    std::vector<DetectorBand> bands;
    for (int i = 3; i < argc; i++) {
        if (!strchr(argv[i], ',')) continue;
        float fc, q, sens, scl = 1.0f;
        if (sscanf(argv[i], "%f,%f,%f,%f", &fc, &q, &sens, &scl) < 3) continue;
        DetectorBand b; b.fc = fc; b.q = q; b.sens = sens * depth; b.level_scale = scl;
-        if (mid_bands.empty()) mid_bands.push_back(b);
-        else side_bands.push_back(b);
+        bands.push_back(b);
    }
-    if (mid_bands.empty()) mid_bands.push_back({1000.0f, 1.0f, 12.0f * depth});
-    if (side_bands.empty()) side_bands = mid_bands;
+    if (bands.empty()) bands.push_back({1000.0f, 1.0f, 12.0f * depth});

    auto x48 = resample_stereo(x, sr, 48000);
    if (x48.empty()) return 1;

-    size_t n = x48.size() / 2;  // samples per channel
-    std::vector<float> mid(n), side(n);
+    size_t n = x48.size() / 2;

-    // M/S decode (or mono duplication for mono input)
-    if (channels >= 2) {
-        for (size_t i = 0; i < n; i++) {
-            float L = x48[2*i];
-            float R = x48[2*i+1];
-            mid[i] = (L + R) * 0.5f;
-            side[i] = (L - R) * 0.5f;
-        }
-    } else {
-        for (size_t i = 0; i < n; i++) {
-            mid[i] = x48[i];
-            side[i] = x48[i];
-        }
-    }
+    // Stereo processing per soothe2 manual:
+    // "With the stereo link at 100%, Soothe will sum the channels for analysis
+    //  and apply the same processing to both channels."
+    // Use separate processors for L and R to avoid stateful interference.

-    // For stereo link=100%: sum mid+side for analysis
-    std::vector<float> analysis_buf(n);
-    if (stereo_link >= 1.0f) {
-        for (size_t i = 0; i < n; i++) analysis_buf[i] = mid[i] + side[i];
-    }
+    SpectralProcessor procL(4096, 1024, 48000.0f);
+    SpectralProcessor procR(4096, 1024, 48000.0f);
+    procL.setDetectorParams(bands);
+    procR.setDetectorParams(bands);

-    // Create processors
-    SpectralProcessor mid_sp(4096, 1024, 48000.0f);
-    SpectralProcessor side_sp(4096, 1024, 48000.0f);
-    mid_sp.setDetectorParams(mid_bands);
-    side_sp.setDetectorParams(side_bands);
-
-    // Process
-    std::vector<float> mid_out(n), side_out(n);
+    std::vector<float> L_out(n), R_out(n);
    const size_t BLK = 1 << 16;
    std::vector<float> inb(BLK), outb(BLK);

+    // Process L channel
    for (size_t s = 0; s < n; s += BLK) {
        size_t blk = std::min(BLK, n - s);
-        memcpy(inb.data(), mid.data() + s, blk * sizeof(float));
+        memcpy(inb.data(), x48.data() + 2*s, blk * sizeof(float));
        for (size_t i = blk; i < BLK; i++) inb[i] = 0.0f;
-        mid_sp.processBlock(inb.data(), outb.data(), BLK, 1);
-        memcpy(mid_out.data() + s, outb.data(), blk * sizeof(float));
+        procL.processBlock(inb.data(), outb.data(), BLK, 1);
+        for (size_t i = 0; i < blk; i++) L_out[s+i] = outb[i];
    }

+    // Process R channel
    for (size_t s = 0; s < n; s += BLK) {
        size_t blk = std::min(BLK, n - s);
-        memcpy(inb.data(), side.data() + s, blk * sizeof(float));
+        memcpy(inb.data(), x48.data() + 2*s + 1, blk * sizeof(float));
        for (size_t i = blk; i < BLK; i++) inb[i] = 0.0f;
-        side_sp.processBlock(inb.data(), outb.data(), BLK, 1);
-        memcpy(side_out.data() + s, outb.data(), blk * sizeof(float));
+        procR.processBlock(inb.data(), outb.data(), BLK, 1);
+        for (size_t i = 0; i < blk; i++) R_out[s+i] = outb[i];
    }

-    // M/S encode with balance and mix
-    // mask is [0,1] where 1=no change, <1=reduction
-    // processed = input * mask
-    // output = input * (1 - mix) + processed * mix
-    // For side: apply balance to reduction amount
-    std::vector<float> Lout(n), Rout(n);
+    // Apply balance and mix
+    std::vector<float> L_final(n), R_final(n);
    for (size_t i = 0; i < n; i++) {
-        float m_in = mid[i];
-        float s_in = side[i];
-        float m_proc = mid_out[i];   // m_in * mask_mid
-        float s_proc = side_out[i];  // s_in * mask_side
-        
-        // Compute mask values (avoid division by zero)
-        float mask_mid = (std::abs(m_in) > 1e-12f) ? m_proc / m_in : 1.0f;
-        float mask_side = (std::abs(s_in) > 1e-12f) ? s_proc / s_in : 1.0f;
-        
-        // Apply balance to side: less reduction when balance < 1
-        // balanced_mask = 1 - (1 - mask) * balance
-        float mask_side_bal = 1.0f - (1.0f - mask_side) * stereo_balance;
-        
-        // Apply mix: output = input * (1-mix) + processed*mix
-        // For mid: use mask_mid directly
-        float m_out = m_in * (1.0f - mix) + m_in * mask_mid * mix;
-        // For side: use balanced mask
-        float s_out = s_in * (1.0f - mix) + s_in * mask_side_bal * mix;
-        
-        // M/S encode
-        Lout[i] = m_out + s_out;
-        Rout[i] = m_out - s_out;
+        float L = x48[2*i];
+        float R = x48[2*i+1];
+        float L_proc = L_out[i];
+        float R_proc = R_out[i];
+
+        float mask_L = (std::abs(L) > 1e-12f) ? L_proc / L : 1.0f;
+        float mask_R = (std::abs(R) > 1e-12f) ? R_proc / R : 1.0f;
+
+        // Apply balance: scale reduction for R channel
+        float mask_R_bal = 1.0f - (1.0f - mask_R) * stereo_balance;
+
+        // Apply mix
+        L_final[i] = L * (1.0f - mix) + L * mask_L * mix;
+        R_final[i] = R * (1.0f - mix) + R * mask_R_bal * mix;
    }

-    auto L44 = resample_mono(Lout, 48000, 44100);
-    auto R44 = resample_mono(Rout, 48000, 44100);
+    auto L44 = resample_mono(L_final, 48000, 44100);
+    auto R44 = resample_mono(R_final, 48000, 44100);
    size_t out_len = std::min(L44.size(), R44.size());
    out_len = std::min(out_len, x.size() / std::max(channels, 1));
    L44.resize(out_len);
    R44.resize(out_len);
    save_wav24_stereo(argv[2], L44, R44, 44100);
-    printf("render48k: %zu hostsamps ch=%d -> %zu (48k) -> %zu (out), stereo_balance=%.3f depth=%.3f\n",
+    printf("render48k: %zu hostsamps ch=%d -> %zu (48k) -> %zu (out), balance=%.3f depth=%.3f\n",
           x.size(), channels, x48.size(), out_len, stereo_balance, depth);
    return 0;
 }
@@ -0,0 +1,293 @@
+# prd.md — Project Requirements Document
+
+## 1. Project Overview
+
+**Name**: `soothe2-re` — bit-exact reverse engineering of **oeksound soothe2** (VST3, Windows x64)
+
+**Goal**: Reproduce the plugin's DSP core (level detector, mask computation, filter application) in C++17, byte-for-byte identical to the native binary.
+
+**Status**: ~95% decompiled. Current best metric: **0.341 dB TOTAL** (structural 48k chain). Target: **<0.05 dB** (bit-exact gate).
+
+**Golden rule**: Every parameter must have a source (decomp address / live table). Empirical fits must be flagged `EMPIRICAL`.
+
+---
+
+## 2. Repository Structure
+
+```
+re-tools/
+├── prd.md                    ← THIS FILE (project overview)
+├── README.md                 ← TOTAL metric source (single source of truth)
+├── AGENTS.md                 ← runbook: build, env flags, tooling hazard
+├── BITEXACT_PLAN.md          ← path to byte-exact (3 steps, criteria)
+├── roadmap.md                ← historical B-phase log (archived)
+│
+├── dsp/                      ← C++17 DSP reconstruction (THE CANON)
+│   ├── framed_model.{cpp,hpp} ← MAIN: mask-apply chain (empirical bridge)
+│   ├── render48k.cpp          ← 48k/4096 structural pipeline (resample→chain→resample)
+│   ├── spectral.{cpp,hpp}     ← STFT/ISTFT processor + FIR builder
+│   ├── fn529fe0.{cpp,hpp}     ← structural chain 9–19 (FUN_180529fe0)
+│   ├── fnfaith.{cpp,hpp}      ← faithful detector cascade (BLOCKMAP transcription)
+│   ├── fft{,_plan,_stage}.cpp/hpp ← FFT engine (canonical + RFFT bit-exact)
+│   ├── twin.{cpp,hpp}         ← twin resonator (FUN_180535880, float-parity)
+│   ├── rt_mask_tables.{hpp,.cpp} ← live IIR A/B coefficients (385K)
+│   ├── rt_weights.{hpp,.cpp}  ← live kWarp/kBand768 tables (44K)
+│   ├── fftconv.{cpp,hpp}      ← FFT convolution FIR application
+│   ├── vlog.{cpp,hpp}         ← fast log2 approximation
+│   ├── exp2.{cpp,_tables.cpp,hpp} ← fast exp2 approximation
+│   ├── levelpath.{cpp,hpp}    ← level-curve path (xv = log10(am/res))
+│   ├── freqpath.{cpp,hpp}     ← frequency-axis warp/freq-domain helpers
+│   ├── leveltrack.{cpp,hpp,hpp} ← envelope follower (attack/release tables)
+│   ├── log2_ln.{cpp,hpp}      ← log/ln utilities
+│   ├── filter.{cpp,hpp}       ← detection kernel (legacy)
+│   ├── detect.{cpp,hpp}       ← detector front-end (legacy)
+│   ├── phase_table.{cpp,hpp}  ← phase table for FFT
+│   ├── ms.hpp                 ← mid-side helpers
+│   ├── params.hpp             ← parameter struct
+│   ├── rotor_kernel.hpp       ← rotor transform kernel
+│   ├── rt_div_tables.hpp      ← division tables
+│   ├── soothe_constants.hpp   ← decoded constants
+│   ├── cody_waite.hpp         ← Cody-Waite argument reduction
+│   ├── twiddle_{builder,loader}.cpp/hpp ← FFT twiddle factors
+│   ├── dsp_ctx.hpp            ← DSP context layout
+│   ├── framed_test.cpp        ← CLI bridge renderer (44.1k)
+│   ├── harness.cpp           ← legacy harness
+│   ├── *_check.cpp            ← bit-exact unit test targets
+│   └── CMakeLists.txt
+│
+├── scripts/
+│   ├── corpus.py              ← bridge regression harness (62 cases, --compare)
+│   ├── corpus_structural.py   ← structural chain harness (--vs-bridge)
+│   ├── rendersnap2.py         ← RENDER_FILE stopper (reads from .rpp)
+│   ├── campaign.py            ← parameter sweep cell (~8 min)
+│   ├── cascade_sim.py         ← numpy step 9–19 simulator
+│   ├── disasm_func.py         ← capstone disasm with RIP constants
+│   ├── iat_name.py            ← runtime import resolution
+│   ├── wine_{chain,stage,ptrace}_trace.py ← ptrace-based live trace
+│   ├── dump_dispatch.py       ← table/state dumper
+│   ├── probe_{states,mem}.py  ← live state/memory probes
+│   ├── hunt2.py               ← ctx-instance hunter
+│   ├── scan_{pairs,lutsub}.py ← memory diagnostics
+│   ├── fit_vlaw_{params,by_group}.py ← VLAW law calibration
+│   ├── lawfit22r.py           ← law fitting (VLAW α/β/c)
+│   ├── mk_{dist,far,multi6}.py ← RPP generators
+│   └── render_parity.py       ← model-vs-render comparison
+│
+├── handoff/
+│   ├── NOTES_LEVEL.md         ← live journal (head: 24mm5+)
+│   ├── NOTES_LEVEL_INDEX.md   ← journal index by date/topic
+│   ├── BLOCKMAP_529fe0.md     ← FUN_180529fe0 method map (53K)
+│   ├── NOTES_TWIN.md          ← twin reference
+│   ├── NOTES_CAPTURE.md       ← live-capture protocol
+│   ├── NEXT_PROMPT.md         ← entry point for new sessions
+│   ├── SESSION_HANDOFF.md     ← handoff template
+│   ├── archive/               ← historical NOTES_LEVEL_*.md, SESSION_HANDOFF_*.md
+│   ├── nls_dasm/              ← 183 disassembly files (.dis, .bin)
+│   ├── phase1/                ← phase-1 outputs
+│   ├── rt*.npy                ← captured runtime tables (48k/44.1k)
+│   └── *.py                   ← emit/extract/joint scripts
+│
+├── *.java                     ← Ghidra scripts (DumpFuns, ImportRtti…)
+├── *.{bin,npz,npy,json,txt}   ← datasets, dumps, LUTs (mostly outside git)
+└── soothe-bt/                 ← test corpus (~600 renders, outside git)
+```
+
+---
+
+## 3. Build System
+
+**Generator**: CMake 3.10+, C++17, GCC/Clang with `-O3 -march=native`.
+
+```cmake
+# Key targets
+soothe2_dsp          # shared library (all dsp/*.cpp)
+framed_test          # CLI bridge renderer (44.1k)
+render48k            # structural renderer (48k/48000)
+twin_check           # float-parity unit test
+tables_check         # live-table verification
+fftconv_check        # FIR convolution check
+vlog_check           # fast log2 check
+leveltrack_check     # envelope follower check
+levelpath_check      # level-curve path check
+exp2_check           # fast exp2 check
+fn529fe0_check       # structural chain check
+soothe2_harness      # legacy harness
+```
+
+**External deps**: `libsamplerate` (render48k only), `pthread`.
+
+**Tooling hazard**: CMake skips rebuild when source modified within same second. Protocol: `touch` source before build + verify binary mtime.
+
+---
+
+## 4. DSP Architecture
+
+### 4.1 Signal Flow (current canon: structural `render48k`)
+
+```
+Host 44.1k → resample → 48k → [per-channel processing] → resample → 44.1k Host
+                                              ↓
+                                    ┌─────────────────────┐
+                                    │  FramedDetector      │
+                                    │  (per 4096 block)     │
+                                    │                      │
+                                    │  am[] ← envelope     │
+                                    │  res[] ← twin resp   │
+                                    │         ↓            │
+                                    │  lvl_raw = am/res·sf │
+                                    │         ↓            │
+                                    │  [RT_VLAW=1]:        │
+                                    │    cut = α·ln1p(L/β) │
+                                    │         +c [+Δ]      │
+                                    │    mask = 10^(-cut/20)│
+                                    │         ↓            │
+                                    │  warp: mask *=       │
+                                    │    kBand·kWarp·res^rp│
+                                    │         ↓            │
+                                    │  IIR3 ×2 (bidir)     │
+                                    │         ↓            │
+                                    │  mask_out → multiply │
+                                    │  spectrum[k] *= mask │
+                                    └─────────────────────┘
+```
+
+### 4.2 Dual Render Path
+
+| Path | File | Grid | Use |
+|------|------|------|-----|
+| Bridge | `framed_model.cpp` | 44.1k/2048 | Legacy, TOTAL 1.594 |
+| Structural | `render48k.cpp` | 48k/4096 | Canon, TOTAL 0.341 |
+
+**Dual-solution env set**: `RT_VLAW=1 RT_SYN=1 RT_NOWARP=1 RT_NOIIR3=1 RT_IIR12=0`
+
+### 4.3 Key Modules
+
+| Module | Responsibility |
+|--------|---------------|
+| `FramedDetector` | Per-band, per-frame mask computation. Holds `am_`, `res_`, `track_` state. |
+| `SpectralProcessor` | STFT/ISTFT, OLA overlap-add, FIR application modes. |
+| `fn529fe0` | Structural chain 9–19 (steps 9–19 of FUN_180529fe0): scale→IIR1→IIR2→blend→combine→warp→IIR3→dry/wet. |
+| `fnfaith` | Faithful detector cascade transcription (BLOCKMAP). |
+| `twin` | Twin resonator `|2B/A|` — frequency response per band. |
+| `rt_mask_tables` | Live IIR A/B coefficients (kIIR_A1/A2/A3, kIIR_B1/B2/B3, kRTAtt, kRTRel). |
+| `rt_weights` | Live warp weights (kBand768, kWarp). |
+| `fft` | Bit-exact RFFT (th1a90/th2180) with `buf548`/`mask598` tables. |
+| `fftconv` | FFT-based convolution for FIR application modes. |
+| `vlog`/`exp2` | Fast polynomial approximations matching plugin精度. |
+| `leveltrack` | Envelope follower with per-bin attack/release tables. |
+
+### 4.4 Detector Cascade (529c60)
+
+```
+complex_spectrum × twin_response → |z|
+  → Haar smooth [0.25,0.5,0.25] × n_iters
+  → peak = max(curve)
+  → sin_peak = sin(param·30 − 90) · 0.115129 · peak
+  → curve = max(curve, sin_peak)
+  → w = -log10(pow(50, ratio·0.001) · ratio·0.001)
+  → acc = acc·w + curve·(1-w)
+  → bands_curve = acc
+```
+
+---
+
+## 5. Environment Flags (experiment control)
+
+| Flag | Effect |
+|------|--------|
+| `RT_VLAW=1` | Two-stage law: `mask = 10^(−(α·ln1p(lvl/β)+c)/20)` |
+| `RT_SYN=1` | STFT without synthesis window (plugin's actual layer) |
+| `RT_WIN=0/1/2` | Analysis window: sym-Hann / periodic / rect |
+| `RT_NOWARP=1` | Skip warp modulation |
+| `RT_NOIIR3=1` | Skip IIR3 ×2 |
+| `RT_IIR12=0` | Skip freq-domain IIR1/2 (critical with VLAW) |
+| `RT_DUMP_BIN=<f>` | Dump tract binary (frame `RT_DUMP_FRAME`) |
+| `RT_VDBG=1` | Print VLAW computations to stderr |
+| `RT_FAITHFUL=1` | Use faithful chain (`fnfaith.cpp`) |
+| `RT_FIRCONV=1/3` | FIR application mode (1=complex-mul, 3=`1.019·mask^1.8345`) |
+| `RT_ENV=live` | Live envelope from kRTAtt/kRTRel tables |
+| `RT_KMAP=1` | k-mapping correction (twin/am scaling) |
+| `RT_EQ=1` | Pre-detector EQ bell |
+| `RT_LUT_OFF=1` | Skip LUT transform |
+| `RT_LUT_A/B/G/M` | LUT parameters (A=-24, B=28, gamma=1, mult=4.2) |
+
+---
+
+## 6. Test Corpus & Metrics
+
+**Location**: `/home/m/soothe-bt/` (~600 renders, outside git).
+
+**Key sets**:
+
+| Prefix | Content |
+|--------|---------|
+| `tone1kq_*` | Single tone, fc-scan, quiet (-18 dBFS) |
+| `tone1k_*` | Single tone, fc-scan, loud (0 dBFS) |
+| `dual_b1q_*` | Two tones (500+2000), q 0.1…10 |
+| `al_*` | Level sweep (fc=1000) |
+| `comb_*` | 4-band multiband |
+| `burst500_b1` | Primary reference (burst 500 Hz) |
+
+**Metric** (Goertzel steady-state):
+```python
+err_dB = 20·log1₀( ta(out,1000) / ta(ref,1000) )
+# trimmed to last 75% of input, matched to plugin render length
+```
+
+**Regression guards**:
+```bash
+python3 scripts/corpus.py                                    # bridge + guard
+python3 scripts/corpus_structural.py                         # structural chain
+python3 scripts/corpus.py --compare scripts/baseline_bridge.json --tol 0.25
+python3 scripts/corpus_structural.py --vs-bridge scripts/baseline_bridge.json
+```
+
+---
+
+## 7. Current Status (2026-08-29, 24mm14)
+
+| Group | Bridge | Structural (VLAW) |
+|-------|--------|-------------------|
+| t1kq (fc-scan) | 0.226 | 0.426–0.852 |
+| t1k (loud) | 1.801 | 0.577–0.930 |
+| al (level) | 0.638 | 0.090–0.804 |
+| res | 0.628 | 0.395 |
+| dual (q-sweep) | 0.726 | **0.193** ✓ |
+| comb (4-band) | 10.149 | 2.678–4.335 |
+| **TOTAL** | **1.594** | **0.341** |
+
+**Decoded**:
+- Layer: STFT without synthesis window, per-bin mask multiply
+- Law: `mask = 10^(−(α·ln1p(lvl/β)+c)/20)` with content-aware Δ
+- FIR: `exp(0.984·ln(raw))` + Hann + normalize → bit-exact RFFT to df0
+
+**Open gaps**:
+1. **Chain 9–19** (priority #1): Dataflow decoded, bigkernel bodies known, I/O format unknown. Target: <0.05.
+2. **k-mapping** (priority #2): twin/am scaling `k(q≥2)=0.403`.
+3. **Δ second-peak rule** (priority #3): Content-dependent gain, requires live-dump.
+
+---
+
+## 8. Reference Documents
+
+| Doc | Content |
+|-----|---------|
+| `README.md` | TOTAL metric, reproduction steps |
+| `AGENTS.md` | Build commands, env flags, hazard, corpus format |
+| `BITEXACT_PLAN.md` | 3-step plan to byte-exact |
+| `handoff/BLOCKMAP_529fe0.md` | Method map for FUN_180529fe0 |
+| `handoff/NOTES_LEVEL.md` | Live working journal |
+| `handoff/NOTES_LEVEL_INDEX.md` | Journal index |
+| `handoff/NOTES_TWIN.md` | Twin resonator reference |
+| `handoff/NOTES_CAPTURE.md` | Live-capture protocol |
+| `handoff/nls_dasm/` | 183 disassembly files |
+
+---
+
+## 9. Reproduction & Development Protocol
+
+1. Install soothe2 VST3 (Windows) under yabridge → `dump_soothe.py` → `soothe_mem.bin`
+2. Ghidra headless: `analyzeHeadless <proj> soothe_x64 -process soothe_mem.bin -noanalysis -postScript <X>.java`
+3. Renders: `sweep.py` → `.rpp`, `reaper -renderproject` → `.wav`
+4. Analysis: `render_parity.py` / `corpus.py`
+5. After C++ edit: `touch` source → `cmake --build dsp/build --target framed_test` → run corpus guards