beqforge 0.2.0__tar.gz → 0.2.2__tar.gz

beqforge-0.2.2/.dockerignore

@@ -0,0 +1,14 @@
+.git
+.venv
+**/__pycache__
+build
+dist
+data
+out
+charts
+plans
+docs
+tests
+tools/experiments
+*.run.json.gz
+*.beq

beqforge-0.2.2/.github/workflows/build-designer-image.yml

@@ -0,0 +1,119 @@
+name: Designer image
+
+# The designer as a container, beside a beqdesigner pipeline service (README, "Running the
+# designer in a container"). Every change to what goes into it is built and smoke-tested;
+# a vX.Y.Z tag also publishes linux/amd64 and linux/arm64 to GHCR as ghcr.io/<owner>/beqforge-designer.
+# A manual run with `publish` publishes the image of an existing release from a later commit,
+# only if the designer's runtime code is identical to that release's tag (as when the image
+# recipe arrived after the release).
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+    paths:
+      - 'packaging/designer/**'
+      - '.dockerignore'
+      - '.github/workflows/build-designer-image.yml'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'beq_common/**'
+      - 'beqforge/**'
+      - 'tools/designer_server.py'
+  pull_request:
+    paths:
+      - 'packaging/designer/**'
+      - '.dockerignore'
+      - '.github/workflows/build-designer-image.yml'
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Publish the image as beq_common.__version__ (its vX.Y.Z tag must exist, with identical designer code)
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: designer-image-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  image:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60   # the arm64 image builds under emulation
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0   # the release tags, for a manual publish's check
+      - name: Choose whether to publish
+        id: publish
+        shell: bash
+        run: |
+          if [[ "$GITHUB_REF" == refs/tags/* || "${{ inputs.publish }}" == true ]]; then
+            echo "publish=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Set image version
+        id: version
+        shell: bash
+        run: |
+          version="$(python3 -c "import re, pathlib; print(re.search(r'__version__ = \"([^\"]+)\"', pathlib.Path('beq_common/__init__.py').read_text()).group(1))")"
+          if [[ "$GITHUB_REF" == refs/tags/* && "$GITHUB_REF_NAME" != "v$version" ]]; then
+            echo "tag $GITHUB_REF_NAME does not match beq_common.__version__ $version" >&2
+            exit 1
+          fi
+          if [[ "$GITHUB_REF" != refs/tags/* && "${{ inputs.publish }}" == true ]]; then
+            # the image says it is release $version: what it runs must be exactly that release's
+            if ! git diff --quiet "v$version" HEAD -- beqforge beq_common tools/designer_server.py; then
+              echo "the designer code differs from v$version: tag a release instead" >&2
+              git diff --stat "v$version" HEAD -- beqforge beq_common tools/designer_server.py >&2
+              exit 1
+            fi
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+      - name: Build image for smoke test
+        run: |
+          docker build -f packaging/designer/Dockerfile -t beqforge-designer:smoke \
+            --build-arg VERSION="${{ steps.version.outputs.version }}" --build-arg REVISION="$GITHUB_SHA" .
+      - name: Health, and a design inline and by reference
+        run: python3 packaging/designer/smoke.py beqforge-designer:smoke
+      - uses: docker/setup-qemu-action@v4
+        if: steps.publish.outputs.publish == 'true'
+      - uses: docker/setup-buildx-action@v4
+        if: steps.publish.outputs.publish == 'true'
+      - name: Log in to GHCR
+        if: steps.publish.outputs.publish == 'true'
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Choose tags
+        id: tags
+        if: steps.publish.outputs.publish == 'true'
+        shell: bash
+        run: |
+          image="ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/beqforge-designer"
+          version="${{ steps.version.outputs.version }}"
+          tags="$image:$version"
+          if [[ ! "$version" =~ (a|b|rc|dev)[0-9]*$ ]]; then
+            tags="$tags,$image:latest"
+          fi
+          echo "tags=$tags" >> "$GITHUB_OUTPUT"
+      - name: Build and publish amd64 and arm64
+        if: steps.publish.outputs.publish == 'true'
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: packaging/designer/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.tags.outputs.tags }}
+          build-args: |
+            VERSION=${{ steps.version.outputs.version }}
+            REVISION=${{ github.sha }}

{beqforge-0.2.0 → beqforge-0.2.2}/.github/workflows/build-device-check.yml

@@ -2,9 +2,19 @@ name: Build device-check preview
 
 on:
   workflow_dispatch:
+  # only when something that affects the packaged executable changes
   push:
     branches:
       - '**'
+    paths:
+      - 'beqforge_device_check/**'
+      - 'beqforge-device-check.spec'
+      - 'tools/prepare_device_check_helper.py'
+      - 'tools/smoke_test_device_check.py'
+      - 'packaging/device-check/**'
+      - '.github/workflows/build-device-check.yml'
+      - 'pyproject.toml'
+      - 'uv.lock'
   pull_request:
     paths:
       - 'beqforge_device_check/**'
@@ -16,6 +26,11 @@ on:
       - 'pyproject.toml'
       - 'uv.lock'
 
+# a newer push to a branch supersedes its in-progress preview build
+concurrency:
+  group: device-check-preview-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
 
@@ -46,7 +61,7 @@ jobs:
             executable: beqforge-device-check
     steps:
       - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v10.2.0
+      - uses: astral-sh/setup-uv@v10.3.0
         with:
           enable-cache: true
       - name: Install Linux audio and USB libraries

{beqforge-0.2.0 → beqforge-0.2.2}/.github/workflows/build-executable.yml

@@ -25,7 +25,7 @@ jobs:
     steps:
       - name: Find successful tests for the tagged commit
         id: check
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             core.setOutput('reusable', 'false');
@@ -72,6 +72,8 @@ jobs:
     needs: previous_tests
     if: needs.previous_tests.outputs.reusable != 'true'
     uses: ./.github/workflows/tests.yml
+    # CODECOV_TOKEN, for the coverage upload
+    secrets: inherit
     permissions:
       contents: read
 
@@ -102,7 +104,7 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v10.2.0
+      - uses: astral-sh/setup-uv@v10.3.0
         with:
           enable-cache: true
       - name: Build wheel and source distribution
@@ -191,7 +193,7 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.2.0
+        uses: astral-sh/setup-uv@v10.3.0
         with:
           enable-cache: true
 

beqforge-0.2.2/.github/workflows/tests.yml

@@ -0,0 +1,140 @@
+name: Tests
+
+# Fits already control their own process parallelism. Avoid multiplying each worker
+# by a BLAS thread pool on the small hosted runners.
+env:
+  OPENBLAS_NUM_THREADS: '1'
+  OMP_NUM_THREADS: '1'
+  MKL_NUM_THREADS: '1'
+  VECLIB_MAXIMUM_THREADS: '1'
+
+on:
+  workflow_call:
+  push:
+    branches:
+      - '**'
+
+# A newer push to a feature branch supersedes its in-progress run. main and tag (release) runs are
+# grouped per commit so they are never cancelled or queued behind each other: a release reuses
+# main's result for the tagged commit.
+concurrency:
+  group: tests-${{ github.event_name }}-${{ github.ref }}-${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && github.sha || 'latest' }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/tags/') }}
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # feature branch pushes only test on Linux; main, tags (releases) and manual runs test all three
+        os: ${{ fromJSON(github.event_name == 'push' && startsWith(github.ref, 'refs/heads/') && github.ref != 'refs/heads/main' && '["ubuntu-latest"]' || '["ubuntu-latest", "macos-latest", "windows-latest"]') }}
+    steps:
+      - uses: actions/checkout@v7
+
+      # brew's and choco's default ffmpeg both lack the libsoxr resampler tools/extract.py
+      # prefers, unlike Ubuntu's apt package — but extract.py now detects that at runtime and
+      # falls back to ffmpeg's default resampler, so any ordinary ffmpeg install is fine here.
+      # apt mirrors have repeatedly taken from 8 to over 50 minutes to serve ffmpeg's dependencies on
+      # hosted runners, so use a static build from GitHub releases (which also includes libsoxr) and
+      # only fall back to apt if that download fails.
+      - name: Install ffmpeg (Linux)
+        if: runner.os == 'Linux'
+        timeout-minutes: 10
+        run: |
+          if command -v ffmpeg >/dev/null && command -v ffprobe >/dev/null; then
+            exit 0
+          fi
+          url=https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linux64-gpl.tar.xz
+          if curl -fsSL --retry 3 --max-time 300 "$url" -o "$RUNNER_TEMP/ffmpeg.tar.xz"; then
+            mkdir -p "$RUNNER_TEMP/ffmpeg"
+            tar -xJf "$RUNNER_TEMP/ffmpeg.tar.xz" -C "$RUNNER_TEMP/ffmpeg" --strip-components=1
+            echo "$RUNNER_TEMP/ffmpeg/bin" >> "$GITHUB_PATH"
+          else
+            # the Azure mirror is the slowest, use Ubuntu's archive mirror
+            sudo sed -i 's|http://azure.archive.ubuntu.com/ubuntu|http://archive.ubuntu.com/ubuntu|g' /etc/apt/apt-mirrors.txt
+            sudo apt-get update
+            sudo apt-get install -y --no-install-recommends ffmpeg
+          fi
+
+      - name: Install ffmpeg (macOS)
+        if: runner.os == 'macOS'
+        run: brew install ffmpeg
+
+      - name: Install ffmpeg (Windows)
+        if: runner.os == 'Windows'
+        run: choco install ffmpeg -y
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --all-groups --extra designer
+
+      # the device-check tests run in their own job below, in parallel, with the extra installed
+      - name: Run tests
+        run: uv run --extra designer pytest -n auto --durations=25 --ignore-glob='tests/test_device_check_*.py' --cov --cov-report=xml
+
+      - name: Upload coverage
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@v7.1.1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          disable_search: true
+          flags: designer,${{ runner.os }}
+          name: designer-${{ runner.os }}
+
+  device-check:
+    name: Device check (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # feature branch pushes only test on Linux; main, tags (releases) and manual runs test all three
+        os: ${{ fromJSON(github.event_name == 'push' && startsWith(github.ref, 'refs/heads/') && github.ref != 'refs/heads/main' && '["ubuntu-latest"]' || '["ubuntu-latest", "macos-latest", "windows-latest"]') }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: true
+
+      # without the extra, most of these tests skip on importorskip('pyfar') rather than fail
+      - name: Install dependencies
+        run: uv sync --locked --all-groups --extra device-check
+
+      - name: Run device-check tests
+        shell: bash
+        run: uv run --extra device-check pytest -n auto --durations=25 tests/test_device_check_*.py --cov --cov-report=xml
+
+      - name: Upload coverage
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@v7.1.1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          disable_search: true
+          flags: device-check,${{ runner.os }}
+          name: device-check-${{ runner.os }}
+
+  package-profiles:
+    name: Install profile (${{ matrix.profile }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        profile: [base, designer, optimiser, device-check, all]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: true
+      - name: Build the single distribution
+        run: uv build --out-dir dist
+      - name: Verify isolated wheel installation and command
+        run: uv run --no-project --python 3.13 python tools/smoke_test_install.py --wheel-dir dist --profile '${{ matrix.profile }}'

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

@@ -55,11 +55,16 @@ importing them; use an isolated worktree for simultaneous experiments.
 
 The root build configuration includes every workflow and the optimiser's bundled seed in one
 wheel and source distribution. `.github/workflows/tests.yml` checks isolated dependency
-profiles. `.github/workflows/build-executable.yml` builds release executables and distributions;
+profiles and runs the suite in parallel (`pytest -n auto`, so tests must not share mutable state
+or fixed ports), with coverage (`--cov`, configured in `pyproject.toml`, `multiprocessing`
+children included) uploaded to Codecov by each test job using the `CODECOV_TOKEN` secret;
+release runs inherit it. Feature branch pushes test on Linux only and a newer push cancels the branch's
+previous run; `main`, tags and manual runs test Linux, macOS and Windows and are never cancelled. `.github/workflows/build-executable.yml` builds release executables and distributions;
 tag pushes publish to PyPI after validation and successful executable builds. Tags must match
 the shared version exactly (`vX.Y.Z`). Manual runs build artifacts without publishing.
 PyPI uses the `pypi` environment and Trusted Publishing; setup details are in the README.
-Device-check preview executable packaging has its own workflow, not a separate Python release.
+Device-check preview executable packaging has its own workflow, not a separate Python release;
+it only runs when device-check code, packaging or dependencies change.
 
 ## Conventions
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: beqforge
-Version: 0.2.0
+Version: 0.2.2
 Summary: Audio-derived BEQ design, published filter optimisation and DSP validation
 License-File: LICENCE.md
 Requires-Python: <3.15,>=3.13
@@ -248,6 +248,42 @@ 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.
 
+### Running the designer in a container
+
+`ghcr.io/3ll3d00d/beqforge-designer:<version>` runs `beqforge serve-designer` for a beqdesigner
+pipeline service beside it (beqdesigner's `docker/compose.example.yaml` runs both). It is
+published for linux/amd64 and linux/arm64 by `.github/workflows/build-designer-image.yml` on
+each `vX.Y.Z` tag, from the same commit as that release; `latest` follows the newest release.
+A manual run of that workflow with `publish` set publishes the current version's image from a
+later commit, and refuses unless the designer's code is identical to that version's tag (0.2.0's
+image was published this way, the recipe having arrived after the release).
+Pin a version: a catalogue designed over several days should come from one designer build.
+
+The image's defaults, all overridable with the environment variables above:
+
+| Setting | Default | Mount |
+| --- | --- | --- |
+| `BEQFORGE_HOST`, `BEQFORGE_PORT` | `0.0.0.0`, `8420` | |
+| `BEQFORGE_SHARED_ROOT` | `/work` | the pipeline's work directory, so audio is sent by reference |
+| `BEQFORGE_CACHE_DIR` | `/cache` | a volume, so a restart keeps the stage cache |
+| `BEQFORGE_RECORD_DIR` | unset | set it (for example to `/records`, and mount that) to keep run records |
+
+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.
+
+Build and check it locally from the repository root:
+
+```bash
+docker build -f packaging/designer/Dockerfile -t beqforge-designer .
+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.
+
 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.0 → beqforge-0.2.2}/README.md

@@ -222,6 +222,42 @@ 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.
 
+### Running the designer in a container
+
+`ghcr.io/3ll3d00d/beqforge-designer:<version>` runs `beqforge serve-designer` for a beqdesigner
+pipeline service beside it (beqdesigner's `docker/compose.example.yaml` runs both). It is
+published for linux/amd64 and linux/arm64 by `.github/workflows/build-designer-image.yml` on
+each `vX.Y.Z` tag, from the same commit as that release; `latest` follows the newest release.
+A manual run of that workflow with `publish` set publishes the current version's image from a
+later commit, and refuses unless the designer's code is identical to that version's tag (0.2.0's
+image was published this way, the recipe having arrived after the release).
+Pin a version: a catalogue designed over several days should come from one designer build.
+
+The image's defaults, all overridable with the environment variables above:
+
+| Setting | Default | Mount |
+| --- | --- | --- |
+| `BEQFORGE_HOST`, `BEQFORGE_PORT` | `0.0.0.0`, `8420` | |
+| `BEQFORGE_SHARED_ROOT` | `/work` | the pipeline's work directory, so audio is sent by reference |
+| `BEQFORGE_CACHE_DIR` | `/cache` | a volume, so a restart keeps the stage cache |
+| `BEQFORGE_RECORD_DIR` | unset | set it (for example to `/records`, and mount that) to keep run records |
+
+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.
+
+Build and check it locally from the repository root:
+
+```bash
+docker build -f packaging/designer/Dockerfile -t beqforge-designer .
+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.
+
 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.0 → beqforge-0.2.2}/TODO.md

@@ -32,7 +32,7 @@ are retained so records and code comments remain traceable. Completed items are
 | 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. |
+| 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. |

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

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

{beqforge-0.2.0 → beqforge-0.2.2}/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. Single-threaded (`http.server.HTTPServer`, not `ThreadingHTTPServer`) on purpose: 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. Costs nothing real — the contract is one synchronous POST per `design()` call. 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); `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 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/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. |