beqforge 0.2.4__tar.gz → 0.2.5__tar.gz

{beqforge-0.2.4 → beqforge-0.2.5}/.github/workflows/build-designer-image.yml

@@ -1,15 +1,16 @@
 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.
+# designer in a container"). Every change to what goes into it is built and smoke-tested.
+# A release publishes linux/amd64 and linux/arm64 to GHCR as ghcr.io/<owner>/beqforge-designer:
+# build-executable.yml calls this for a vX.Y.Z tag once the release tests have passed, as it
+# does for the executables and PyPI, so an image never ships ahead of its tests.
 # 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'
@@ -30,6 +31,8 @@ on:
         description: Publish the image as beq_common.__version__ (its vX.Y.Z tag must exist, with identical designer code)
         type: boolean
         default: false
+  # the release: build-executable.yml, from a tag, after its test gate
+  workflow_call:
 
 permissions:
   contents: read

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

@@ -234,6 +234,18 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  image:
+    name: Publish designer image
+    needs: [validated_tests, package]
+    # see create_release for why the needed results are checked explicitly
+    if: >-
+      !cancelled() && startsWith(github.ref, 'refs/tags/') &&
+      needs.validated_tests.result == 'success' && needs.package.result == 'success'
+    uses: ./.github/workflows/build-designer-image.yml
+    permissions:
+      contents: read
+      packages: write
+
   publish:
     name: Publish Python package to PyPI
     needs: [validated_tests, package, build, create_release]

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

@@ -60,7 +60,8 @@ or fixed ports), with coverage (`--cov`, configured in `pyproject.toml`, `multip
 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
+tag pushes publish to PyPI after validation and successful executable builds, and the designer
+image to GHCR after validation. 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;

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: beqforge
-Version: 0.2.4
+Version: 0.2.5
 Summary: Audio-derived BEQ design, published filter optimisation and DSP validation
 License-File: LICENCE.md
 Requires-Python: <3.15,>=3.13
@@ -190,8 +190,9 @@ 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.
+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.
 
 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
@@ -259,8 +260,11 @@ pure `design(request) -> response` adapter, independently testable without a soc
 
 `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
+published for linux/amd64 and linux/arm64 by `.github/workflows/build-designer-image.yml` for
 each `vX.Y.Z` tag, from the same commit as that release; `latest` follows the newest release.
+The release workflow (`build-executable.yml`) calls it only once the release tests have passed,
+as it does for the executables and PyPI; pushes to `main` and pull requests build and
+smoke-test the image without publishing it.
 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).

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

@@ -164,8 +164,9 @@ 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.
+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.
 
 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
@@ -233,8 +234,11 @@ pure `design(request) -> response` adapter, independently testable without a soc
 
 `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
+published for linux/amd64 and linux/arm64 by `.github/workflows/build-designer-image.yml` for
 each `vX.Y.Z` tag, from the same commit as that release; `latest` follows the newest release.
+The release workflow (`build-executable.yml`) calls it only once the release tests have passed,
+as it does for the executables and PyPI; pushes to `main` and pull requests build and
+smoke-test the image without publishing it.
 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).

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

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

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

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

{beqforge-0.2.4 → beqforge-0.2.5}/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 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/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/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 → beqforge-0.2.5}/beqforge/diagnose.py

@@ -8,6 +8,7 @@ unknown source spectrum.
 
 import logging
 import math
+from concurrent.futures import ProcessPoolExecutor
 from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING
 
@@ -633,7 +634,7 @@ def diagnose(
     # and reported the band top as where tracking stopped (A Few Good Men: 150.5-200 Hz found by
     # one, none by the other).
     _, mix_plateau = plateau_reference(mix_spectrum, spectrum_freqs, params)
-    from beqforge.extraction import ExtractionParams, extract
+    from beqforge.extraction import ExtractionParams
 
     extraction_params = extraction_params or ExtractionParams()
     extraction_params = replace(
@@ -645,12 +646,18 @@ def diagnose(
         ),
     )
 
+    plateaus = {
+        name: plateau_reference(
+            spectra[name][band], freqs, params, one_sided_fallback=False
+        )
+        for name in material.channels
+    }
+    evidence = _channel_evidence(material, params, extraction_params, plateaus, freqs)
+
     channels: dict[str, ChannelDiagnosis] = {}
     for name in material.channels:
         response = spectra[name][band]
-        level, plateau = plateau_reference(
-            response, freqs, params, one_sided_fallback=False
-        )
+        level, plateau = plateaus[name]
         response = np.where(
             unexcluded(freqs, params.exclude_bands_hz), response, np.nan
         )
@@ -666,10 +673,19 @@ def diagnose(
         passband_share = (
             float(share[in_share_band].mean()) if in_share_band.any() else 0.0
         )
-        _, channel_spread, _, _, tracking = _temporal_evidence(
-            material.channels[name], material.fs, params, plateau, freqs
-        )
-        envelope = extract(material.channels[name], material.fs, extraction_params)
+        if name in evidence:
+            (_, channel_spread, _, _, tracking), envelope, records = evidence[name]
+            for record in records:
+                logging.getLogger(record.name).handle(record)
+        else:
+            (_, channel_spread, _, _, tracking), envelope = _one_channel(
+                material.channels[name],
+                material.fs,
+                params,
+                plateau,
+                freqs,
+                extraction_params,
+            )
         channels[name] = ChannelDiagnosis(
             name=name,
             response_db=response,
@@ -707,6 +723,80 @@ def diagnose(
     )
 
 
+def _one_channel(samples, fs, params, plateau, freqs, extraction_params):
+    """A channel's temporal evidence and envelopes: most of a cold analysis's time, and
+    independent of every other channel's."""
+    from beqforge.extraction import extract
+
+    return (
+        _temporal_evidence(samples, fs, params, plateau, freqs),
+        extract(samples, fs, extraction_params),
+    )
+
+
+class _Collect(logging.Handler):
+    def __init__(self):
+        super().__init__()
+        self.records: list[logging.LogRecord] = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        # made picklable: the message rendered, any traceback as text
+        record.msg, record.args = record.getMessage(), None
+        if record.exc_info:
+            record.exc_text = logging.Formatter().formatException(record.exc_info)
+            record.exc_info = None
+        self.records.append(record)
+
+
+def _one_channel_logged(level, *args):
+    """`_one_channel` in a pool process, its log records returned rather than emitted, so the
+    parent logs them in channel order on every platform: a spawned process has none of the
+    parent's handlers, and a forked one would print them out of order."""
+    root = logging.getLogger()
+    handlers, previous = root.handlers[:], root.level
+    collect = _Collect()
+    root.handlers[:] = [collect]
+    root.setLevel(level)
+    try:
+        return (*_one_channel(*args), collect.records)
+    finally:
+        root.handlers[:] = handlers
+        root.setLevel(previous)
+
+
+def _channel_evidence(material, params, extraction_params, plateaus, freqs):
+    """`_one_channel` for every channel, with its log records, computed in parallel: a
+    process per channel up to the fitter's pool size, when the fitter may run in parallel
+    (`filters.PARALLEL_FITS`, `filters.FIT_WORKERS`). Empty otherwise, and `diagnose` works
+    through the channels in turn as it always did. Each channel's work is seeded and
+    self-contained, so the answer is the serial one; only the time differs."""
+    from beqforge import filters
+
+    names = list(material.channels)
+    tasks = [
+        (
+            material.channels[n],
+            material.fs,
+            params,
+            plateaus[n][1],
+            freqs,
+            extraction_params,
+        )
+        for n in names
+    ]
+    workers = min(len(names), filters.FIT_WORKERS) if filters.PARALLEL_FITS else 1
+    if workers < 2:
+        return {}
+    level = logging.getLogger().getEffectiveLevel()
+    with ProcessPoolExecutor(max_workers=workers) as pool:
+        results = list(
+            pool.map(
+                _one_channel_logged, [level] * len(tasks), *zip(*tasks, strict=True)
+            )
+        )
+    return dict(zip(names, results, strict=True))
+
+
 def _temporal_evidence(
     subject: np.ndarray,
     fs: float,

{beqforge-0.2.4 → beqforge-0.2.5}/beqoptimiser/AGENTS.md

@@ -41,7 +41,8 @@ strings with additive feedback; internal SOS uses subtractive feedback.
 | File | Responsibility |
 | --- | --- |
 | `core.py` | Precision models, deterministic bounded search and independent validation |
-| `cache.py` | Public cached optimisation, immutable numerical results and seed lookup |
+| `parameters.py` | Parameter (freq/Q/gain) search for several (rate, precision) profiles at once, on the publication grid |
+| `cache.py` | Public cached optimisation (coefficients and parameters), immutable numerical results and seed lookup |
 | `cli.py` | Catalogue preparation, current-entry metadata, variant export and CLI |
 | `__init__.py` | Public library exports, including the cached `optimise` wrapper |
 | `data/seed.json.gz`, `data/seed-manifest.json` | Bundled numerical results and provenance |
@@ -53,6 +54,9 @@ dependency versions and execution architecture.
 Custom precision implementations without a complete explicit `cache_identity()` bypass caching.
 Corrupt entries are misses; unwritable storage must not prevent calculation or seed reuse.
 Use atomic writes and retain checksums, request identity and publication-policy validation.
+Parameter results are keyed by that identity plus `parameters.py`'s own hash and
+`PARAMETER_VERSION`, kept out of `implementation_identity()` so they never invalidate the seed;
+put parameter-search code in `parameters.py`, never `core.py`, for the same reason.
 
 Bundled seeds are reusable only in their recorded numerical environment. Changes to numerical
 code or settings invalidate them; do not relabel old results as compatible. Bump

{beqforge-0.2.4 → beqforge-0.2.5}/beqoptimiser/__init__.py

@@ -8,6 +8,9 @@ from .cache import (
 from .cache import (
     optimise as optimise,
 )
+from .cache import (
+    optimise_parameters as optimise_parameters,
+)
 from .core import (
     FixedPoint as FixedPoint,
 )
@@ -32,3 +35,15 @@ from .core import (
 from .core import (
     stable as stable,
 )
+from .parameters import (
+    Fixed as Fixed,
+)
+from .parameters import (
+    ParameterResult as ParameterResult,
+)
+from .parameters import (
+    ParameterSettings as ParameterSettings,
+)
+from .parameters import (
+    ProfileError as ProfileError,
+)

{beqforge-0.2.4 → beqforge-0.2.5}/beqoptimiser/cache.py

@@ -17,16 +17,25 @@ from pathlib import Path
 import numpy as np
 import scipy
 
-from . import core
+from . import core, parameters
 from .core import (
     NUMERICAL_VERSION,
+    PUBLISHED_OUTCOMES,
     FixedPoint,
     Float32,
     Precision,
     Result,
+    Section,
     Settings,
     stable,
 )
+from .parameters import (
+    PARAMETER_VERSION,
+    Fixed,
+    ParameterResult,
+    ParameterSettings,
+    ProfileError,
+)
 
 LOGGER = logging.getLogger(__name__)
 CACHE_SCHEMA = 1
@@ -263,10 +272,13 @@ class ResultCache:
         self.directory = Path(directory)
         self.use_seed = use_seed
 
-    def get(self, request) -> Result | None:
+    def get(self, request, restore=None):
+        """The cached result for a request, or None; `restore` checks an envelope against
+        its request (`_restore` for coefficient results, the default)."""
+        restore = restore or _restore
         key = request[0]
         try:
-            result = _restore(
+            result = restore(
                 json.loads((self.directory / f"{key}.json").read_text()), request
             )
             LOGGER.debug(f"Optimiser disk cache hit: {key}")
@@ -277,7 +289,7 @@ class ResultCache:
             try:
                 envelope = _bundled_entries().get(key)
                 if envelope is not None:
-                    result = _restore(envelope, request)
+                    result = restore(envelope, request)
                     LOGGER.debug(f"Optimiser bundled cache hit: {key}")
                     return result
             except (ValueError, KeyError, TypeError, OverflowError):
@@ -373,3 +385,169 @@ def optimise(
     _restore(envelope, request)
     store._write(envelope)
     return result
+
+
+PARAMETER_OUTCOMES = (
+    "within_margin",
+    "replacement",
+    "improvement",
+    "no_replacement",
+    "unresolved",
+)
+
+
+def _section_identity(section) -> dict:
+    return {"kind": type(section).__name__, **asdict(section)}
+
+
+def _parameter_request(sections, *, profiles, settings=None):
+    """(key, sections, profiles, settings), or None when a request cannot be cached: an
+    invalid one (left for `optimise_parameters` to refuse) or a precision without a complete
+    identity. Keyed by the coefficient optimiser's implementation identity plus this module's
+    own source and `PARAMETER_VERSION`, so the coefficient seed is unaffected."""
+    cfg = settings or ParameterSettings()
+    cascade = tuple(sections)
+    chosen = list(profiles)
+    if (
+        not cascade
+        or not chosen
+        or not all(isinstance(s, (Section, Fixed)) for s in cascade)
+    ):
+        return None
+    identities = []
+    for rate, precision in chosen:
+        identity = _precision_identity(precision)
+        if identity is None or rate not in parameters.RATES:
+            return None
+        identities.append({"rate": rate, "name": precision.name, "identity": identity})
+    try:
+        implementation = implementation_identity() | {
+            "parameters": hashlib.sha256(
+                files("beqoptimiser").joinpath("parameters.py").read_bytes()
+            ).hexdigest(),
+            "parameter_version": PARAMETER_VERSION,
+        }
+        payload = {
+            "sections": [_section_identity(s) for s in cascade],
+            "profiles": identities,
+            "settings": asdict(cfg),
+        }
+        key = _digest({"implementation": implementation, "request": payload})
+    except (OSError, TypeError, ValueError):
+        return None
+    return key, cascade, chosen, cfg
+
+
+def _parameter_envelope(key: str, result: ParameterResult) -> dict:
+    body = _encode(
+        asdict(result)
+        | {
+            "sections": None
+            if result.sections is None
+            else [_section_identity(s) for s in result.sections]
+        }
+    )
+    return {
+        "schema": CACHE_SCHEMA,
+        "kind": "parameters",
+        "key": key,
+        "result": body,
+        "checksum": _digest(body),
+    }
+
+
+def _decode_section(value: dict):
+    kind = value.pop("kind")
+    if kind == "Section":
+        return Section(**value)
+    if kind == "Fixed":
+        return Fixed(tuple((int(r), tuple(row)) for r, row in value["coefficients"]))
+    raise ValueError(f"unknown section kind {kind!r}")
+
+
+def _restore_parameters(envelope: dict, request) -> ParameterResult:
+    key, cascade, chosen, cfg = request
+    if (
+        envelope["schema"] != CACHE_SCHEMA
+        or envelope.get("kind") != "parameters"
+        or envelope["key"] != key
+        or envelope["checksum"] != _digest(envelope["result"])
+    ):
+        raise ValueError("invalid cache envelope")
+    body = _decode(envelope["result"])
+    body["band_hz"] = tuple(body["band_hz"])
+    body["profiles"] = tuple(ProfileError(**p) for p in body["profiles"])
+    if body["sections"] is not None:
+        body["sections"] = tuple(_decode_section(dict(s)) for s in body["sections"])
+    result = ParameterResult(**body)
+    expected = [(rate, p.name) for rate, p in chosen]
+    if (
+        result.version != PARAMETER_VERSION
+        or result.outcome not in PARAMETER_OUTCOMES
+        or result.margin_db != cfg.margin_db
+        or result.band_hz != cfg.band_hz
+        or [(p.rate, p.precision) for p in result.profiles]
+        != list(dict.fromkeys(expected))
+        or np.isnan(result.original_error_db)
+        or result.original_error_db < 0
+        or result.evaluations < 0
+    ):
+        raise ValueError("cache result does not match request")
+    if result.outcome in PUBLISHED_OUTCOMES:
+        if (
+            result.sections is None
+            or len(result.sections) != len(cascade)
+            or result.candidate_error_db is None
+            or not np.isfinite(result.candidate_error_db)
+            or result.original_error_db <= cfg.margin_db
+        ):
+            raise ValueError("cached replacement violates publication policy")
+        for old, new in zip(cascade, result.sections, strict=True):
+            if type(old) is not type(new) or (isinstance(old, Fixed) and old != new):
+                raise ValueError("cached replacement changes the cascade's structure")
+            if isinstance(new, Section) and (
+                new.type != old.type
+                or round(new.freq, 2) != new.freq
+                or round(new.q, 4) != new.q
+                or round(new.gain, 2) != new.gain
+            ):
+                raise ValueError("cached replacement is off the publication grid")
+        if result.outcome == "replacement" and (
+            result.candidate_error_db > cfg.margin_db
+        ):
+            raise ValueError("cached replacement violates publication policy")
+        if (
+            result.outcome == "improvement"
+            and result.candidate_error_db
+            >= result.original_error_db - cfg.numerical_tolerance_db
+        ):
+            raise ValueError("cached improvement violates publication policy")
+    elif result.sections is not None:
+        raise ValueError("unexpected cached replacement")
+    return result
+
+
+def optimise_parameters(
+    sections,
+    *,
+    profiles,
+    settings: ParameterSettings | None = None,
+    cache: ResultCache | bool | None = None,
+) -> ParameterResult:
+    """`parameters.optimise_parameters` with automatic cache reuse; use cache=False for a
+    fresh calculation."""
+    kwargs = {"profiles": profiles, "settings": settings}
+    if cache is False or os.environ.get("BEQOPTIMISER_CACHE") == "0":
+        return parameters.optimise_parameters(sections, **kwargs)
+    request = _parameter_request(sections, **kwargs)
+    if request is None:
+        return parameters.optimise_parameters(sections, **kwargs)
+    store = cache if isinstance(cache, ResultCache) else ResultCache()
+    result = store.get(request, _restore_parameters)
+    if result is not None:
+        return result
+    result = parameters.optimise_parameters(sections, **kwargs)
+    envelope = _parameter_envelope(request[0], result)
+    _restore_parameters(envelope, request)
+    store._write(envelope)
+    return result