beqforge 0.2.3__tar.gz → 0.2.4__tar.gz

beqforge-0.2.4/.gitattributes

@@ -0,0 +1 @@
+*.cmd text eol=crlf

{beqforge-0.2.3 → beqforge-0.2.4}/.github/workflows/build-executable.yml

@@ -226,6 +226,14 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Attach the Windows designer launcher
+        if: runner.os == 'Windows' && startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v3
+        with:
+          files: packaging/designer/beqforge-designer.cmd
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
   publish:
     name: Publish Python package to PyPI
     needs: [validated_tests, package, build, create_release]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: beqforge
-Version: 0.2.3
+Version: 0.2.4
 Summary: Audio-derived BEQ design, published filter optimisation and DSP validation
 License-File: LICENCE.md
 Requires-Python: <3.15,>=3.13
@@ -187,6 +187,12 @@ naming the array, rather than a design decline. Inline requests remain supported
 logs read, parse, decode, design and response timings; `tools/experiments/request_timing.py`
 measures cold and warm requests.
 
+**Several designs at once.** `--workers N` (1-8, default 1) runs N designs at once, each in
+its own worker process; further requests queue. `GET /health` reports it as `parallel`, so a
+caller can send each server as many designs as it takes rather than be configured with that
+number. Each design's fit pool gets an equal share of the machine's cores (`BEQ_FIT_WORKERS`,
+if set, stays each design's own). 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
 environment list. `--help` lists the variable beside each option. Other subcommands retain
@@ -207,6 +213,7 @@ their existing CLI configuration.
 | `--record-dir` | `BEQFORGE_RECORD_DIR` | path |
 | `--cache-dir` | `BEQFORGE_CACHE_DIR` | path |
 | `--shared-root` | `BEQFORGE_SHARED_ROOT` | path |
+| `--workers` | `BEQFORGE_WORKERS` | integer, 1-8 |
 | `--quiet` | `BEQFORGE_QUIET` | boolean |
 
 Booleans accept `true`/`false`, `yes`/`no`, `on`/`off` or `1`/`0`, ignoring case.
@@ -270,9 +277,9 @@ The image's defaults, all overridable with the environment variables above:
 
 It runs as uid/gid 1000 (`--build-arg PUID=… PGID=…` to change), which must be able to write
 the shared root and the cache: the server checks both with a write at startup. Its
-`HEALTHCHECK` asks `/health`, which answers while a design runs: designs run in a separate
-worker process, one at a time, so a caller sending several at once queues them; size the
-caller's timeout for that. `docker stop` stops a design in progress.
+`HEALTHCHECK` asks `/health`, which answers while a design runs: designs run in separate
+worker processes, `BEQFORGE_WORKERS` (default 1) at a time, so a caller sending more at once
+queues them; size the caller's timeout for that. `docker stop` stops a design in progress.
 
 Build and check it locally from the repository root:
 
@@ -284,6 +291,38 @@ python3 packaging/designer/smoke.py beqforge-designer
 The smoke script checks `/health` and one design inline and one by reference;
 `tests/test_designer_image.py` runs the same check against an in-process server.
 
+### Running the designer on Windows
+
+The release's `beqforge-windows-x86_64.exe` runs the same server natively, for a beqdesigner
+container (or install) that calls out to a Windows machine. Put `beqforge-designer.cmd`, which
+is attached to the same release (source: `packaging/designer/beqforge-designer.cmd`), beside the
+exe and double-click it, or run the exe directly:
+
+```bat
+beqforge-windows-x86_64.exe serve-designer --host 0.0.0.0 --port 8420 ^
+  --shared-root D:\beq\work --cache-dir %LOCALAPPDATA%\beqforge\cache
+```
+
+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`.
+
+* **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
+  networks.
+* **Shared root.** For audio by reference, set `BEQFORGE_SHARED_ROOT` (or edit the commented
+  line in the launcher) to the Windows folder bind-mounted into beqdesigner's container as its
+  work directory. Without it, beqdesigner must send audio inline.
+* **beqdesigner's side.** Under Docker Desktop on the same machine, register
+  `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`.
+* **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.
+
+### Building and releasing
+
 For a machine without Python/`uv`, a standalone `beqforge` executable (every subcommand,
 including `serve-designer`) is built for Linux/macOS/Windows by
 `.github/workflows/build-executable.yml` on every `vX.Y.Z` tag, and attached to the matching

{beqforge-0.2.3 → beqforge-0.2.4}/README.md

@@ -161,6 +161,12 @@ naming the array, rather than a design decline. Inline requests remain supported
 logs read, parse, decode, design and response timings; `tools/experiments/request_timing.py`
 measures cold and warm requests.
 
+**Several designs at once.** `--workers N` (1-8, default 1) runs N designs at once, each in
+its own worker process; further requests queue. `GET /health` reports it as `parallel`, so a
+caller can send each server as many designs as it takes rather than be configured with that
+number. Each design's fit pool gets an equal share of the machine's cores (`BEQ_FIT_WORKERS`,
+if set, stays each design's own). 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
 environment list. `--help` lists the variable beside each option. Other subcommands retain
@@ -181,6 +187,7 @@ their existing CLI configuration.
 | `--record-dir` | `BEQFORGE_RECORD_DIR` | path |
 | `--cache-dir` | `BEQFORGE_CACHE_DIR` | path |
 | `--shared-root` | `BEQFORGE_SHARED_ROOT` | path |
+| `--workers` | `BEQFORGE_WORKERS` | integer, 1-8 |
 | `--quiet` | `BEQFORGE_QUIET` | boolean |
 
 Booleans accept `true`/`false`, `yes`/`no`, `on`/`off` or `1`/`0`, ignoring case.
@@ -244,9 +251,9 @@ The image's defaults, all overridable with the environment variables above:
 
 It runs as uid/gid 1000 (`--build-arg PUID=… PGID=…` to change), which must be able to write
 the shared root and the cache: the server checks both with a write at startup. Its
-`HEALTHCHECK` asks `/health`, which answers while a design runs: designs run in a separate
-worker process, one at a time, so a caller sending several at once queues them; size the
-caller's timeout for that. `docker stop` stops a design in progress.
+`HEALTHCHECK` asks `/health`, which answers while a design runs: designs run in separate
+worker processes, `BEQFORGE_WORKERS` (default 1) at a time, so a caller sending more at once
+queues them; size the caller's timeout for that. `docker stop` stops a design in progress.
 
 Build and check it locally from the repository root:
 
@@ -258,6 +265,38 @@ python3 packaging/designer/smoke.py beqforge-designer
 The smoke script checks `/health` and one design inline and one by reference;
 `tests/test_designer_image.py` runs the same check against an in-process server.
 
+### Running the designer on Windows
+
+The release's `beqforge-windows-x86_64.exe` runs the same server natively, for a beqdesigner
+container (or install) that calls out to a Windows machine. Put `beqforge-designer.cmd`, which
+is attached to the same release (source: `packaging/designer/beqforge-designer.cmd`), beside the
+exe and double-click it, or run the exe directly:
+
+```bat
+beqforge-windows-x86_64.exe serve-designer --host 0.0.0.0 --port 8420 ^
+  --shared-root D:\beq\work --cache-dir %LOCALAPPDATA%\beqforge\cache
+```
+
+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`.
+
+* **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
+  networks.
+* **Shared root.** For audio by reference, set `BEQFORGE_SHARED_ROOT` (or edit the commented
+  line in the launcher) to the Windows folder bind-mounted into beqdesigner's container as its
+  work directory. Without it, beqdesigner must send audio inline.
+* **beqdesigner's side.** Under Docker Desktop on the same machine, register
+  `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`.
+* **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.
+
+### Building and releasing
+
 For a machine without Python/`uv`, a standalone `beqforge` executable (every subcommand,
 including `serve-designer`) is built for Linux/macOS/Windows by
 `.github/workflows/build-executable.yml` on every `vX.Y.Z` tag, and attached to the matching

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

@@ -43,6 +43,7 @@ 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 | open | 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). |
 
 ## Review evidence
 

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

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

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

@@ -43,7 +43,7 @@ still holds: no other API, no other service, and the server is a thin transport
 | `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. |
 | `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 one 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. One worker keeps designs serial (the contract is one synchronous POST per `design()` call); a worker that dies answers 500 and is replaced. 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` and `shared_root`. |
+| `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 `filters.FIT_WORKERS // N` (`fit_share`) unless `BEQ_FIT_WORKERS` is set: 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/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. |

beqforge-0.2.4/packaging/designer/beqforge-designer.cmd

@@ -0,0 +1,33 @@
+@echo off
+rem Runs the beqforge designer for beqdesigner on Windows: `beqforge serve-designer`, with the
+rem container image's defaults (README, "Running the designer on Windows"). Keep this file
+rem beside the release's beqforge-windows-x86_64.exe and double-click it, or run it from a
+rem prompt with any extra serve-designer options, e.g. `beqforge-designer.cmd --record-dir D:\beq\records`.
+rem
+rem Every BEQFORGE_* variable already set in the environment wins over the defaults below.
+setlocal
+
+rem beqdesigner's work directory, as this machine sees it, so audio arrives by reference rather
+rem than inline. Uncomment and point it at the folder mounted into beqdesigner's container.
+rem if not defined BEQFORGE_SHARED_ROOT set "BEQFORGE_SHARED_ROOT=D:\beq\work"
+
+rem How many titles to design at once, if this machine can take more than one (0.2.4 on).
+rem if not defined BEQFORGE_WORKERS set "BEQFORGE_WORKERS=2"
+
+if not defined BEQFORGE_HOST set "BEQFORGE_HOST=0.0.0.0"
+if not defined BEQFORGE_PORT set "BEQFORGE_PORT=8420"
+if not defined BEQFORGE_CACHE_DIR set "BEQFORGE_CACHE_DIR=%LOCALAPPDATA%\beqforge\cache"
+
+set "EXE=%~dp0beqforge-windows-x86_64.exe"
+if not exist "%EXE%" set "EXE=%~dp0beqforge.exe"
+if not exist "%EXE%" (
+    echo beqforge-windows-x86_64.exe was not found beside %~nx0
+    pause
+    exit /b 1
+)
+
+"%EXE%" serve-designer %*
+set "STATUS=%ERRORLEVEL%"
+rem keep the window open on a startup error, so a double-click shows why
+if not "%STATUS%"=="0" pause
+exit /b %STATUS%

{beqforge-0.2.3 → beqforge-0.2.4}/plans/done-design-and-pipeline.md

@@ -748,6 +748,37 @@ beside the answer or the decline (probe unchanged; no decision touched).
     caller's; `beqforge_revision` is already in every response for it.
 
 
+## Several designs at once, advertised on `/health` (18 October 2026)
+
+A Windows machine that could design two titles at once was added beside the container as a
+second endpoint, and the only way to use it was two servers on two ports: one server had a
+single design worker. Saying how many each endpoint takes in beqdesigner's profile also put a
+fact about the designer's host in the caller's configuration.
+
+`serve-designer --workers N` (`BEQFORGE_WORKERS`, 1-8, the range beqdesigner accepts for an
+endpoint's `parallel`) now runs N `_DesignWorker`s, each still one spawned, single-threaded
+process. A request takes the next idle worker and waits for one when none is, so arrival order
+is kept and a worker that dies fails only its own request. `/health` gains `"parallel": N` for
+a caller to size its sends from; beqdesigner was sent the caller-side proposal. With N > 1 each
+worker's fit pool is `filters.FIT_WORKERS // N` (`fit_share`), so N designs do not each claim
+the whole machine; an explicit `BEQ_FIT_WORKERS` is left as each design's own. `_run_fits`
+returns results in submission order from fixed seeds, so pool size moves timing and never an
+answer. Nothing under `beqforge/` changed, so the decision regression probe does not apply.
+
+* **Checks.** New tests: with two workers a quick request is answered while a real design is
+  still running on the other (the same test fails with one worker, so it distinguishes them),
+  `/health` reports `parallel`, a count outside 1-8 is refused by the server and the CLI, the
+  option comes from the environment, and the fit share. Server, startup, image and parallel-fit
+  tests: 61 passed. `tools/smoke_test_exe.py` now starts the executable with `--workers 2` and
+  requires `parallel: 2`. Its three requests alternate between the workers, so both design for
+  real inside the frozen build and the cache hit is one worker reusing the other's entries. A
+  Linux PyInstaller build passed it, with no process left after shutdown. Windows and macOS
+  are covered by the release workflow's smoke test, not run here.
+* **Windows packaging.** `packaging/designer/beqforge-designer.cmd` starts the release's
+  Windows executable with the container's defaults and is attached to each release; the README
+  gains "Running the designer on Windows".
+
+
 ## The designer server answers `/health` during a design (17 October 2026)
 
 A deployed image went unhealthy while it designed correctly. `serve-designer` was a plain

beqforge-0.2.4/plans/parameter-space-optimisation.md

@@ -0,0 +1,75 @@
+# Optimising a filter's parameters for several device profiles at once
+
+**Status: design, not built.** A request from beqdesigner (October 2026), for a feature in its main window: a filter
+designer picks one or more device profiles, sees what each does to the filter, and asks for the filter to be optimised
+before it is published. The person who owns both projects decided that the search belongs here, in `beqoptimiser`, and
+beqdesigner only provides the interface. Parameter search is already listed as a follow-up in
+[F2-catalogue-filter-optimisation.md](F2-catalogue-filter-optimisation.md).
+
+## What is different from `optimise()`
+
+`optimise()` searches the coefficients of one cascade for one rate and precision, and returns custom SOS. This request
+needs:
+
+1. **Parameters out, not coefficients.** The result is each section's `freq`, `q` and `gain` (and its type unchanged).
+   A BEQ is published and loaded as parameters: beqdesigner's projects and exports, the catalogue, and ezbeq (which
+   rebuilds RBJ coefficients from the parameters at each device's rate when it has none published for it) all carry
+   parameters. Optimised parameters therefore need no new catalogue schema and reach every consumer as they are.
+2. **Several profiles jointly.** The same parameters are realised on every device. The search minimises the worst
+   matching-band error across all the profiles the caller passes (a minimax), so a change that helps one device cannot
+   quietly make another worse. The result reports each profile's error before and after.
+3. **Representable parameters.** Only values beqdesigner can show and the exports keep: `freq` to 0.01 Hz, `q` (and a
+   shelf's `S`) to 0.0001, `gain` to 0.01 dB. Search on that grid, or round and re-validate, so the result is exactly
+   what is published.
+
+## Proposed interface
+
+```python
+optimise_parameters(
+    sections,                 # the cascade as authored: beqoptimiser.core.Section (type, freq, q, gain), in order
+    *,
+    profiles,                 # [(rate, precision), ...]: 48000 or 96000, with Float32() or FixedPoint(i, f)
+    settings=None,            # Settings: margin, band, plus the parameter bounds below
+) -> ParameterResult
+```
+
+`ParameterResult` carries the outcome (with the same `replacement`/`improvement`/`no_replacement` rules as
+`optimise()`), the new sections when there is one, and per profile: the original error, the candidate's error and its
+guard (out-of-band) error, with the numerical version and settings for provenance.
+
+* **Reference:** each section's ideal float64 RBJ response, from the authored parameters, as now.
+* **Realised:** for each profile, the coefficients computed from the candidate parameters at that rate in float64,
+  then stored with that profile's precision (`quantise`), as a device that receives parameters (or coefficients
+  computed from them) would hold them.
+* **Bounds:** the parameters may only move as far as keeps the filter the author's: proposed defaults of ±1% in
+  frequency, ±2% in Q and ±0.1 dB in gain per section, configurable. A result outside them is not a correction of
+  the same filter.
+* **Sections it cannot change:** the request may contain other biquads (pass filters, a gain stage). They stay
+  fixed but count in the cascade's response; a cascade with nothing searchable returns `no_replacement`.
+
+## Open points for this repository to decide
+
+* **Whose RBJ:** the coefficients must be computed as the consumers compute them. beqdesigner (`model/iir.py`),
+  `beq_common.biquad` and ezbeq each implement the cookbook; check that they agree, including the shelf Q/S conversion,
+  to the precision a profile can resolve. If they do not, name the one a profile models.
+* **Search method:** a coordinate or pattern search on the parameter grid, a scalar minimiser per parameter as now, or
+  something else; deterministic, bounded and cacheable as `optimise()` is.
+* **Whether it ever helps:** benchmark against direct-coefficient search on the catalogue's float32/96 kHz worst cases
+  (e.g. the 5 Hz Q 6 peak the 2x4 HD pilot measured). Parameter search may recover little where the coefficient grid is
+  coarse; the outcome rules already report that honestly as `no_replacement`.
+
+## What beqdesigner will build around it
+
+* Device profiles: one per device it exports to (miniDSP HD-class: float32 at 96 kHz; earlier miniDSPs: Q5.23 fixed
+  point at 48 kHz; HTP-1 and JRiver compute in double precision, so nothing to show), plus profiles a user defines
+  (rate and storage). It uses `beqoptimiser`'s `Float32`/`FixedPoint` and `magnitude` for part (a).
+* Part (a), now: the main chart shows the filter as each chosen profile realises it, and its error against the ideal.
+* Part (b), after this ships: an *Optimise for devices* action on the filter, which calls `optimise_parameters` with the
+  ticked profiles, shows the before/after errors per profile and lets the designer accept the new parameters.
+
+## Completion criteria
+
+* `optimise_parameters` in `beqoptimiser` with tests covering: both rates, both precisions, the joint (minimax)
+  objective protecting each profile, the parameter grid and bounds, fixed non-searchable sections, and cache identity.
+* A short benchmark against `optimise()` on the catalogue report's worst float32 cases, recorded here.
+* Released in a `beqforge` version beqdesigner can pin.

{beqforge-0.2.3 → beqforge-0.2.4}/tests/test_design_designer_server.py

@@ -20,6 +20,7 @@ import http.client
 import json
 import logging
 import threading
+import time
 from dataclasses import replace
 
 import numpy as np
@@ -149,7 +150,12 @@ def _known_filter_request(duration_s: float = 150.0, seed: int = 101) -> dict:
 def test_health_check(server) -> None:
     status, body = _request(server, "GET", "/health")
     assert status == 200
-    assert body == {"status": "ok", "contract_version": "1.2", "shared_root": False}
+    assert body == {
+        "status": "ok",
+        "contract_version": "1.2",
+        "shared_root": False,
+        "parallel": 1,
+    }
 
 
 def test_unknown_get_path_is_404(server) -> None:
@@ -250,7 +256,7 @@ def test_health_answers_while_a_design_runs(server) -> None:
 def test_a_dead_worker_is_a_500_and_the_next_request_gets_a_new_one() -> None:
     httpd, thread = _serve(PipelineParams(strategies=("flatten",)), None)
     try:
-        for process in list(httpd.worker._pool._processes.values()):
+        for process in list(httpd.workers[0]._pool._processes.values()):
             process.kill()
             process.join(timeout=10)
         status, body = _request(
@@ -267,8 +273,52 @@ def test_a_dead_worker_is_a_500_and_the_next_request_gets_a_new_one() -> None:
         _stop(httpd, thread)
 
 
-def _serve(params: PipelineParams, cache, shared_root=None):
-    """A server of its own, with its own settings and its own worker process."""
+def test_a_second_worker_designs_while_the_first_is_busy() -> None:
+    """With two workers a quick request is answered while a slow one is still designing;
+    with one it would queue behind it. `/health` says how many it takes at once."""
+    httpd, thread = _serve(PipelineParams(strategies=("flatten",)), None, workers=2)
+    try:
+        assert _request(httpd.server_address, "GET", "/health")[1]["parallel"] == 2
+        slow = []
+        designing = threading.Thread(
+            target=lambda: slow.append(
+                _request(
+                    httpd.server_address,
+                    "POST",
+                    DESIGN_PATH,
+                    body=_known_filter_request(),
+                    timeout=DESIGN_TIMEOUT_S,
+                )
+            )
+        )
+        designing.start()
+        try:
+            time.sleep(0.5)  # let the slow request take a worker first
+            status, body = _request(
+                httpd.server_address, "POST", DESIGN_PATH, _no_evidence_request()
+            )
+            assert status == 200
+            assert body["decline_reason"] == "channel_evidence_unavailable"
+            assert designing.is_alive()
+        finally:
+            designing.join(timeout=DESIGN_TIMEOUT_S)
+        assert slow[0][0] == 200
+    finally:
+        _stop(httpd, thread)
+
+
+def test_a_worker_count_outside_the_callers_range_is_refused() -> None:
+    for workers in (0, 9):
+        with pytest.raises(ValueError, match="workers must be 1-8"):
+            DesignServer(
+                ("127.0.0.1", 0),
+                DesignSettings(PipelineParams(strategies=("flatten",))),
+                workers=workers,
+            )
+
+
+def _serve(params: PipelineParams, cache, shared_root=None, workers: int = 1):
+    """A server of its own, with its own settings and its own worker processes."""
     # These tests exercise transport and cache identity/reuse, not section-budget
     # escalation. Still run the real pipeline with a bounded numerical search;
     # test_accepts_a_real_injected_rolloff_over_http retains the full budget.
@@ -277,6 +327,7 @@ def _serve(params: PipelineParams, cache, shared_root=None):
         DesignSettings(
             replace(params, max_sections=1), cache=cache, shared_root=shared_root
         ),
+        workers=workers,
     )
     thread = threading.Thread(target=httpd.serve_forever, daemon=True)
     thread.start()
@@ -436,7 +487,12 @@ def test_health_says_whether_references_are_accepted(tmp_path) -> None:
     finally:
         _stop(httpd, thread)
     assert status == 200
-    assert body == {"status": "ok", "contract_version": "1.2", "shared_root": True}
+    assert body == {
+        "status": "ok",
+        "contract_version": "1.2",
+        "shared_root": True,
+        "parallel": 1,
+    }
 
 
 def test_a_request_by_reference_answers_as_the_same_request_inline(tmp_path) -> None:

{beqforge-0.2.3 → beqforge-0.2.4}/tests/test_designer_server_startup.py

@@ -113,6 +113,7 @@ def test_every_server_option_can_come_from_environment(startup, monkeypatch, tmp
         "RECORD_DIR": str(tmp_path / "records"),
         "CACHE_DIR": str(tmp_path / "cache"),
         "SHARED_ROOT": str(tmp_path / "shared"),
+        "WORKERS": "2",
         "QUIET": "1",
     }
     for name, value in settings.items():
@@ -134,7 +135,7 @@ def test_every_server_option_can_come_from_environment(startup, monkeypatch, tmp
     assert args.quiet is True
     (address, settings), options = constructor.call_args
     assert address == ("127.0.0.2", 9123)
-    assert options == {"log_level": logging.WARNING}
+    assert options == {"log_level": logging.WARNING, "workers": 2}
     params = settings.params
     assert params.realisation.fs == 48000
     assert params.realisation.coefficient_bits == 24
@@ -177,7 +178,7 @@ def test_cli_replaces_environment_values_including_repeated_and_boolean_options(
     )
     (address, settings), options = constructor.call_args
     assert address == ("127.0.0.1", 8123)
-    assert options == {"log_level": logging.INFO}
+    assert options == {"log_level": logging.INFO, "workers": 1}
     params = settings.params
     assert params.strategies == ("flatten", "counterfactual")
     assert params.exclude_bands_hz == ((30.0, 32.0),)
@@ -207,6 +208,8 @@ def test_false_environment_boolean(startup, monkeypatch, value):
         ("EXCLUDE", "[18, 22]", "must be a JSON array of pairs"),
         ("EXCLUDE", '[[18, "invalid"]]', "invalid float value"),
         ("QUIET", "perhaps", "BEQFORGE_QUIET must be true/false"),
+        ("WORKERS", "0", "workers must be 1-8"),
+        ("WORKERS", "9", "workers must be 1-8"),
     ],
 )
 def test_invalid_environment_fails_before_listening(
@@ -244,7 +247,21 @@ def test_help_lists_every_environment_option_even_with_invalid_environment(
         "RECORD_DIR",
         "CACHE_DIR",
         "SHARED_ROOT",
+        "WORKERS",
         "QUIET",
     ):
         assert f"BEQFORGE_{name}" in output
     constructor.assert_not_called()
+
+
+def test_concurrent_designs_share_the_fit_pool(monkeypatch):
+    monkeypatch.delenv("BEQ_FIT_WORKERS", raising=False)
+    monkeypatch.setattr(designer_server.filters, "FIT_WORKERS", 7)
+    assert designer_server.fit_share(1) is None
+    assert designer_server.fit_share(2) == 3
+    assert designer_server.fit_share(8) == 1
+
+
+def test_an_explicit_fit_pool_is_each_designs_own(monkeypatch):
+    monkeypatch.setenv("BEQ_FIT_WORKERS", "4")
+    assert designer_server.fit_share(2) is None