beqforge 0.2.5__tar.gz → 0.2.7__tar.gz

{beqforge-0.2.5 → beqforge-0.2.7}/.github/workflows/build-executable.yml

@@ -34,9 +34,10 @@ jobs:
               return;
             }
             const deadline = Date.now() + 15 * 60 * 1000;
-            try {
-              while (true) {
-                const runs = await github.paginate(github.rest.actions.listWorkflowRuns, {
+            while (true) {
+              let runs;
+              try {
+                runs = await github.paginate(github.rest.actions.listWorkflowRuns, {
                   ...context.repo,
                   workflow_id: 'tests.yml',
                   head_sha: context.sha,
@@ -44,27 +45,34 @@ jobs:
                   event: 'push',
                   per_page: 100,
                 });
-                const matching = runs.filter(run =>
-                  run.head_sha === context.sha && run.head_branch === 'main' && run.event === 'push'
-                );
-                const passed = matching.find(run =>
-                  run.status === 'completed' && run.conclusion === 'success'
-                );
-                if (passed) {
-                  core.info(`Reusing successful main tests: ${passed.html_url}`);
-                  await core.summary.addLink('Reused main test run', passed.html_url).write();
-                  core.setOutput('reusable', 'true');
+              } catch (error) {
+                // a transient API failure is no reason to rerun the whole suite, so keep trying until the deadline
+                if (Date.now() >= deadline) {
+                  core.warning(`Unable to check main tests; running fresh release tests: ${error.message}`);
                   return;
                 }
-                if (!matching.some(run => run.status !== 'completed') || Date.now() >= deadline) {
-                  core.info('No successful main test run available; running fresh release tests.');
-                  return;
-                }
-                core.info('Main tests are still running; checking again in 30 seconds.');
+                core.info(`Unable to check main tests (${error.message}); trying again in 30 seconds.`);
                 await new Promise(resolve => setTimeout(resolve, 30_000));
+                continue;
+              }
+              const matching = runs.filter(run =>
+                run.head_sha === context.sha && run.head_branch === 'main' && run.event === 'push'
+              );
+              const passed = matching.find(run =>
+                run.status === 'completed' && run.conclusion === 'success'
+              );
+              if (passed) {
+                core.info(`Reusing successful main tests: ${passed.html_url}`);
+                await core.summary.addLink('Reused main test run', passed.html_url).write();
+                core.setOutput('reusable', 'true');
+                return;
+              }
+              if (!matching.some(run => run.status !== 'completed') || Date.now() >= deadline) {
+                core.info('No successful main test run available; running fresh release tests.');
+                return;
               }
-            } catch (error) {
-              core.warning(`Unable to check main tests; running fresh release tests: ${error.message}`);
+              core.info('Main tests are still running; checking again in 30 seconds.');
+              await new Promise(resolve => setTimeout(resolve, 30_000));
             }
 
   tests:

{beqforge-0.2.5 → beqforge-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: beqforge
-Version: 0.2.5
+Version: 0.2.7
 Summary: Audio-derived BEQ design, published filter optimisation and DSP validation
 License-File: LICENCE.md
 Requires-Python: <3.15,>=3.13
@@ -146,7 +146,7 @@ straight off disk. A stale record is skipped with a warning rather than failing
 
 `beqforge serve-designer` runs this pipeline as a live, HTTP-bound filter designer for
 [`beqdesigner`](https://github.com/3ll3d00d/beqdesigner), implementing its
-`design/designer-interface.md` v1.2 contract (§7.1's HTTP binding) rather than the file-based
+`design/designer-interface.md` v1.4 contract (§7.1's HTTP binding) rather than the file-based
 `.npz` → `design` → `--beq` export flow above:
 
 ```bash
@@ -183,7 +183,8 @@ An unusable directory causes a startup error naming the option and path.
 relative to that root plus the SHA-256 of its decoded column, instead of inline base64 audio.
 The server resolves, decodes and checks each reference; an unusable reference gets HTTP 422
 naming the array, rather than a design decline. Inline requests remain supported.
-`GET /health` reports `contract_version` and whether `shared_root` is enabled. Each request
+`GET /health` reports `contract_version`, whether `shared_root` is enabled, and 1.4's design
+version, settings and build. Each request
 logs read, parse, decode, design and response timings; `tools/experiments/request_timing.py`
 measures cold and warm requests.
 
@@ -192,7 +193,9 @@ its own worker process; further requests queue. `GET /health` reports it as `par
 caller can send each server as many designs as it takes rather than be configured with that
 number. Concurrent designs share the machine's logical processors, SMT threads included, each
 at most the width one design uses alone (`BEQ_FIT_WORKERS`, if set, stays each design's own).
-The share changes how long a fit takes, never its answer.
+`--cores N` caps the processors the designs use between them, for a machine with other work to
+do: concurrent designs split N evenly, and N must be at least `--workers`. The share changes
+how long a fit takes, never its answer.
 
 Every `serve-designer` configuration option can also be set through an environment variable.
 Explicit CLI options take precedence; for repeatable options, CLI values replace the entire
@@ -215,6 +218,7 @@ their existing CLI configuration.
 | `--cache-dir` | `BEQFORGE_CACHE_DIR` | path |
 | `--shared-root` | `BEQFORGE_SHARED_ROOT` | path |
 | `--workers` | `BEQFORGE_WORKERS` | integer, 1-8 |
+| `--cores` | `BEQFORGE_CORES` | integer, at least `--workers` |
 | `--quiet` | `BEQFORGE_QUIET` | boolean |
 
 Booleans accept `true`/`false`, `yes`/`no`, `on`/`off` or `1`/`0`, ignoring case.
@@ -247,15 +251,42 @@ diagnosis, in this order:
   carried `bass_management`, otherwise the assumed LR4 80 Hz model, and it says which).
   Clipping is reported, never used to reject a filter. The typed `gain_reduction_db` field is
   filled only when the request carries `bass_management`, as the contract requires.
+* `fit` — how closely the filter, as the device plays it, delivers the boost the content
+  supports: the typical error, the share of that boost within ±0.5 dB, and the worst miss,
+  where and which way. It is a match to that target, not a verdict on whether the target is
+  right; `correction` says how much of what is missing that target restores.
 * `alternatives` — why each other candidate was rejected or not chosen.
 
 The commentary then continues with `target_notes`, `verdict_notes` (what the checks themselves
-noticed), `effective_params` and `beqforge_revision` (which build answered). The raw
+noticed), `effective_params` and `beqforge_revision` (which build answered). The same fit is
+in typed fields (contract 1.3): `residual_db` is the worst absolute error over
+`residual_band_hz`, the band the fit was actually scored on, measured on the published filter
+as the device plays it; `residual_at_hz` and `residual_direction` say where and which way;
+`residual_rms_db` and `residual_within_tolerance` (against `residual_tolerance_db`) weight
+each frequency by the boost asked for there, as `confidence` does. The raw
 recovered and shaping fractions are kept in the run record, not the response. A decline's `decline_message` gives the reason first, then `| found: …` with
 the same diagnosis, then the build in brackets. `beqforge/designer.py` is the
 pure `design(request) -> response` adapter, independently testable without a socket;
 `tools/designer_server.py` is the HTTP transport around it.
 
+**Which answer a build gives (contract 1.4).** Every response, design or decline, and
+`GET /health` carry `design_version`, `design_settings` and `designer_build`, whatever
+`contract_version` the request names. `design_version` is an integer bumped only by a change
+that can alter an answer for an unchanged request: the candidates, the rejected designs, a
+decline or a fit figure. Wording, speed and
+packaging don't bump it, so the executable and the image of one release report the same
+version and different `designer_build`s (the string also in `beqforge_revision`). Releases
+before it: 0.0.x and 0.1.0 are 0, 0.2.0 is 1, 0.2.1 is 2, 0.2.2 is 3, and 0.2.3 to 0.2.5
+are 4, as is 0.2.7, the first release to report it. One version is one algorithm, not one
+filter on every machine: the `counterfactual` and `parametric` fits can land on a different
+filter on a different processor, so compare versions, never figures. `design_settings` is a 12-hex digest of the server-wide settings that can change an
+answer (`--strategy`, `--exclude`, `--goal-tolerance`, `--goal-tilt`, `--content-edge`,
+`--device-rate`, `--coefficient-bits`, `--integer-bits`) that differ from their defaults, so a
+server started with none of them always sends the same digest. `/health` also reports those
+settings as `design_settings_detail`, for reading when two designers disagree. A caller keys
+each title on (`design_version`, `design_settings`) to tell which titles a new release would
+answer differently.
+
 ### Running the designer in a container
 
 `ghcr.io/3ll3d00d/beqforge-designer:<version>` runs `beqforge serve-designer` for a beqdesigner
@@ -308,8 +339,10 @@ beqforge-windows-x86_64.exe serve-designer --host 0.0.0.0 --port 8420 ^
 ```
 
 The launcher sets the image's defaults through the environment variables above, each only if
-not already set: `BEQFORGE_HOST=0.0.0.0`, `BEQFORGE_PORT=8420` and
-`BEQFORGE_CACHE_DIR=%LOCALAPPDATA%\beqforge\cache`. Arguments pass through to `serve-designer`.
+not already set: `BEQFORGE_HOST=0.0.0.0`, `BEQFORGE_PORT=8420`,
+`BEQFORGE_CACHE_DIR=%LOCALAPPDATA%\beqforge\cache` and
+`BEQFORGE_RECORD_DIR=%LOCALAPPDATA%\beqforge\records`, so every request's run record is kept.
+Arguments pass through to `serve-designer`.
 
 * **Listen on the network.** The CLI's default host is `127.0.0.1`, which a container cannot
   reach; the launcher uses `0.0.0.0`. Windows Firewall asks the first time: allow private
@@ -321,7 +354,8 @@ not already set: `BEQFORGE_HOST=0.0.0.0`, `BEQFORGE_PORT=8420` and
   `http://host.docker.internal:8420/design`; from another machine, use this one's LAN address.
   Check `http://<address>:8420/health` from there first.
 * **Several at once.** Set `BEQFORGE_WORKERS` (or pass `--workers 2`) for a machine that can
-  design more than one title at a time; `/health` reports it as `parallel`.
+  design more than one title at a time; `/health` reports it as `parallel`. To leave room for
+  other work, set `BEQFORGE_CORES` to the most processors the designer may use between them.
 * **The rest.** The exe is unsigned, so SmartScreen warns on first run. `serve-designer` does not need `ffmpeg`. Close the window, or
   press Ctrl+C, to stop.
 
@@ -338,7 +372,8 @@ one locally: `uv pip install pyinstaller && uv run pyinstaller beqforge.spec`.
 
 The same workflow builds and checks the Python wheel and source distribution, verifies all
 five dependency profiles, and reuses a successful branch-push run of `tests.yml` on `main`
-at the exact tagged commit. If matching tests are still running, it waits up to 15 minutes;
+at the exact tagged commit. If matching tests are still running, or GitHub's API fails to answer, it
+keeps checking for up to 15 minutes;
 without a successful result, it runs the reusable tests workflow against the release commit.
 GitHub release creation and executable builds require those tests to pass on Linux, macOS
 and Windows, including device-check tests and isolated dependency profiles. PyPI publication

{beqforge-0.2.5 → beqforge-0.2.7}/README.md

@@ -120,7 +120,7 @@ straight off disk. A stale record is skipped with a warning rather than failing
 
 `beqforge serve-designer` runs this pipeline as a live, HTTP-bound filter designer for
 [`beqdesigner`](https://github.com/3ll3d00d/beqdesigner), implementing its
-`design/designer-interface.md` v1.2 contract (§7.1's HTTP binding) rather than the file-based
+`design/designer-interface.md` v1.4 contract (§7.1's HTTP binding) rather than the file-based
 `.npz` → `design` → `--beq` export flow above:
 
 ```bash
@@ -157,7 +157,8 @@ An unusable directory causes a startup error naming the option and path.
 relative to that root plus the SHA-256 of its decoded column, instead of inline base64 audio.
 The server resolves, decodes and checks each reference; an unusable reference gets HTTP 422
 naming the array, rather than a design decline. Inline requests remain supported.
-`GET /health` reports `contract_version` and whether `shared_root` is enabled. Each request
+`GET /health` reports `contract_version`, whether `shared_root` is enabled, and 1.4's design
+version, settings and build. Each request
 logs read, parse, decode, design and response timings; `tools/experiments/request_timing.py`
 measures cold and warm requests.
 
@@ -166,7 +167,9 @@ its own worker process; further requests queue. `GET /health` reports it as `par
 caller can send each server as many designs as it takes rather than be configured with that
 number. Concurrent designs share the machine's logical processors, SMT threads included, each
 at most the width one design uses alone (`BEQ_FIT_WORKERS`, if set, stays each design's own).
-The share changes how long a fit takes, never its answer.
+`--cores N` caps the processors the designs use between them, for a machine with other work to
+do: concurrent designs split N evenly, and N must be at least `--workers`. The share changes
+how long a fit takes, never its answer.
 
 Every `serve-designer` configuration option can also be set through an environment variable.
 Explicit CLI options take precedence; for repeatable options, CLI values replace the entire
@@ -189,6 +192,7 @@ their existing CLI configuration.
 | `--cache-dir` | `BEQFORGE_CACHE_DIR` | path |
 | `--shared-root` | `BEQFORGE_SHARED_ROOT` | path |
 | `--workers` | `BEQFORGE_WORKERS` | integer, 1-8 |
+| `--cores` | `BEQFORGE_CORES` | integer, at least `--workers` |
 | `--quiet` | `BEQFORGE_QUIET` | boolean |
 
 Booleans accept `true`/`false`, `yes`/`no`, `on`/`off` or `1`/`0`, ignoring case.
@@ -221,15 +225,42 @@ diagnosis, in this order:
   carried `bass_management`, otherwise the assumed LR4 80 Hz model, and it says which).
   Clipping is reported, never used to reject a filter. The typed `gain_reduction_db` field is
   filled only when the request carries `bass_management`, as the contract requires.
+* `fit` — how closely the filter, as the device plays it, delivers the boost the content
+  supports: the typical error, the share of that boost within ±0.5 dB, and the worst miss,
+  where and which way. It is a match to that target, not a verdict on whether the target is
+  right; `correction` says how much of what is missing that target restores.
 * `alternatives` — why each other candidate was rejected or not chosen.
 
 The commentary then continues with `target_notes`, `verdict_notes` (what the checks themselves
-noticed), `effective_params` and `beqforge_revision` (which build answered). The raw
+noticed), `effective_params` and `beqforge_revision` (which build answered). The same fit is
+in typed fields (contract 1.3): `residual_db` is the worst absolute error over
+`residual_band_hz`, the band the fit was actually scored on, measured on the published filter
+as the device plays it; `residual_at_hz` and `residual_direction` say where and which way;
+`residual_rms_db` and `residual_within_tolerance` (against `residual_tolerance_db`) weight
+each frequency by the boost asked for there, as `confidence` does. The raw
 recovered and shaping fractions are kept in the run record, not the response. A decline's `decline_message` gives the reason first, then `| found: …` with
 the same diagnosis, then the build in brackets. `beqforge/designer.py` is the
 pure `design(request) -> response` adapter, independently testable without a socket;
 `tools/designer_server.py` is the HTTP transport around it.
 
+**Which answer a build gives (contract 1.4).** Every response, design or decline, and
+`GET /health` carry `design_version`, `design_settings` and `designer_build`, whatever
+`contract_version` the request names. `design_version` is an integer bumped only by a change
+that can alter an answer for an unchanged request: the candidates, the rejected designs, a
+decline or a fit figure. Wording, speed and
+packaging don't bump it, so the executable and the image of one release report the same
+version and different `designer_build`s (the string also in `beqforge_revision`). Releases
+before it: 0.0.x and 0.1.0 are 0, 0.2.0 is 1, 0.2.1 is 2, 0.2.2 is 3, and 0.2.3 to 0.2.5
+are 4, as is 0.2.7, the first release to report it. One version is one algorithm, not one
+filter on every machine: the `counterfactual` and `parametric` fits can land on a different
+filter on a different processor, so compare versions, never figures. `design_settings` is a 12-hex digest of the server-wide settings that can change an
+answer (`--strategy`, `--exclude`, `--goal-tolerance`, `--goal-tilt`, `--content-edge`,
+`--device-rate`, `--coefficient-bits`, `--integer-bits`) that differ from their defaults, so a
+server started with none of them always sends the same digest. `/health` also reports those
+settings as `design_settings_detail`, for reading when two designers disagree. A caller keys
+each title on (`design_version`, `design_settings`) to tell which titles a new release would
+answer differently.
+
 ### Running the designer in a container
 
 `ghcr.io/3ll3d00d/beqforge-designer:<version>` runs `beqforge serve-designer` for a beqdesigner
@@ -282,8 +313,10 @@ beqforge-windows-x86_64.exe serve-designer --host 0.0.0.0 --port 8420 ^
 ```
 
 The launcher sets the image's defaults through the environment variables above, each only if
-not already set: `BEQFORGE_HOST=0.0.0.0`, `BEQFORGE_PORT=8420` and
-`BEQFORGE_CACHE_DIR=%LOCALAPPDATA%\beqforge\cache`. Arguments pass through to `serve-designer`.
+not already set: `BEQFORGE_HOST=0.0.0.0`, `BEQFORGE_PORT=8420`,
+`BEQFORGE_CACHE_DIR=%LOCALAPPDATA%\beqforge\cache` and
+`BEQFORGE_RECORD_DIR=%LOCALAPPDATA%\beqforge\records`, so every request's run record is kept.
+Arguments pass through to `serve-designer`.
 
 * **Listen on the network.** The CLI's default host is `127.0.0.1`, which a container cannot
   reach; the launcher uses `0.0.0.0`. Windows Firewall asks the first time: allow private
@@ -295,7 +328,8 @@ not already set: `BEQFORGE_HOST=0.0.0.0`, `BEQFORGE_PORT=8420` and
   `http://host.docker.internal:8420/design`; from another machine, use this one's LAN address.
   Check `http://<address>:8420/health` from there first.
 * **Several at once.** Set `BEQFORGE_WORKERS` (or pass `--workers 2`) for a machine that can
-  design more than one title at a time; `/health` reports it as `parallel`.
+  design more than one title at a time; `/health` reports it as `parallel`. To leave room for
+  other work, set `BEQFORGE_CORES` to the most processors the designer may use between them.
 * **The rest.** The exe is unsigned, so SmartScreen warns on first run. `serve-designer` does not need `ffmpeg`. Close the window, or
   press Ctrl+C, to stop.
 
@@ -312,7 +346,8 @@ one locally: `uv pip install pyinstaller && uv run pyinstaller beqforge.spec`.
 
 The same workflow builds and checks the Python wheel and source distribution, verifies all
 five dependency profiles, and reuses a successful branch-push run of `tests.yml` on `main`
-at the exact tagged commit. If matching tests are still running, it waits up to 15 minutes;
+at the exact tagged commit. If matching tests are still running, or GitHub's API fails to answer, it
+keeps checking for up to 15 minutes;
 without a successful result, it runs the reusable tests workflow against the release commit.
 GitHub release creation and executable builds require those tests to pass on Linux, macOS
 and Windows, including device-check tests and isolated dependency profiles. PyPI publication

{beqforge-0.2.5 → beqforge-0.2.7}/TODO.md

@@ -30,7 +30,6 @@ are retained so records and code comments remain traceable. Completed items are
 | 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). |
@@ -43,7 +42,8 @@ are retained so records and code comments remain traceable. Completed items are
 | 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). |
-| 27 | Parameter-space optimisation for several profiles | implemented; release pending | `beqoptimiser.optimise_parameters` built and benchmarked (18 October 2026): within margin on 21/25 and 10/25 of the worst 48/96 kHz float32 entries against coefficient search's 20/25 and 16/25; see [the outcome](plans/parameter-space-optimisation.md#outcome-18-october-2026). Done once released in a version beqdesigner can pin. Originally: beqdesigner's main window will let a filter designer optimise a filter for chosen device profiles before publishing, in freq/Q/gain terms (a BEQ is published and loaded as parameters, so no catalogue schema change), minimising the worst error across all chosen profiles at once. The search belongs in `beqoptimiser`, beside `optimise()`; beqdesigner builds the interface. See [the request](plans/parameter-space-optimisation.md). |
+| 27 | Keep run records and logs by default | open | `serve-designer` keeps no run record and no log file unless told to, so the Windows designer's 432 library titles (111 declines) have no records and can be reviewed only from their responses. Default records and a rotating log to the platform's per-user data directory (as the `.cmd` already does for the cache), set and declare `/records` in the image, report `record_dir` on `/health`. See [the handoff](plans/default-record-and-log-locations.md). |
+| 28 | Fit sensitivity to arithmetic | open | The same request can get a different filter on a different processor. On the synthetic BW4 24 Hz title, `counterfactual` gave 2 sections here and 3 on Linux and macOS CI; `parametric`'s boost was 15.21 dB on this AVX-512 machine, 15.78 dB with Haswell BLAS kernels and 16.49 dB on CI. `flatten` matched everywhere. It's repeatable on one machine, so last-digit differences grow into a different local optimum. Measure it on real titles first: run the baseline set under `OPENBLAS_CORETYPE=Haswell` (or on another CPU) and compare verdicts and corrected curves. Then decide whether the fit needs a deterministic tie-break or a conditioning fix, or whether only the golden's coverage does. See [the correction](plans/design-version.md#correction-after-the-v026-release-tests). |
 
 ## Review evidence
 
@@ -92,10 +92,6 @@ Evidence behind the order and the parked decisions:
   filtered/1 reached 5.6 dB over 0.28 octave. Real-title candidates stayed below 0.5 dB.
   Audit this with steep policy; it is not evidence specifically of single-bin holes or
   permission to add a blanket gate.
-* [`designer._to_design_candidate`](beqforge/designer.py) forwards `fit_error_db` and the
-  run's residual band, while [`filters._fit_structure`](beqforge/filters.py) returns a
-  target-error/device-drift objective and [`design._result`](beqforge/design.py) recomputes
-  pure target error. The actual fit score band can widen beyond the reported one.
 * The sibling [`designer-interface.md`](../beqdesigner/design/designer-interface.md)
   §§2–4 already adopts clipping cost, bass management, ordinal confidence, non-parametric
   residuals and decline/report rules. It deliberately excludes device preference.
@@ -124,20 +120,6 @@ supplying a dict is not enough to claim it was modelled. No hardware capture is
 these software comparisons. Caller propagation requires a change in beqdesigner, outside
 this repo; both its batch job and library call omit the available argument today.
 
-### Residual reporting
-
-`Candidate.fit_error_db` reaches the response's `residual_db`. For fitted candidates it is
-normally the larger of target error and exact-coefficient quantisation change; after pruning
-it can be pure target error. The contract already permits residuals for every method with an
-explicit target and defines them as maximum absolute target error. Recompute the reported
-error from the canonical published cascade against its priced target on a stated band; make
-the evaluation rate and coefficient treatment explicit. Carry or recompute the actual band:
-`_fit_all` can widen it above `params.residual_band_hz`, and parametric proposals carry their
-own effective design settings. Keep the optimisation objective, drift screen and escalation
-unchanged in a reporting fix. Changing what `residual_target_db` compares against is a
-separate decision change and needs the full regression workflow. A small residual says the
-fit matched the constructed target, not that the target is correct.
-
 ### Fresh validation protocol and steep-filter policy
 
 The legacy corpus is development evidence after repeated tuning, not a held-out estimate.

{beqforge-0.2.5 → beqforge-0.2.7}/beq_common/__init__.py

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

{beqforge-0.2.5 → beqforge-0.2.7}/beqforge/AGENTS.md

@@ -40,10 +40,10 @@ still holds: no other API, no other service, and the server is a thin transport
 | `beqforge/record.py` | The run record — a fingerprinted, gzipped JSON of everything a run produced, written every run. Ours, not beqdesigner's. |
 | `beqforge/beqd.py` | Export to a `.beq` beqdesigner project. A separate job from the record: idiomatic in their UI, allowed to be lossy. |
 | `beqforge/cli.py` | `beqforge <subcommand> ...` — the installed entry point. Strips the subcommand off argv and hands the rest to the matching script in `tools/` unchanged. |
-| `beqforge/explain.py` | The plain-language account a designer response leads with — `found` (reference plateau, which channels carry it and which are silent, down to where there is real bass content, judged band, goal), `correction` (the cascade, then frequency by frequency what was wanted, what the content supports and before → after), `clipping` (the sub-feed peak and how far to turn the sub down, on the request's or the assumed bass management) and `alternatives` (why each other candidate lost). Reads the `Report`; measures and decides nothing. |
-| `beqforge/designer.py` | The `design(request) -> response` adapter between beqdesigner's `designer-interface.md` v1.1 and `beqforge.pipeline.run` — request/response dataclasses (1.1: every candidate the judge failed goes back in `rejected` with its failures, review only, beside the answer or the decline), wire-format (de)serialisation and the field-by-field mapping onto `Report`/`Candidate`/`Verdict`. Also `validate_response`, an independent re-implementation of beqdesigner's own §3-§5 rules (that repo isn't importable — PyQt6), called by the server before a response ever goes on the wire. Pure and independently testable; no socket. |
+| `beqforge/explain.py` | The plain-language account a designer response leads with — `found` (reference plateau, which channels carry it and which are silent, down to where there is real bass content, judged band, goal), `correction` (the cascade, then frequency by frequency what was wanted, what the content supports and before → after), `clipping` (the sub-feed peak and how far to turn the sub down, on the request's or the assumed bass management), `fit` (how closely the filter as played delivers the boost the content supports — a match to the target, not a verdict on it) and `alternatives` (why each other candidate lost). Reads the `Report`; measures and decides nothing. |
+| `beqforge/designer.py` | The `design(request) -> response` adapter between beqdesigner's `designer-interface.md` v1.1 and `beqforge.pipeline.run` — request/response dataclasses (1.1: every candidate the judge failed goes back in `rejected` with its failures, review only, beside the answer or the decline; 1.3: `residual_db` and its companions come from `Candidate.target_fit`, never `fit_error_db`; 1.4: `design_version` (`DESIGN_VERSION`, bumped only by a change that can alter an answer, guarded by `tests/test_design_golden.py`), `design_settings` (`design_settings_digest`, the non-default server settings that can change an answer) and `designer_build` on every response), wire-format (de)serialisation and the field-by-field mapping onto `Report`/`Candidate`/`Verdict`. Also `validate_response`, an independent re-implementation of beqdesigner's own §3-§5 rules (that repo isn't importable — PyQt6), called by the server before a response ever goes on the wire. Pure and independently testable; no socket. |
 | `tools/design_beq.py` | **The entry point.** One command, a filter and its reasoning. `--charts DIR` for the pictures; writes a `.run.json.gz` record beside the material unless `--no-record`. |
-| `tools/designer_server.py` | `beqforge serve-designer` — the HTTP transport (`designer-interface.md` §7.1) around `beqforge/designer.py`. Server-wide flags for device realisation/strategies/exclusions; everything per-title comes from the request. A `ThreadingHTTPServer`, so `/health` answers during a design, with every design run in a long-lived worker process started with "spawn" (`_DesignWorker`): the fitter forks worker processes (`beqforge.filters.PARALLEL_FITS`) when a fit escalates past one section count, and forking a multi-threaded process risks a deadlock, so the process that forks must stay single-threaded — the worker's log records come back over a `SimpleQueue`, not a `Queue`, for that reason. A worker designs one title at a time; `--workers N` (1-8) runs N of them, each request taking the next idle one, and `/health` reports N as `parallel` so a caller can size its sends from the designer. With N > 1 each worker's fit pool is the logical processors less one, divided by N and capped at `filters.FIT_WORKERS` (`fit_share`), unless `BEQ_FIT_WORKERS` is set: concurrent designs are what can use SMT threads, and pool size changes timing, never an answer. A worker that dies answers 500 and is replaced; the others carry on. SIGTERM shuts down like Ctrl-C, stopping the worker's process group, fit pool included. Every response names its build (`beqforge_revision`); `--record-dir DIR` also writes each request's run record, named by a digest of the request audio, so a review-queue entry can be replayed. `--cache-dir DIR` keeps the stage cache there (`cache.DirStore`, one file per entry, atomic): a repeat request for a title skips the analysis — 110 s cold, 50 s warm on a 2-hour 8-channel title. Each request logs a timing line (read, parse, decode, design, respond, queued); `tools/experiments/request_timing.py` reports them. `--shared-root DIR` accepts audio by reference (contract 1.2, beqdesigner's `design/designer-by-reference.md` §3): an array names a WAV relative to DIR plus the SHA-256 of its decoded column, and `beqforge/reference.py` resolves, decodes and checks it; one that cannot be honoured is a 422 naming the array, never a decline. `GET /health` reports `contract_version`, `shared_root` and `parallel`. |
+| `tools/designer_server.py` | `beqforge serve-designer` — the HTTP transport (`designer-interface.md` §7.1) around `beqforge/designer.py`. Server-wide flags for device realisation/strategies/exclusions; everything per-title comes from the request. A `ThreadingHTTPServer`, so `/health` answers during a design, with every design run in a long-lived worker process started with "spawn" (`_DesignWorker`): the fitter forks worker processes (`beqforge.filters.PARALLEL_FITS`) when a fit escalates past one section count, and forking a multi-threaded process risks a deadlock, so the process that forks must stay single-threaded — the worker's log records come back over a `SimpleQueue`, not a `Queue`, for that reason. A worker designs one title at a time; `--workers N` (1-8) runs N of them, each request taking the next idle one, and `/health` reports N as `parallel` so a caller can size its sends from the designer. With N > 1 each worker's fit pool is the logical processors less one, divided by N and capped at `filters.FIT_WORKERS` (`fit_share`), unless `BEQ_FIT_WORKERS` is set; `--cores N` instead caps the designs' total at N, split evenly, still at most `filters.FIT_WORKERS` each: concurrent designs are what can use SMT threads, and pool size changes timing, never an answer. A worker that dies answers 500 and is replaced; the others carry on. SIGTERM shuts down like Ctrl-C, stopping the worker's process group, fit pool included. Every response names its build (`beqforge_revision`); `--record-dir DIR` also writes each request's run record, named by a digest of the request audio, so a review-queue entry can be replayed. `--cache-dir DIR` keeps the stage cache there (`cache.DirStore`, one file per entry, atomic): a repeat request for a title skips the analysis — 110 s cold, 50 s warm on a 2-hour 8-channel title. Each request logs a timing line (read, parse, decode, design, respond, queued); `tools/experiments/request_timing.py` reports them. `--shared-root DIR` accepts audio by reference (contract 1.2, beqdesigner's `design/designer-by-reference.md` §3): an array names a WAV relative to DIR plus the SHA-256 of its decoded column, and `beqforge/reference.py` resolves, decodes and checks it; one that cannot be honoured is a 422 naming the array, never a decline. `GET /health` reports `contract_version`, `shared_root`, `parallel`, and 1.4's `design_version`, `design_settings`, `design_settings_detail` and `designer_build`. |
 | `tools/replay.py` | Redraw charts and export to beqdesigner from a record — no rerun, no extraction. Refuses on a stale record unless `--force`. |
 | `tools/extract.py` | ffmpeg → 1 kHz per-channel `.npz`. Requires an explicit supported channel layout; preserves layout provenance. Needs no beqdesigner. |
 | `tools/summarise.py` | Sanity-check an extraction before using it. |
@@ -203,6 +203,16 @@ open questions it resolves. An item with no recorded outcome is not done.
 
 ## Gotchas
 
+* A change that can alter an answer for an unchanged request (candidates, rejected designs, a
+  decline or a 1.3 fit figure) bumps `designer.DESIGN_VERSION` and regenerates
+  `tests/fixtures/design_golden.json` (`BEQFORGE_REGENERATE_GOLDEN=1 uv run pytest
+  tests/test_design_golden.py`) in the same commit. Callers decide what to redesign from it.
+  Wording, speed, packaging and new outputs don't bump it. If the probe shows a moved verdict
+  or target, the golden will usually fail too, but it covers only a few synthetic requests:
+  a bump follows from what the change can do, not from whether the golden noticed. It leaves
+  out `counterfactual` and `parametric` because their fits differ across processors
+  (TODO, "Fit sensitivity to arithmetic"): regenerating it on one machine doesn't make those
+  hold on CI.
 * RBJ biquad formulae exist twice — `biquad.py`'s class hierarchy and `filters.py`'s
   `_sos_from_parameters`. Fix both or neither; the test asserting they agree is what keeps that
   honest.
@@ -425,18 +435,19 @@ least `min_judge_octaves` above the floor — no fixed top (historical review T6
 
 ### Publication, playback and verification
 
-* **Robustness is measured five ways, and they answer different questions.** Do not add one
+* **Robustness is measured six ways, and they answer different questions.** Do not add one
   to another, or compare one against a limit meant for another:
 
   | Quantity | What it measures | Where, over what |
   | --- | --- | --- |
   | Fit objective (`_fit_structure`'s cost) | the larger of the worst error against the target and the worst change exact-coefficient device quantisation makes to the response | the optimiser's raw parameters, over the fit's scoring band (`residual_band_hz`, widened to cover placements) |
-  | `fit_error_db` / designer `residual_db` | that objective — **except** that when `_prune` drops a section it becomes the pure worst error against the target, without the quantisation term. Two meanings in one field (TODO 5); the escalation's `residual_target_db` compares against it | as above |
+  | `fit_error_db` | that objective — **except** that when `_prune` drops a section it becomes the pure worst error against the target, without the quantisation term. Two meanings in one field; the escalation's `residual_target_db` compares against it, so it is left alone. Record-only outside the fitter, never in the response | as above |
+  | `TargetFit` / designer `residual_db` and its 1.3 companions | the cascade that plays against the target it was fitted to: worst absolute error, where and which way, RMS and share within `fit_tolerance_db` both weighted by the boost the target asks for. Reported, never gated; a match to the target, not evidence the target is right | published parameters, quantised coefficients at the device rate, design grid, over the band the fit was actually scored on (`_fit_band_hz`, or `residual_band_hz` for `parametric`) |
   | Drift, p90 (`_published_drift`, `Verdict.drift_db`) | the 90th percentile, over `drift_samples` jitters of the *published* parameters by their rounding step, of the worst change quantisation makes — how fragile the neighbourhood is, not what the published filter does | published parameters (since the F1 follow-up both use them), 3-400 Hz design grid |
   | Exposure (`_exposure_db`) | the fallback's ranking when no fit reaches the residual target: the residual, plus the drift if over `max_drift_db`. A sampled heuristic, not a bound on the published response | as its two terms |
   | `device_error_db` and the corrected curve | what the device will actually do: the exact published, quantised response against the unquantised one (`device_error_db`), and that response applied to the programme (`verify`) — the only one that is not a model | published parameters, quantised coefficients, design grid / the programme |
 
-  Strict Jury stability (`unstable_sections`) is separate from all five and is a veto: a
+  Strict Jury stability (`unstable_sections`) is separate from all six and is a veto: a
   cascade that is unstable at its published, quantised coefficients is never accepted, and its
   drift and exposure are infinite.