beqforge 0.2.2__tar.gz → 0.2.3__tar.gz

{beqforge-0.2.2 → beqforge-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: beqforge
-Version: 0.2.2
+Version: 0.2.3
 Summary: Audio-derived BEQ design, published filter optimisation and DSP validation
 License-File: LICENCE.md
 Requires-Python: <3.15,>=3.13

{beqforge-0.2.2 → beqforge-0.2.3}/TODO.md

@@ -18,29 +18,31 @@ are retained so records and code comments remain traceable. Completed items are
 | Priority | ID | Status | Value, work and blocker or reason for parking |
 | --- | --- | --- | --- |
 | 1 | Playback contract | open | Reconcile the supplied bass-management model with the model actually used for targets, verification and clipping. Only `lpf_fs` is consumed today; check the ignored fields before claiming the listener's clipping cost. Caller propagation is an external subtask. |
-| 2 | E10 | open | Predeclare fresh content-goal validation before further tuning or a default change. Existing seeds and corpus have repeatedly informed development; writing the protocol needs no new audio. |
-| 3 | E1 | open | Add record-only scene-held-out verification: evidence independent of the material that generated the target. A gate needs a separate demonstrated benefit. |
-| 4 | Steep-filter scoring | open | Implement coloured/codec-like floors and recipe-specific truth bands under E10; inspect shape failures and published-ceiling excess. Existing titles can supply programme texture. |
-| 5 | Steep-filter default | blocked | Recovery improves substantially with `--content-edge`, but changing the default needs E10, the scoring above, listening judgements and more independent real steep titles. Safe House already works with the default; keep the option off meanwhile. |
-| 6 | F2 / device behaviour | in progress; first hardware pilot measured | Coefficient quantisation does not establish hardware accuracy. Limit changes need measured internal arithmetic/noise/limit cycles on a named device and a capture setup; the [measurement plan](plans/F2-device-precision-validation.md) specifies Python sweep/capture, optional REW cross-checks, software controls, single-entry/full-catalogue analysis and a standalone cross-platform executable. The `beqforge-device-check` preview includes frozen manifests, capture/recovery, CLI-only miniDSP controls (minidsp-rs 0.1.12, batched through `-f`) with float32 transport attribution, staged qualification/convergence, uncertainty-aware filter checks, entry/unique-cascade frequency distributions and matched-device deltas. First verified pilot on a miniDSP 2x4 HD (USB loopback, 96 kHz): the device plays its float32 coefficients as predicted (worst 0.0074 dB, 2-200 Hz), while float32 coefficients themselves put 18.8 dB of error into a 5 Hz Q 6 peak; see the plan, section 12. First catalogue sample (50 cascades): 49 play as predicted on every bin (worst 0.0082 dB); the 50th was clipped by the device and is to be remeasured (F2a, plan section 13). Next: the `grid` and `boundary` suites on hardware to map where float32 coefficients stop representing low, high-Q filters. No Q-limit change yet. |
-| 7 | Validation coverage (former TODO 10) | blocked | Broad real-programme generalisation needs the missing shapes and independently characterised paired releases listed below. Sparse titles exist; their absolute truth and wider sparse coverage remain missing. |
-| 8 | Identification | blocked | Generalising `N(f)` and its fit band needs independent, varied source material, especially paired releases. Sensitivity experiments can proceed; programme-only uncertainty cannot identify the cause of a droop. |
-| 9 | E4 | parked | No measured failure has been attributed to isolated ceiling holes. Reopen if unevenness or E9 excess is traced to such bins; smoothing may only reduce the raw licence. |
-| 10 | F4 follow-up | parked | Both fitter-objective selection spikes lost passes/true positives. Judge several fits only with a demonstrated usable alternative discarded before `_judge`; a smaller residual is insufficient evidence. |
-| 11 | F3 follow-up | parked | A fifth section moved no verdict when tried and costs more fitting. Reopen if an evidence-supported target has a demonstrated usable fit beyond four sections and no usable fit within four. |
-| 12 | T2 | parked | The steep-variant audit found no swept cap binding a weak winner. Derive caps only when a binding cap demonstrably prevents a better supported result. |
-| 13 | Residual (former TODO 5) | open | Correct the reported target error and its actual measurement band without changing fit selection. Primarily audit accuracy; any escalation/objective change is a separate, higher-impact decision. Non-parametric reporting is already allowed upstream. |
-| 14 | Authored features | parked | Manual `--exclude` works; no validated automatic detector exists. Reopen with real labelled features and negatives showing that detection preserves legitimate bass. |
-| 15 | Dynamic processing (former TODO 11) | parked | No suspected real case has scoped a useful tripwire. Reopen when compression/limiting demonstrably compromises this correction; non-LTI processing alone does not prove every BEQ is invalid. |
-| 16 | Tilted passband reference (goal/corpus follow-up) | parked | No real in-sub-band case needs a sloping reference yet; Dossier's abstention was decided. Reopen with one. Goal-aware corpus labels belong to the open E10 protocol work. Nearest so far: 13 Going on 30's mix tilts about −7 dB/oct above 50 Hz (bass is coherent across channels, ~200 Hz is not) and finds its plateau only through the one-sided fallback. That reference reads a 36 dB deficit below 25 Hz; each channel's own plateau reads 30-34 dB. A reference built from the channels would be 2-5 dB less generous there (see plans/done-design-and-pipeline.md, 11 October 2026). |
-| 17 | Mixed-channel policy | parked | `channel_scope` is currently an unpopulated optional response field, not a computed `mixed` finding awaiting a gate. Reopen with a case where existing per-channel restoration and common pricing produce an unsuitable mix correction. |
-| 18 | Fraction dial (former TODO 7) | parked | No user/title has needed partial licensed restoration as a preference; tilt and tolerance already ship. Reopen with a concrete requested outcome, then price and validate it like every target. |
-| 19 | Protective corner (former TODO 9) | parked | The corner is already derived from boost cap and implied order, floored by `lowest_frequency_hz`. No case requires an independent override or different fallback alignment; reopen with one. |
-| 20 | Device configuration on the wire | parked | The current contract deliberately omits device preference; server flags already configure realisation. Reopen if one server must serve different device formats/rates per request; then agree an upstream extension. Hardware validity remains F2. |
-| 21 | Catalogue comparison (former TODO 8) | parked | A disagreement detector has no demonstrated accuracy benefit. Reopen with an independent discrepancy to investigate; authored filters remain comparisons, never calibration targets. |
-| 22 | Performance | parked | Further reuse changes cost, not filter accuracy. Reopen after measuring repeated numerical identities or material remaining analysis cost; missed-fit search belongs to F3/F4 instead. |
-| 23 | Chart peak bias | parked | Deliberate catalogue-compatible per-bin maximum; it affects presentation only. Reopen if a reader needs an alternative percentile view; keep it distinct from the 95th-percentile evidence envelope. |
-| 24 | Documentation citations | open | Remove or repoint orphan references and stale descriptions of shipped behaviour. Low filter impact, but prevents future changes being based on obsolete assumptions. |
+| 2 | Texture yardstick band | open (E10 only) | Implemented: the mix's ripple is measured about a cubic over the unchanged band, so the LFE knee is trend. 9 (2009), Beauty and the Beast, Crazy, Stupid, Love and Despicable Me 3 now accept; Carrie stays declined. Probe and protocol unchanged; corpus 0/45 gate pass. Neither width-normalised form separated `broadband/5`. The degree was chosen on corpus and library data, so it needs the fresh E10 validation before it counts as settled; see [the outcome](plans/texture-yardstick-sub-band.md#outcome-17-october-2026). |
+| 3 | E10 | open | Predeclare fresh content-goal validation before further tuning or a default change. Existing seeds and corpus have repeatedly informed development; writing the protocol needs no new audio. |
+| 4 | E1 | open | Add record-only scene-held-out verification: evidence independent of the material that generated the target. A gate needs a separate demonstrated benefit. |
+| 5 | Steep-filter scoring | open | Implement coloured/codec-like floors and recipe-specific truth bands under E10; inspect shape failures and published-ceiling excess. Existing titles can supply programme texture. |
+| 6 | Steep-filter default | blocked | Recovery improves substantially with `--content-edge`, but changing the default needs E10, the scoring above, listening judgements and more independent real steep titles. Safe House already works with the default; keep the option off meanwhile. |
+| 7 | F2 / device behaviour | in progress; first hardware pilot measured | Coefficient quantisation does not establish hardware accuracy. Limit changes need measured internal arithmetic/noise/limit cycles on a named device and a capture setup; the [measurement plan](plans/F2-device-precision-validation.md) specifies Python sweep/capture, optional REW cross-checks, software controls, single-entry/full-catalogue analysis and a standalone cross-platform executable. The `beqforge-device-check` preview includes frozen manifests, capture/recovery, CLI-only miniDSP controls (minidsp-rs 0.1.12, batched through `-f`) with float32 transport attribution, staged qualification/convergence, uncertainty-aware filter checks, entry/unique-cascade frequency distributions and matched-device deltas. First verified pilot on a miniDSP 2x4 HD (USB loopback, 96 kHz): the device plays its float32 coefficients as predicted (worst 0.0074 dB, 2-200 Hz), while float32 coefficients themselves put 18.8 dB of error into a 5 Hz Q 6 peak; see the plan, section 12. First catalogue sample (50 cascades): 49 play as predicted on every bin (worst 0.0082 dB); the 50th was clipped by the device and is to be remeasured (F2a, plan section 13). Next: the `grid` and `boundary` suites on hardware to map where float32 coefficients stop representing low, high-Q filters. No Q-limit change yet. |
+| 8 | Validation coverage (former TODO 10) | blocked | Broad real-programme generalisation needs the missing shapes and independently characterised paired releases listed below. Sparse titles exist; their absolute truth and wider sparse coverage remain missing. |
+| 9 | Identification | blocked | Generalising `N(f)` and its fit band needs independent, varied source material, especially paired releases. Sensitivity experiments can proceed; programme-only uncertainty cannot identify the cause of a droop. |
+| 10 | E4 | parked | No measured failure has been attributed to isolated ceiling holes. Reopen if unevenness or E9 excess is traced to such bins; smoothing may only reduce the raw licence. |
+| 11 | F4 follow-up | parked | Both fitter-objective selection spikes lost passes/true positives. Judge several fits only with a demonstrated usable alternative discarded before `_judge`; a smaller residual is insufficient evidence. |
+| 12 | F3 follow-up | parked | A fifth section moved no verdict when tried and costs more fitting. Reopen if an evidence-supported target has a demonstrated usable fit beyond four sections and no usable fit within four. |
+| 13 | T2 | parked | The steep-variant audit found no swept cap binding a weak winner. Derive caps only when a binding cap demonstrably prevents a better supported result. |
+| 14 | Residual (former TODO 5) | open | Correct the reported target error and its actual measurement band without changing fit selection. Primarily audit accuracy; any escalation/objective change is a separate, higher-impact decision. Non-parametric reporting is already allowed upstream. |
+| 15 | Authored features | parked | Manual `--exclude` works; no validated automatic detector exists. Reopen with real labelled features and negatives showing that detection preserves legitimate bass. |
+| 16 | Dynamic processing (former TODO 11) | parked | No suspected real case has scoped a useful tripwire. Reopen when compression/limiting demonstrably compromises this correction; non-LTI processing alone does not prove every BEQ is invalid. |
+| 17 | Tilted passband reference (goal/corpus follow-up) | parked | No real in-sub-band case needs a sloping reference yet; Dossier's abstention was decided. Reopen with one. Goal-aware corpus labels belong to the open E10 protocol work. Nearest so far: 13 Going on 30's mix tilts about −7 dB/oct above 50 Hz (bass is coherent across channels, ~200 Hz is not) and finds its plateau only through the one-sided fallback. That reference reads a 36 dB deficit below 25 Hz; each channel's own plateau reads 30-34 dB. A reference built from the channels would be 2-5 dB less generous there (see plans/done-design-and-pipeline.md, 11 October 2026). |
+| 18 | Mixed-channel policy | parked | `channel_scope` is currently an unpopulated optional response field, not a computed `mixed` finding awaiting a gate. Reopen with a case where existing per-channel restoration and common pricing produce an unsuitable mix correction. |
+| 19 | Fraction dial (former TODO 7) | parked | No user/title has needed partial licensed restoration as a preference; tilt and tolerance already ship. Reopen with a concrete requested outcome, then price and validate it like every target. |
+| 20 | Protective corner (former TODO 9) | parked | The corner is already derived from boost cap and implied order, floored by `lowest_frequency_hz`. No case requires an independent override or different fallback alignment; reopen with one. |
+| 21 | Device configuration on the wire | parked | The current contract deliberately omits device preference; server flags already configure realisation. Reopen if one server must serve different device formats/rates per request; then agree an upstream extension. Hardware validity remains F2. |
+| 22 | Catalogue comparison (former TODO 8) | parked | A disagreement detector has no demonstrated accuracy benefit. Reopen with an independent discrepancy to investigate; authored filters remain comparisons, never calibration targets. |
+| 23 | Performance | parked | Further reuse changes cost, not filter accuracy. Reopen after measuring repeated numerical identities or material remaining analysis cost; missed-fit search belongs to F3/F4 instead. |
+| 24 | Chart peak bias | parked | Deliberate catalogue-compatible per-bin maximum; it affects presentation only. Reopen if a reader needs an alternative percentile view; keep it distinct from the 95th-percentile evidence envelope. |
+| 25 | Documentation citations | open | Remove or repoint orphan references and stale descriptions of shipped behaviour. Low filter impact, but prevents future changes being based on obsolete assumptions. |
+| 26 | Texture yardstick retune (library review) | parked | The cubic (row 2) keeps the 200 Hz band only because the sub-band cap admitted one synthetic negative, `broadband/5`: chance unevenness in noise bursts, at a 2.6 dB boost. With 45 gated cases a single case moves the gate's upper bound from 0.079 to 0.118. Carrie is still declined (0.85x about a cubic, 1.33x with the cap). Reopen when the beqdesigner library review (~1,290 titles) is complete. Then retune against its declines: the band edge, the trend degree, and whether the gate weights a false acceptance by its boost. The library holds no known negative, so it can expose wrong declines but not measure false acceptances. Any retune still needs the corpus or a fresh E10 set for that, ideally with negatives built from real programme texture (row 5). See [the outcome](plans/texture-yardstick-sub-band.md#outcome-17-october-2026). |
 
 ## Review evidence
 

{beqforge-0.2.2 → beqforge-0.2.3}/beq_common/__init__.py

@@ -1,6 +1,6 @@
 """Shared filter primitives; no workflow package dependencies."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 from .types import BiquadSpec as BiquadSpec
 from .types import BiquadType as BiquadType

{beqforge-0.2.2 → beqforge-0.2.3}/beqforge/AGENTS.md

@@ -333,7 +333,11 @@ least `min_judge_octaves` above the floor — no fixed top (historical review T6
   (`pipeline.passband_ripple_db`) is left alone: it abstains with `within_programme_ripple`
   before any strategy runs. That ripple is the title's own yardstick, so there is no constant.
   Crest to trough rather than a one-sided dip, because the reference sits on the crests. This
-  is what took the negative corpus from 4 false acceptances in 45 to 0.
+  is what took the negative corpus from 4 false acceptances in 45 to 0. The mix's ripple is
+  taken about a cubic in log frequency, so an LFE-led mix's knee above the crossover is trend,
+  not texture; each channel's is taken about a line. Don't shorten the band instead:
+  crest to trough shrinks with bin count, and the 1x boundary was calibrated on the full band
+  ([plans/texture-yardstick-sub-band.md](../plans/texture-yardstick-sub-band.md)).
 * **Steep filters: the default declines them; `judge_from_content_edge` is an opt-in that
   recovers them and lifts some noise.** Below a steep filter's edge the priced target already
   falls into the quiet floor with the programme — contrast bounds it — and the shape clauses

{beqforge-0.2.2 → beqforge-0.2.3}/beqforge/pipeline.py

@@ -772,6 +772,9 @@ MAINS_HZ = (50.0, 60.0)
 # inside the 50 Hz spacing so it never reaches the next harmonic
 HUM_NOTCH_HALF_WIDTH_HZ = 2.5
 HUM_SURROUND_HALF_WIDTH_HZ = 10.0
+# the mix's texture is measured about a cubic in log frequency, so an LFE-led mix's knee above
+# the crossover is trend, not ripple (plans/texture-yardstick-sub-band.md)
+MIX_TEXTURE_TREND_DEGREE = 3
 
 
 def mains_hum_notches(
@@ -815,7 +818,11 @@ def mains_hum_notches(
 
 
 def passband_ripple_db(
-    material: Material, params: "PipelineParams", noise_floor_hz: float = math.nan
+    material: Material,
+    params: "PipelineParams",
+    noise_floor_hz: float = math.nan,
+    *,
+    trend_degree: int = 1,
 ) -> tuple[float, tuple[float, float]] | None:
     """The programme's own texture where nothing is missing: crest-to-trough, dB, and where.
 
@@ -823,6 +830,17 @@ def passband_ripple_db(
     correction — the top of the judged band to the top of the analysis band — as the spread of
     the curve about its own log-frequency trend, so a tilted passband is not read as ripple.
 
+    The trend is a polynomial of `trend_degree` in log frequency. The mix's texture blocker
+    asks for a cubic (`MIX_TEXTURE_TREND_DEGREE`). In an LFE-led mix the level falls away
+    where the LFE channel's content ends (60-100 Hz), a knee a straight line cannot remove, so
+    it read as ripple and withheld a real deficit: 9 (2009) measured 8.8 dB of "ripple" against
+    a 6.2 dB shortfall, 2.2 dB about a cubic. The band is not shortened instead. Crest to
+    trough shrinks with the number of bins even on noise, so ending it at the crossover lowered
+    every yardstick and admitted a broadband negative on the corpus. A cubic keeps the band the
+    1x boundary was calibrated on and leaves the negatives where they were: at most 0.76x about
+    a cubic against 0.77x about a line, with every real and filtered title at 1.08x and up.
+    Each channel's own rule (`channels_missing_low_end`) keeps the line.
+
     Crest to trough, not a one-sided dip, because the reference sits near the 90th percentile
     of the spectrum, on the crests: a shortfall measured from it spans the whole swing. On the
     negative corpus (IMPROVEMENT_PLAN E2) every unfiltered title's low-end deficit came in
@@ -847,7 +865,7 @@ def passband_ripple_db(
         return None
     smooth = smooth_unexcluded(response, freqs, bands, 15, levels=True)[band]
     octaves = np.log2(freqs[band])
-    about = smooth - np.polyval(np.polyfit(octaves, smooth, 1), octaves)
+    about = smooth - np.polyval(np.polyfit(octaves, smooth, trend_degree), octaves)
     return float(np.max(about) - np.min(about)), (low, high)
 
 
@@ -1550,7 +1568,12 @@ def analyse(
                 f"programme (tracking stops at {diagnosis.noise_floor_hz:.1f} Hz), so there "
                 "is no bass passband to restore towards; restoration withheld"
             )
-        texture = passband_ripple_db(material, params, diagnosis.noise_floor_hz)
+        texture = passband_ripple_db(
+            material,
+            params,
+            diagnosis.noise_floor_hz,
+            trend_degree=MIX_TEXTURE_TREND_DEGREE,
+        )
         low_end = low_end_deficit_db(material, params, diagnosis.noise_floor_hz)
         if texture is not None and low_end is not None:
             ripple, (edge_low, edge_high) = texture

beqforge-0.2.3/plans/texture-yardstick-sub-band.md

@@ -0,0 +1,215 @@
+# Texture yardstick: measure it in the band the sub plays
+
+**Status: implemented (17 October 2026), as a cubic detrend over the unchanged band, not as
+either width-normalised measure below.** See [Outcome](#outcome-17-october-2026). The rest of
+this document is the original handoff, from the beqdesigner library design run (October
+2026), where every decline of the full JRiver library (~1,290 films) is being reviewed. The
+first two attempts, which only shorten the band, are in
+[texture-yardstick-sub-band.patch](texture-yardstick-sub-band.patch); it applies to `main`
+at `fd9ae22`. It fails the corpus gate, so it was not committed.
+
+## The problem
+
+`pipeline.passband_ripple_db` measures the programme's texture as the crest-to-trough swing
+of the smoothed mean spectrum about its own linear log-frequency trend. It runs from the top
+of the judged band to the **top of the analysis band** (`diagnose.band_hz[1]`, 200 Hz). If the
+deepest low-end shortfall is no bigger than that swing, the title is declined
+`within_programme_ripple`. `channels_missing_low_end` uses the same function for each
+channel.
+
+Above the sub crossover (80 Hz), the mix's shape is not texture the sub plays. In an
+LFE-led 5.1 mix the level falls away where the LFE content ends (about 60-100 Hz). A linear
+detrend cannot remove that knee, so it is counted as ripple and the yardstick gets bigger.
+The rule's 1x boundary was calibrated on the negative corpus, which is two-channel synthetic
+material with no LFE knee. That is why calibration did not catch this.
+
+## Evidence
+
+**9 (2009)**, 5.1 DTS-HD, LFE carries 77% of the plateau. Local rerun at v0.2.1, with the
+material digest matching the deployed request:
+
+| Yardstick band | Ripple | Shortfall | Outcome |
+| --- | --- | --- | --- |
+| 23-200 Hz (current) | 8.8 dB | 6.2 dB | declined `within_programme_ripple` |
+| 23-80 Hz (crossover) | 5.1 dB | 6.2 dB | accepts `flatten`: LowShelf 13.0 Hz +6.4 dB Q 0.72, confidence 0.97 |
+
+- The community BEQ (aron7awol) is 2x LowShelf 10 Hz +3.2 dB + LowShelf 27 Hz +2 dB: the same
+  kind and size of correction.
+- The level-invariance evidence supports a real filter: the loudness strata agree down to
+  4.15 Hz, and content tracks all the way down.
+
+Other titles declined this way in the run (shortfall vs the ripple capped at the crossover):
+
+| Title | Shortfall | Capped ripple |
+| --- | --- | --- |
+| Beauty and the Beast (1991) | 11.7 dB | 9.74 dB |
+| Carrie (1976) | 8.4 dB | 6.32 dB |
+| Crazy, Stupid, Love (2011) | 10.8 dB | 4.06 dB |
+| Despicable Me 3 (2017) | 4.3 dB | 3.1 dB |
+
+Battle: Los Angeles and Changeling are not affected: their capped ripple still exceeds their
+shortfall.
+
+## What was tried (the patch)
+
+1. **Capping both rules at the sub edge** (`min(crossover_hz, bus_lowpass_hz)`, the edge the
+   plateau blocker already uses). Corpus: 1 false acceptance in 45 gated (`broadband/5`,
+   `counterfactual/25dB`). The gate's upper bound is 0.118, above 0.100: **fail**. Through the
+   per-channel rule, counterfactual targets also grew on Bugonia, Caught Stealing (peak
+   4.3 -> 12.3 dB) and Incredible Hulk.
+2. **Capping the mix rule only** (`in_sub_band=True`; each channel keeps the whole passband).
+   The probe is unchanged on all 11 baseline titles, and the protocol is identical on both
+   seeds. 9, Beauty and the Beast and Carrie are all accepted:
+   - 9: LowShelf 13.0 Hz +6.4 dB
+   - Beauty and the Beast: LowShelf 13.8 Hz +2.4 dB, LowShelf 35.1 Hz +1.0 dB, PeakingEQ 24.4 Hz +4.6 dB
+   - Carrie: LowShelf 6.5 Hz +3.7 dB
+
+   The corpus still fails: `flatten` now accepts `broadband/5` (peak boost 2.6 dB), 1/45,
+   upper bound 0.118.
+
+**Why the gate fails:** crest-to-trough is an extreme-value statistic, so it shrinks as the
+band holds fewer bins, even on pure noise. The 1x boundary was earned with the 200 Hz band.
+Shortening the band therefore lowers every title's yardstick, the genuine negatives'
+included. Fixing the band is really a recalibration.
+
+## Wanted: a width-normalised measure
+
+Measure texture with a statistic that does not depend on how wide the band is. Then the band
+can end at the sub edge without moving the 1x boundary the corpus set. Two candidate forms;
+the owner of beqforge chooses:
+
+- **A scaled robust spread.** Compute the residual about the trend as now, then take a spread
+  that converges with bin count instead of growing with it (standard deviation, or an
+  inter-percentile range such as 5th-95th). Scale it by the ratio of crest-to-trough to that
+  spread, measured over the full 200 Hz band on the calibration titles. Then, on the band the
+  rule was calibrated on, the yardstick stays in units of what the corpus measured, while a
+  shorter band no longer shrinks it just by being shorter.
+- **A fixed-width window.** Take crest-to-trough over a sliding window of fixed octave width,
+  inside the judged-top-to-sub-edge band (the largest or the median of the windows), so every
+  title is measured over the same width. Choose the window from the corpus, and fall back to
+  the current measure where the band is narrower than one window.
+
+Either way, keep what the docstring already relies on: the reference sits on the crests, so
+the yardstick must still span the whole swing a shortfall is measured across; hum notches stay
+excluded (`mains_hum_notches` still searches the whole passband, because below 80 Hz only one
+harmonic remains); and when the judged band already reaches past the sub edge, the analysis
+band is kept.
+
+Decide separately whether the per-channel rule moves too. The first attempt shows that a
+smaller yardstick there judged more channels short, so leaving it alone is the safer
+default.
+
+## Completion criteria
+
+- `tools/negative_corpus.py`: false acceptances 0/45, gate pass, with `broadband/5` declined.
+- `tools/validate_evidence.py` and the protocol: unchanged on both seeds; the probe unchanged
+  on the 11 baseline titles, or each change explained.
+- 9 (2009) accepted with a correction of the size above. Beauty and the Beast and Carrie
+  accepted, or the reason they are not recorded.
+- If the measure needs any constant fitted to the corpus, the fresh validation E10 asks for
+  applies before it becomes the default.
+
+## Repro
+
+The library run's audio and scripts are on the beq share (`/media/beq`):
+
+```sh
+python -I /media/beq/triage/scripts/ripple_counterfactual.py <beqforge checkout> \
+    "/media/beq/work/9 - audio 1" \
+    c942feb4b5f22f680bb4fc8fc484d63afe92c4dc796b1c26701a07a5b93c5739 <out dir>
+```
+
+It reruns the title as deployed, then with the yardstick capped at the crossover, and checks
+the material digest against the deployed request. The patch's
+`tests/test_design_ripple_band.py` has a synthetic LFE-led source (noise with a knee at 70
+Hz) that is a reasonable unit test for any replacement.
+
+## Outcome (17 October 2026)
+
+### Neither width-normalised form separates the corpus
+
+Both forms were scored offline before any code changed. Each candidate measured the same
+residual as `passband_ripple_db`, over the full band and capped at the sub edge, on all 63
+corpus cases (seeds 1-9), the 11 baseline titles, the 43 variants and the 8 library titles
+above. A scaled spread took the corpus median of crest-to-trough/spread over the full band as
+its scale. Shortfall/yardstick, where above 1 is accepted:
+
+| Sub-band yardstick | Worst gated negative | 9 | Beauty and the Beast | Despicable Me 3 |
+| --- | --- | --- | --- | --- |
+| crest-to-trough (the patch) | 1.11 (`sparse_dialogue/9`)\* | 1.22 | 1.20 | 1.39 |
+| 4.79 x standard deviation | 1.05 (`broadband/5`)\* | 1.15 | 1.10 | 1.09 |
+| 1.48 x 5th-95th percentile | 1.06 (`broadband/5`)\* | 1.33 | 0.99 | 1.12 |
+| largest ¾-octave window | 1.11 (`sparse_dialogue/9`)\* | 1.14 | 1.13 | 1.30 |
+
+\* Excluding `sparse_dialogue/5`, at 3.2-5.2x on every one. Its judged top is 77 Hz, so its
+sub band is 0.06 octaves wide. A sub-band yardstick also needs a minimum width, which neither
+form had.
+
+The handoff's premise is only half right. `broadband/5`'s sub band is smoother in fact, not
+just shorter: its standard deviation falls from 0.9 to 0.6 dB, and so does every
+width-invariant statistic. A shorter band also lets the linear trend take up more of the slow
+structure. No statistic over the sub band left a margin worth calling a separation.
+
+### What was built: a cubic trend over the same band
+
+The knee is a trend problem, not a band problem, so the band stays where the 1x boundary was
+calibrated (judged top to `diagnose.band_hz[1]`), and only the mix's detrend changes.
+`passband_ripple_db` takes `trend_degree` (1 by default). The mix's texture blocker passes
+`MIX_TEXTURE_TREND_DEGREE` = 3. `channels_missing_low_end` keeps the line, as the handoff
+advised.
+
+The same study, full band, mix rule:
+
+| Trend | Worst gated negative | Lowest real/filtered/variant | 9 | B&tB | CSL | DM3 | Carrie |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| line (before) | 0.77 | 1.01 (Incredible Hulk) | 0.71 | 0.98 | 0.98 | 0.62 | 0.82 |
+| quadratic | 0.82 | 1.05 (Bugonia) | 1.21 | 1.00 | 1.06 | 1.31 | 0.86 |
+| hinge at 80 Hz | 0.77 | 1.05 (Bugonia) | 1.00 | 1.01 | 1.08 | 1.14 | 0.87 |
+| **cubic** | **0.76** | **1.08 (Bugonia)** | **2.79** | **1.11** | **1.06** | **1.43** | **0.85** |
+
+The cubic is the only trend that widens the separation at both ends. Over all 125 items, it
+changes the texture verdict on exactly four: 9, Beauty and the Beast (1991), Crazy, Stupid,
+Love and Despicable Me 3. A cubic can raise a yardstick as well as lower it (`sparse_dialogue/9`
+measures 5.54 dB about it against 5.24 about a line), but no verdict went that way. Battle: Los
+Angeles (0.28) and Changeling (0.89) stay declined.
+
+### Regression check
+
+* **Probe** (11 baseline titles, default params): unchanged on every title.
+* **Protocol**, seeds 101 and 947, before in a HEAD worktree (`a4b4d06`, the code of `fd9ae22`) and after: every decision,
+  score and failure identical. The only difference is the ripple figure quoted in two
+  `within_programme_ripple` notes per seed.
+* **Negative corpus**, seeds 1-9: 0/45 false acceptances on the gated shapes, upper bound
+  0.079 against 0.100, **pass**. All of `broadband/*` abstains. Ungated: `natural_droop` 4/9,
+  `filtered` 7/9 true positives, median recovery 1.27 dB RMS. The committed
+  `negative_corpus.json` is from an older revision (`4c6d5c3`), and 7 cases differ from it:
+  5 in recovery or peak boost on accepted cascades, and `natural_droop/7`, now abstaining.
+  None is this change: no corpus case's texture verdict moves under the cubic, and the
+  blocker is all the change touches. The committed file was not refreshed.
+* **Library titles**, real `designer.design` runs with the deployed request shape (bass
+  management `lpf_fs` 80):
+
+  | Title | Material digest | Accepted | Confidence |
+  | --- | --- | --- | --- |
+  | 9 (2009) | `c942feb4…`, matches the deployed request | `flatten`: LowShelf 13.0 Hz +6.4 dB Q 0.72 | 0.97 |
+  | Beauty and the Beast (1991) | `8d98789b…` | LowShelf 13.8 Hz +2.4 dB, LowShelf 35.1 Hz +1.0 dB, PeakingEQ 24.4 Hz +4.6 dB | 0.95 |
+  | Crazy, Stupid, Love | `df2456f6…` | `flatten`: LowShelf 34.5 Hz +10.0 dB Q 0.79, PeakingEQ 28.6 Hz −7.6 dB Q 2.07 | 0.93 |
+  | Despicable Me 3 | `7cf1e523…` | LowShelf 28.2 Hz +1.6 dB, LowShelf 15.0 Hz +1.0 dB | 0.96 |
+
+  9 is the correction the handoff expected, and Beauty and the Beast is the cascade the
+  patch's second attempt found. Crazy, Stupid, Love's cascade looks odd until its corrected
+  curve is checked: the average goes from a steep fall below about 25 Hz to flat at about
+  −72 dB down to about 5 Hz. The cut shapes the shelf; it does not fight it.
+* **Carrie stays declined**: an 8.4 dB shortfall against 9.9 dB of ripple about a cubic
+  (10.3 about a line). Its judged band starts at 10 Hz, so its passband runs 4.3 octaves,
+  and the texture there is broadband, not a knee. Shortening the band would accept it. Nothing
+  measured here licenses doing that.
+
+### Caveat: the degree is a choice made on this data
+
+Degree 3 was picked from three degrees and a hinge after seeing the corpus and the library
+ratios. That is a modelling choice informed by the corpus, so the completion criterion's E10
+clause applies. Fresh validation should precede treating it as settled. The hinge at the
+crossover is the one variant with no free choice (its bend is the playback crossover). It
+leaves every corpus ratio as it was, but puts 9 at exactly 1.00x, so it does not fix the
+reported title.

beqforge-0.2.3/plans/texture-yardstick-sub-band.patch

@@ -0,0 +1,154 @@
+diff --git a/beqforge/pipeline.py b/beqforge/pipeline.py
+index 699762d..6a6b345 100644
+--- a/beqforge/pipeline.py
++++ b/beqforge/pipeline.py
+@@ -814,8 +814,21 @@ def mains_hum_notches(
+     return ()
+ 
+ 
++def _sub_feed_edge_hz(params: "PipelineParams") -> float:
++    """The top of the band the sub plays: the lower of the crossover and the sub-bus low-pass."""
++    return min(
++        corner
++        for corner in (params.playback.crossover_hz, params.playback.bus_lowpass_hz)
++        if corner is not None
++    )
++
++
+ def passband_ripple_db(
+-    material: Material, params: "PipelineParams", noise_floor_hz: float = math.nan
++    material: Material,
++    params: "PipelineParams",
++    noise_floor_hz: float = math.nan,
++    *,
++    in_sub_band: bool = False,
+ ) -> tuple[float, tuple[float, float]] | None:
+     """The programme's own texture where nothing is missing: crest-to-trough, dB, and where.
+ 
+@@ -823,6 +836,16 @@ def passband_ripple_db(
+     correction — the top of the judged band to the top of the analysis band — as the spread of
+     the curve about its own log-frequency trend, so a tilted passband is not read as ripple.
+ 
++    `in_sub_band` ends that passband at the sub feed's low-pass (`_sub_feed_edge_hz`) unless the
++    judged band already reaches past it. The mix's texture blocker asks for it: above the sub
++    edge the mix's shape is not texture the sub plays. In an LFE-led mix the level falls away
++    where the LFE channel's content ends, a knee a linear trend cannot remove, which read as
++    ripple and withheld a real deficit (9, 2009: 8.8 dB of "ripple" over 23-200 Hz against a
++    6.2 dB shortfall, 5.1 dB up to the 80 Hz crossover). Each channel's own rule
++    (`channels_missing_low_end`) keeps the whole passband: there the smaller yardstick judged
++    more channels short, grew counterfactual targets (Caught Stealing 4.3 -> 12.3 dB) and
++    admitted a broadband negative on the corpus.
++
+     Crest to trough, not a one-sided dip, because the reference sits near the 90th percentile
+     of the spectrum, on the crests: a shortfall measured from it spans the whole swing. On the
+     negative corpus (IMPROVEMENT_PLAN E2) every unfiltered title's low-end deficit came in
+@@ -841,7 +864,11 @@ def passband_ripple_db(
+         _judged_top_hz(anchor, params, noise_floor_hz),
+         params.diagnose.band_hz[1],
+     )
++    # a hum comb is recognised by its harmonics, so it is looked for over the whole passband
++    # even where the ripple is then measured on less of it: below 80 Hz only one is left
+     bands = (*params.exclude_bands_hz, *mains_hum_notches(freqs, response, low, high))
++    if in_sub_band and low < _sub_feed_edge_hz(params):
++        high = min(high, _sub_feed_edge_hz(params))
+     band = (freqs >= low) & (freqs <= high) & unexcluded(freqs, bands)
+     if band.sum() < 8:
+         return None
+@@ -1537,11 +1564,7 @@ def analyse(
+         # (Black Bag with LR4 @ 30 injected — plateau 50-83 Hz gone, content tracking to
+         # 9 Hz), and that low end is content to restore, not an absence of bass. NaN means
+         # every band tracked.
+-        sub_edge = min(
+-            corner
+-            for corner in (params.playback.crossover_hz, params.playback.bus_lowpass_hz)
+-            if corner is not None
+-        )
++        sub_edge = _sub_feed_edge_hz(params)
+         if region[0] >= sub_edge and diagnosis.noise_floor_hz >= sub_edge:
+             blockers.append(
+                 "no usable contiguous mix plateau in the band the sub plays: the mix's only "
+@@ -1550,7 +1573,9 @@ def analyse(
+                 f"programme (tracking stops at {diagnosis.noise_floor_hz:.1f} Hz), so there "
+                 "is no bass passband to restore towards; restoration withheld"
+             )
+-        texture = passband_ripple_db(material, params, diagnosis.noise_floor_hz)
++        texture = passband_ripple_db(
++            material, params, diagnosis.noise_floor_hz, in_sub_band=True
++        )
+         low_end = low_end_deficit_db(material, params, diagnosis.noise_floor_hz)
+         if texture is not None and low_end is not None:
+             ripple, (edge_low, edge_high) = texture
+diff --git a/tests/test_design_ripple_band.py b/tests/test_design_ripple_band.py
+new file mode 100644
+index 0000000..c0559b9
+--- /dev/null
++++ b/tests/test_design_ripple_band.py
+@@ -0,0 +1,68 @@
++"""The mix's texture yardstick is measured in the band the sub plays (9, 2009, 2026-10)."""
++
++import numpy as np
++from scipy import signal
++
++from beqforge.material import Material
++from beqforge.pipeline import PipelineParams, passband_ripple_db
++
++FS = 1000
++
++
++def _lfe_led(
++    high_pass_hz: float = 20.0, knee_hz: float = 70.0, seed: int = 5
++) -> Material:
++    """Noise high-passed at `high_pass_hz` whose level falls away above `knee_hz`.
++
++    The knee stands in for an LFE-led mix, where the level drops where the LFE channel's content
++    ends: real programme shape, but not texture the sub plays.
++    """
++    rng = np.random.default_rng(seed)
++    noise = rng.standard_normal(240 * FS)
++    bass = signal.sosfilt(
++        signal.butter(4, knee_hz, btype="low", fs=FS, output="sos"),
++        signal.sosfilt(
++            signal.butter(4, high_pass_hz, btype="high", fs=FS, output="sos"), noise
++        ),
++    )
++    mains = 0.05 * signal.sosfilt(
++        signal.butter(4, high_pass_hz, btype="high", fs=FS, output="sos"),
++        rng.standard_normal(noise.size),
++    )
++    return Material("lfe-led", FS, 0.01 * (bass + mains), {}, "complete_programme")
++
++
++def test_the_ripple_is_measured_up_to_the_sub_edge():
++    params = PipelineParams()
++    ripple = passband_ripple_db(_lfe_led(), params, in_sub_band=True)
++    assert ripple is not None
++    assert ripple[1][1] == params.playback.crossover_hz
++
++
++def test_a_knee_above_the_sub_edge_is_not_read_as_texture():
++    material = _lfe_led()
++    params = PipelineParams()
++    in_sub_band = passband_ripple_db(material, params, in_sub_band=True)
++    # what the yardstick is over the whole passband, as each channel's own rule measures it
++    to_band_top = passband_ripple_db(material, params)
++    assert in_sub_band is not None and to_band_top is not None
++    assert to_band_top[1][1] == params.diagnose.band_hz[1]
++    assert in_sub_band[0] < to_band_top[0] - 3.0
++
++
++def test_a_judged_band_past_the_sub_edge_keeps_the_analysis_band():
++    # a passband that only starts above the crossover: there is nothing below the sub edge to
++    # measure, so the yardstick is the one it always was
++    params = PipelineParams()
++    ripple = passband_ripple_db(
++        _lfe_led(high_pass_hz=110.0, knee_hz=400.0), params, in_sub_band=True
++    )
++    assert ripple is None or ripple[1][1] == params.diagnose.band_hz[1]
++
++
++def test_a_channel_s_own_rule_keeps_the_whole_passband():
++    # the per-channel texture rule: a smaller yardstick there judged more channels short and
++    # admitted a broadband negative on the corpus
++    params = PipelineParams()
++    ripple = passband_ripple_db(_lfe_led(), params)
++    assert ripple is not None and ripple[1][1] == params.diagnose.band_hz[1]

beqforge-0.2.3/tests/test_design_ripple_band.py

@@ -0,0 +1,56 @@
+"""The mix's texture yardstick is measured about a cubic, not a line (9, 2009, 2026-10)."""
+
+import numpy as np
+from scipy import signal
+
+from beqforge.material import Material
+from beqforge.pipeline import (
+    MIX_TEXTURE_TREND_DEGREE,
+    PipelineParams,
+    passband_ripple_db,
+)
+
+FS = 1000
+
+
+def _programme(knee_hz: float | None, seed: int = 5) -> Material:
+    """Noise high-passed at 20 Hz whose level falls away above `knee_hz`, if given.
+
+    The knee stands in for an LFE-led mix, where the level drops where the LFE channel's content
+    ends: real programme shape, but not texture the sub plays.
+    """
+    rng = np.random.default_rng(seed)
+    high_pass = signal.butter(4, 20.0, btype="high", fs=FS, output="sos")
+    bass = signal.sosfilt(high_pass, rng.standard_normal(240 * FS))
+    if knee_hz is not None:
+        bass = signal.sosfilt(
+            signal.butter(4, knee_hz, btype="low", fs=FS, output="sos"), bass
+        )
+    mains = 0.05 * signal.sosfilt(high_pass, rng.standard_normal(bass.size))
+    return Material("programme", FS, 0.01 * (bass + mains), {}, "complete_programme")
+
+
+def test_a_knee_above_the_crossover_is_trend_not_texture():
+    material, params = _programme(70.0), PipelineParams()
+    line = passband_ripple_db(material, params)
+    cubic = passband_ripple_db(material, params, trend_degree=MIX_TEXTURE_TREND_DEGREE)
+    assert line is not None and cubic is not None
+    assert cubic[0] < line[0] - 3.0
+
+
+def test_the_band_is_the_one_the_boundary_was_calibrated_on():
+    params = PipelineParams()
+    cubic = passband_ripple_db(
+        _programme(70.0), params, trend_degree=MIX_TEXTURE_TREND_DEGREE
+    )
+    assert cubic is not None and cubic[1][1] == params.diagnose.band_hz[1]
+
+
+def test_programme_without_a_knee_keeps_its_texture():
+    # the cubic must not explain away texture a line already measured: on broadband noise
+    # the two agree
+    material, params = _programme(None), PipelineParams()
+    line = passband_ripple_db(material, params)
+    cubic = passband_ripple_db(material, params, trend_degree=MIX_TEXTURE_TREND_DEGREE)
+    assert line is not None and cubic is not None
+    assert abs(cubic[0] - line[0]) < 0.25 * line[0]