ci: limit the frontend job to 8 minutes

The first 0.0.17 cut (run 687) failed verify-pins in CI for two reasons. The asset generator embedded admin/dist/.src-hash, a freshness stamp that CI's artifact copy does not carry; it now skips dotfiles. And the Arch zig package emits different code than the ziglang.org tarball that CI installs, so the cut downloads the pinned tarball (ZIG_TARBALL_SHA256 in gates.yml, the full digest keys the cache) and builds the release with it. flake.nix is re-pinned to the bytes both now produce.

The saturated-primary pool test gates its holders on a semaphore instead of sleeps and releases every spawned holder on the way out, so a loaded runner cannot flake it. The package job uploads the payload before the pin check and runs the check when the version or flake.nix changed against the parent. The verify-a-release recipe clones the tag first and builds with the official zig.

.gitea/workflows/gates.yml

@@ -41,9 +41,20 @@ on:
 
 env:
   ZIG_VERSION: "0.16.0"
+  # The bytes of that zig, not just its version string: a distribution package
+  # of the same version is built against a different LLVM and emits different
+  # machine code, so its tarballs hash to something no CI run reproduces.
+  # setup-zig verifies these same bytes by minisign; `zig build cut` checks this
+  # digest before it builds a release.
+  ZIG_TARBALL_SHA256: "70e49664a74374b48b51e6f3fdfbf437f6395d42509050588bd49abe52ba3d00"
   # Exact patch, not a floating "24" (milestone-14 ruling 12): the bundled npm
   # and the emitted bundle change under a floating major.
   NODE_VERSION: "24.19.0"
+  # The npm the cut runs and the npm CI runs must be one version: npm writes the
+  # admin bundle whose bytes the release hashes are pinned to before CI ever
+  # rebuilds them. setup-node installs the npm that ships with the node above,
+  # so this pin is asserted, not installed.
+  NPM_VERSION: "11.17.0"
   # There is deliberately no CI_VERSION literal here. Ruling 2 allows the
   # version to exist in the tag and in build.zig.zon and nowhere else, and
   # ruling 5 makes verify-dist fail when the version under build disagrees with
@@ -115,6 +126,10 @@ jobs:
     # 1536Mi dind limit, and it runs no docker command — so it overlaps the
     # heavy runner's zig and image work instead of queueing behind it.
     runs-on: ubuntu-24.04-light
+    # The slowest green run took 4 minutes. A stalled Node download leaves setup-node
+    # holding an open socket after its retry succeeds, so the step never exits:
+    # without a limit the job held the runner for over an hour.
+    timeout-minutes: 8
 
     steps:
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
@@ -126,9 +141,25 @@ jobs:
           cache: npm
           cache-dependency-path: admin/package-lock.json
 
+      # The bundle is a release input whose hash is pinned before this run
+      # exists, so a runner on a different node or npm must fail here rather
+      # than emit different bytes further down.
+      - name: Assert the pinned Node and npm
+        run: |
+          test "$(node --version)" = "v${NODE_VERSION:?}"
+          test "$(npm --version)" = "${NPM_VERSION:?}"
+          test ! -e /nonexistent/npmrc-user
+          test ! -e /nonexistent/npmrc-global
+
+      # `npm ci` and `npm run build` run under the same normalized environment
+      # the cut builds the bundle in: exactly nine variables, a file mode from
+      # the umask, a C locale, UTC, and a zero build timestamp. Each of those
+      # can move the bytes the release hashes cover. The format, lint,
+      # typecheck and test steps below stay ambient on purpose: only the
+      # bundle's bytes are pinned, and those checks emit nothing that ships.
       - name: Install dependencies
         working-directory: admin
-        run: npm ci
+        run: env -i PATH="$PATH" HOME="$HOME" LC_ALL=C LANG=C TZ=UTC SOURCE_DATE_EPOCH=0 CI=true npm_config_userconfig=/nonexistent/npmrc-user npm_config_globalconfig=/nonexistent/npmrc-global sh -c 'umask 022 && npm ci'
 
       - name: Check formatting
         working-directory: admin
@@ -148,7 +179,7 @@ jobs:
 
       - name: Build
         working-directory: admin
-        run: npm run build
+        run: env -i PATH="$PATH" HOME="$HOME" LC_ALL=C LANG=C TZ=UTC SOURCE_DATE_EPOCH=0 CI=true npm_config_userconfig=/nonexistent/npmrc-user npm_config_globalconfig=/nonexistent/npmrc-global sh -c 'umask 022 && npm run build'
 
       # The licence inventory has to cover every package whose bytes ship, and
       # the lockfile does not answer that question: it lists what could be
@@ -191,7 +222,12 @@ jobs:
       version: ${{ steps.zon-version.outputs.version }}
 
     steps:
+      # Depth 2, not the default 1: the pin check at the foot of this job runs
+      # only on the commit that changed build.zig.zon, and answering that
+      # question needs HEAD's first parent. No other job here reads a parent.
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 2
 
       - name: Set up Zig
         uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2.2.1
@@ -243,7 +279,6 @@ jobs:
           set -euo pipefail
           zig build dist \
             -Dversion-string="$CI_VERSION" \
-            -Dgit-commit="$GITHUB_SHA" \
             -Dadmin-dist=admin-dist-ci \
             -Doptimize=ReleaseSafe
 
@@ -259,10 +294,14 @@ jobs:
           set -euo pipefail
           zig build verify-dist \
             -Dversion-string="$CI_VERSION" \
-            -Dgit-commit="$GITHUB_SHA" \
             -Dadmin-dist=admin-dist-ci \
             -Doptimize=ReleaseSafe
 
+      # This upload runs before the pin check below: a pin mismatch is exactly
+      # the failure whose diagnosis needs the built bytes, so they must already
+      # be downloadable when that step fails. The container job's dependency on
+      # the artifact is unchanged.
+      #
       # deploy/docker/Dockerfile copies both of these trees and nothing else
       # out of zig-out/dist: the binary comes from dist/bin/<triple>/, and
       # /LICENSE and /THIRD-PARTY-NOTICES come from the matching dist/stage/
@@ -290,6 +329,57 @@ jobs:
             zig-out/bin/container_check
           if-no-files-found: error
 
+      # The cut writes the release hashes into flake.nix before it makes the
+      # bump commit, so the bump commit is the one commit whose pins nothing has
+      # verified yet — the tag's own run (release.yml) is the next chance, and by
+      # then the tag is public. This step is that first chance.
+      #
+      # It is deliberately NOT part of verify-dist. Every other commit on master
+      # builds the same build.zig.zon version from a different tree, so its bytes
+      # legitimately differ from the pins and a check there would fail the whole
+      # branch. The commit is identified by the version it declares, not by its
+      # message: a message is a string anyone can write, and the pins follow
+      # the manifest.
+      #
+      # A root commit has no first parent. That is an error rather than a skip:
+      # this repository has history, so `HEAD^` failing means the checkout is
+      # shallower than the depth 2 declared above and the question went
+      # unanswered, which must never read as "nothing to check".
+      #
+      # The predicate is the declared VERSION, not the file: build.zig.zon also
+      # carries the dependency pins, and updating a sqlite or mbedTLS hash
+      # changes the file without cutting a release. Such a commit builds the
+      # same version from a different tree, so its bytes are not the pinned
+      # ones and this check would fail it.
+      #
+      # A commit that rewrites flake.nix runs the check too: a re-pin during a
+      # cut changes the pins without changing the version, and those pins must
+      # be verified before the tag as well.
+      #
+      # HEAD's version is CI_VERSION, parsed out of the working tree by the
+      # container gate tool. The parent's is read with `sed`, because that tool
+      # reads `build.zig.zon` at a fixed path and has no mode for a blob out of
+      # history. An empty parse is a failure, not a bump: it means the manifest
+      # moved and the question went unanswered.
+      - name: Verify the flake pins on a version bump
+        run: |
+          set -euo pipefail
+          parent="$(git rev-parse --verify HEAD^)"
+          parent_version="$(git show "$parent":build.zig.zon | sed -n 's/^[[:space:]]*\.version = "\([^"]*\)".*/\1/p')"
+          if [ -z "$parent_version" ]; then
+            echo "cannot read .version out of $parent:build.zig.zon" >&2
+            exit 1
+          fi
+          if [ "$parent_version" != "$CI_VERSION" ] || ! git diff --quiet "$parent" HEAD -- flake.nix; then
+            zig build verify-pins \
+              -Dversion-string="$CI_VERSION" \
+              -Dadmin-dist=admin-dist-ci \
+              -Doptimize=ReleaseSafe
+          else
+            echo "skipped: $GITHUB_SHA declares version $CI_VERSION, $parent already declared $parent_version and flake.nix is unchanged, so it is neither a version bump nor a re-pin and its bytes are not the ones flake.nix pins"
+          fi
+
+
   container:
     needs: [package]
     runs-on: ubuntu-24.04

.gitea/workflows/release.yml

@@ -60,8 +60,15 @@ env:
   REGISTRY_HOST: "git.mial.net"
 
   ZIG_VERSION: "0.16.0"
+  # The bytes of that zig, not just its version string: a distribution package
+  # of the same version is built against a different LLVM and emits different
+  # machine code, so its tarballs hash to something no CI run reproduces.
+  # setup-zig verifies these same bytes by minisign; `zig build cut` checks this
+  # digest before it builds a release.
+  ZIG_TARBALL_SHA256: "70e49664a74374b48b51e6f3fdfbf437f6395d42509050588bd49abe52ba3d00"
   # Exact patch, not a floating "24" (ruling 12).
   NODE_VERSION: "24.19.0"
+  NPM_VERSION: "11.17.0"
 
   # The author's commit- and tag-signing key. `git verify-tag` alone proves
   # only that *some* key in the keyring signed the tag, so the signature's
@@ -271,18 +278,29 @@ jobs:
           cache: npm
           cache-dependency-path: admin/package-lock.json
 
+      # The same pinned toolchain and normalized environment as the frontend
+      # job in gates.yml: the cut pinned the bundle's bytes into flake.nix
+      # before this run existed, and the pin check below compares against them.
+      - name: Assert the pinned Node and npm
+        run: |
+          test "$(node --version)" = "v${NODE_VERSION:?}"
+          test "$(npm --version)" = "${NPM_VERSION:?}"
+          test ! -e /nonexistent/npmrc-user
+          test ! -e /nonexistent/npmrc-global
+
+      # The same normalized environment the cut builds the bundle in: exactly
+      # nine variables, a file mode from the umask, a C locale, UTC and a zero
+      # build timestamp. Each of those can move the bytes the release hashes
+      # cover, and this job's bundle has to reproduce the one the cut pinned.
       - name: Build the web UI
         working-directory: admin
-        run: |
-          npm ci
-          npm run build
+        run: env -i PATH="$PATH" HOME="$HOME" LC_ALL=C LANG=C TZ=UTC SOURCE_DATE_EPOCH=0 CI=true npm_config_userconfig=/nonexistent/npmrc-user npm_config_globalconfig=/nonexistent/npmrc-global sh -c 'umask 022 && npm ci && npm run build'
 
       # Step 8.
       - name: Build the release artifacts
         run: >
           zig build dist
           -Dversion-string="$VERSION"
-          -Dgit-commit="$TAG_COMMIT"
           -Dadmin-dist=admin/dist
           -Doptimize=ReleaseSafe
 
@@ -290,7 +308,19 @@ jobs:
         run: >
           zig build verify-dist
           -Dversion-string="$VERSION"
-          -Dgit-commit="$TAG_COMMIT"
+          -Dadmin-dist=admin/dist
+          -Doptimize=ReleaseSafe
+
+      # Unconditional, and before the image push, the draft and every upload:
+      # the tag's tree IS the bump commit's tree, so the flake block must pin
+      # these exact bytes and name this exact version. A consumer who resolves
+      # the tag through the flake gets hashes that were written before this run
+      # existed; this is where the claim is proved, while nothing has yet left
+      # the runner.
+      - name: Verify the flake pins
+        run: >
+          zig build verify-pins
+          -Dversion-string="$VERSION"
           -Dadmin-dist=admin/dist
           -Doptimize=ReleaseSafe
 

AGENTS.md

@@ -49,6 +49,16 @@ That function returns `null` for every input. `fetchAdd` is the only trigger: a
 
 `Owner.published` in `src/upstream/owner.zig` is a plain `u64` under the owner's mutex for this reason. Do not "modernize" it to `std.atomic.Value(u64)`.
 
+## Testing the NixOS module
+
+`nix/module.nix` (`services.nxdns`) has two acceptance checks in `nix/tests.nix`, and no CI job runs them: the VM test needs KVM, and both download a nixpkgs closure that the shared Gitea runner must not fetch on every push. The cut's `nix flake check --no-build` evaluates them, which catches a module that no longer evaluates, but builds nothing. After any change to `nix/module.nix`, `nix/tests.nix`, the package in `flake.nix` or `deploy/systemd/nxdns.service`, build both on a host with KVM before the commit:
+
+```
+nix build --no-link -L .#checks.x86_64-linux.nixos-module .#checks.x86_64-linux.nixos-module-rejects-config
+```
+
+The checks run the package the flake pins, which is the last release, so a change to `deploy/systemd/nxdns.service` reaches the VM test only after the release that ships it.
+
 ## Regenerating the contract samples
 
 `admin/src/lib/contractSamples.gen.ts` is a committed golden of canonicalized API responses, byte-compared against the live server by a `-Dintegration` test and type-checked by `tsc`. After a deliberate API contract change, regenerate it with:

CHANGELOG.md

@@ -4,6 +4,75 @@ All notable changes to nxdns are recorded here. The format follows [Keep a Chang
 
 Sections are written by hand. Nothing here is generated from commit messages: the point of the file is to say what changed for an operator, which a commit subject rarely does.
 
+## [0.0.24] - 2026-10-21
+
+### Fixed
+
+- **The admin pages fit a phone.** At 390 px, Activity, Clients, Diagnostics and every configuration table scrolled sideways, and Diagnostics and Clients made the whole page 826 px and 660 px wide, so the phone zoomed out. A table now shows all its columns only where they fit without wrapping. In a narrower table, the first cell carries the other columns' facts on short lines ("Priority 20 · TLS name dns.quad9.net", "Created 19 Oct 2026, 16:15:44"), and long names, URLs, IPv6 addresses and patterns wrap instead of widening the page. In the narrow Sources and Upstreams tables, Edit and Delete stack, which gives the first cell the width. Protection > Sources needs a 1440 px wide table for all its columns, so a 1440 px window now shows its narrow form; in 0.0.23 it made the page 1557 px wide there.
+- **Overview is no longer taller than the window.** The charts' screen-reader tables extended the document below the app, so the page had a second scroll bar under the main one at desktop widths.
+- **The Diagnostics count line no longer spreads its words across the page.**
+- **The Diagnostics health cards no longer spread a short card's lines down its height.**
+
+## [0.0.23] - 2026-10-20
+
+### Fixed
+
+- **A blackhole route to an upstream no longer stops failover.** On a route like that, `connect()` fails with an errno the runtime has no name for, and nxdns took it for a fault of its own: the query got SERVFAIL at once, the next upstream was never tried, and nothing was charged to the unreachable one. A connect failure of that kind now counts against that upstream as `ConnectFailed (cause Unexpected)`, and the query fails over.
+- **The Overview charts no longer draw the current bucket as a fall in traffic.** Every Overview window ends at the end of the bucket that holds the present moment, so its last bucket is still counting. Queries over time draws the curve into it dashed over a fainter fill, and Client activity draws its column faint inside a dashed outline. Both legends name "Still counting", and the tooltip and the chart's data table give that bucket's time as "<time> · still counting".
+- **The query detail page names the device.** The Client fact showed only the address, while the Activity list showed "iPhone (192.168.50.52)" for the same query. It now uses the list's label. The query log records only the address, so the record's intro says the device name is the one the address has today.
+
+### Added
+
+- **A NixOS module.** The flake exports `nixosModules.default`, which adds `services.nxdns` with four options: `enable`, `package`, `configFile` and `openFirewall`. It runs the release's own `nxdns.service` with a drop-in for file mode, checks `configFile` with the pinned binary's `nxdns import` at build time so a configuration that does not parse, validate or reconcile fails the build, and restarts the service when only the configuration changes. The flake's package now also installs `lib/systemd/system/nxdns.service`. See "Install nxdns with Nix".
+- **`nxdns_upstream_local_resource_total`** counts exchanges that ended on this process's own resources (memory, file descriptors, an unnamed system error) before any upstream answered. Until now, such a SERVFAIL left no record of its cause anywhere.
+
+### Changed
+
+- **The compose file names its own release.** `deploy/docker/compose.yaml` defaults its image to the release it is tagged with instead of `:latest`, so `docker compose up -d` with the file from a tag runs that tag's image, and the install and upgrade steps no longer set `NXDNS_VERSION`. The variable still picks another release, and `NXDNS_IMAGE` still names a local image. Compose files from `v0.0.22` and earlier keep the `:latest` default.
+- **A DoH upstream that answers with an error status says which.** The Diagnostics episode and `/api/health` read `HttpStatus (status 505 HTTP Version Not Supported)` instead of `HttpStatus (cause HttpStatus)`. A 505 is a server that requires HTTP/2, which nxdns does not speak.
+
+## [0.0.22] - 2026-10-19
+
+### Added
+
+- **`/metrics` reports the most concurrent work the server has seen.** Five gauges hold peaks since start: `nxdns_dns_in_flight_peak` (queries handled at once, every listener together), `nxdns_tcp_server_connections_peak`, `nxdns_dot_server_connections_peak` and `nxdns_doh_server_connections_peak` (connections one listener held at once), and `nxdns_querylog_queue_peak` (entries waiting for the query log writer at once). The memory budget work sizes its limits from them; "Measure performance" shows how to read them beside the process's resident memory, thread count and worker stacks.
+
+## [0.0.21] - 2026-09-12
+
+### Changed
+
+- **An upstream warning means the pool stopped trusting the endpoint.** A Diagnostics episode opens when an upstream reaches the health failure threshold and closes on the success that clears it, instead of one card per lost exchange. Failures during backoff raise the card's occurrence count. The episode detail and the `nxdns check` report name the concrete cause behind the classification, `SendFailed (cause BrokenPipe)`.
+
+## [0.0.20] - 2026-09-12
+
+### Fixed
+
+- **A blocklist source no longer fails on a stale pooled connection.** The fetcher reused a keep-alive connection from an earlier pass that the server had closed, and the standard client never retries one; every later download from that host failed with `HttpConnectionClosing` at 0 ms. Downloads now send `connection: close` and never enter the pool.
+
+## [0.0.19] - 2026-09-12
+
+### Changed
+
+- **A failed blocklist download says why.** The warning line and the Diagnostics event detail now carry the phase that failed, the concrete cause behind the classification (a reset connection, a truncated chunk, a TLS handshake fault), the HTTP status if a head arrived, the bytes received, and the elapsed time. The separate `http status` warning is folded into that line. Same one line per failed source per pass as before.
+
+## [0.0.18] - 2026-09-09
+
+### Fixed
+
+- **The Overview scope pickers no longer sit apart, and a long device name no longer pushes the period picker off a phone screen.** The Device and Period dropdowns fill their wrappers and stand side by side; a long name truncates with an ellipsis in the trigger and stays fully readable in the list.
+
+## [0.0.17] - 2026-09-08
+
+### Added
+
+- **A Nix flake with tag-pinned hashes.** `flake.nix` at the repository root builds `nxdns` for `aarch64-linux` and `x86_64-linux` from the release tarballs, and carries their hashes in a generated block. A consumer pins the flake to a release tag and gets the exact bytes that tag published; `docs/how-to/install-with-nix.md` covers the input, the `nixpkgs` follows line, and Renovate.
+
+### Changed
+
+- **The release archive is written by the project's own tool.** `zig build dist` no longer shells out to the runner's `tar` and `gzip`; it writes the tar stream and the gzip container itself, with sorted entries, fixed modes, and zero timestamps. The tarball bytes now depend on the source tree, the compiler, and the admin bundle, and on nothing the host supplies — which is what lets a hash be pinned before CI rebuilds it.
+- **The cut pins the release hashes before it commits.** `zig build cut` asserts the local Node, npm, and Zig match the versions CI pins, builds the release from the bumped manifest in a normalized environment, writes the resulting hashes into `flake.nix`, and commits that file alongside `build.zig.zon` as one commit. CI reverifies the pins on the bump commit and again on the tag, before anything is uploaded.
+- **`nxdns version` no longer reports a git commit.** The commit is gone from the command's output, from `GET /api/version`, and from the admin footer, which now shows `nxdns v<version>`. A release identifies itself by version, and the bytes are reproducible from the tag, so a commit embedded in the binary told a reader nothing the tag did not.
+
 ## [0.0.16] - 2026-09-07
 
 The Overview page is redesigned around the two dashboards people already know — Pi-hole's layout, NextDNS's charts — and every number in the admin is spelled one way.

PLAN.md

@@ -37,9 +37,10 @@ Serves a household LAN (≈2–20 devices). Portfolio-grade public repo with ext
 - Partial-segment wildcards (`ads*.example.com`) as a rule kind. The regex kind covers the need without a second globbing dialect.
 - DHCP server.
 - DNSSEC validation (DO bit passthrough only).
-- DoQ (QUIC), HTTP/2 upstream transport.
+- DoQ (DNS over QUIC). Out of scope until the Zig stdlib, or an equivalent dependency, provides QUIC; neither the stdlib nor mbedTLS does at 0.16.0. This is the one conditional entry in this list.
+- HTTP/2 upstream transport.
+- DNSCrypt. It is older than DoH and DoT and not an IETF standard, and DoH and DoT already cover encrypted DNS.
 - Clustering / distributed state.
-- Project website. The repository, its README and `docs/` are the whole published surface.
 
 ---
 
@@ -571,7 +572,7 @@ Requirements: responsive desktop/mobile; route loaders for initial fetch; TanSta
 - `nxdns check` — validate config, probe upstreams, load each enabled listener's certificate and verify its key pairs with it; exit 2 on failure, 0 with warnings.
 - `nxdns export [--out file.zon]`
 - `nxdns import <file.zon> [--force]`
-- `nxdns version` — app version, Zig version string, git commit. No build date: the version and the commit identify a build exactly, and a date is one more input a reproducible build would have to pin.
+- `nxdns version` — app version and Zig version string. No commit and no build date: the version names the release, the release tarballs are reproducible from the tag with the pinned toolchain, and `flake.nix` pins their hashes. A commit or a date would be one more build input that reproducibility has to pin.
 
 ---
 

README.md

@@ -28,13 +28,11 @@ One static Zig binary. SQLite holds the state and the query log, which the web U
 
 ## Install
 
-**No release exists yet.** This repository has no tags, nothing has been published to <https://git.mial.net/mokhtar/nxdns/releases>, and no container image has been pushed. Every release URL on this page and in the how-to guides is a 404 today, and `docker pull` finds nothing. Until the first tag ships, building from source is the only way to get nxdns.
-
-What a tag will publish, once one exists: five assets — two static musl tarballs (`nxdns-<version>-x86_64-linux-musl.tar.gz`, `nxdns-<version>-aarch64-linux-musl.tar.gz`), `IMAGE-DIGEST.txt` naming the multi-architecture container image by digest, `SHA256SUMS.txt` covering those three files, and `SHA256SUMS.txt.asc`, a detached OpenPGP signature over the checksum file. Verify what you downloaded before you run it: [docs/how-to/verify-a-release.md](docs/how-to/verify-a-release.md), which also says what that signature does and does not prove.
+Releases are published at <https://git.mial.net/mokhtar/nxdns/releases>, and the container image at `git.mial.net/mokhtar/nxdns`, which pulls without an account. Each tag publishes five assets — two static musl tarballs (`nxdns-<version>-x86_64-linux-musl.tar.gz`, `nxdns-<version>-aarch64-linux-musl.tar.gz`), `IMAGE-DIGEST.txt` naming the multi-architecture container image by digest, `SHA256SUMS.txt` covering those three files, and `SHA256SUMS.txt.asc`, a detached OpenPGP signature over the checksum file. Verify what you downloaded before you run it: [docs/how-to/verify-a-release.md](docs/how-to/verify-a-release.md), which also says what that signature does and does not prove.
 
 ## Quickstart (docker compose)
 
-Write a minimal configuration and start the published image. This is what the first release will make possible; it does not work today, because there is no image in the registry to pull:
+Write a minimal configuration and start the published image:
 
 ```sh
 cd deploy/docker
@@ -46,14 +44,14 @@ cat > etc-nxdns/config.zon <<'EOF'
     .web = .{ .password = "choose-a-real-password" },
 }
 EOF
-NXDNS_VERSION=<version> docker compose up -d
+docker compose up -d
 ```
 
-The compose file defaults to `:latest`; pin a version for anything you intend to keep running. To run it before a release exists, build the image yourself and name it — `NXDNS_IMAGE=nxdns docker compose up -d` — as [docs/how-to/install-with-docker.md](docs/how-to/install-with-docker.md) describes. DNS is on port 53, the web UI on <http://localhost:8080>.
+The compose file names the release it belongs to, so a checkout of a release tag runs that release's image. `NXDNS_VERSION=<version> docker compose up -d` runs another release. To run an image you built yourself, name it — `NXDNS_IMAGE=nxdns docker compose up -d` — as [docs/how-to/install-with-docker.md](docs/how-to/install-with-docker.md) describes. DNS is on port 53, the web UI on <http://localhost:8080>.
 
 The compose file runs `nxdns run --config=/etc/nxdns/config.zon`, which makes that file the configuration: every start reconciles the database onto it, and the UI refuses configuration edits. Edit the file and restart to change anything. Drop the `command:` line to run bare `nxdns run` instead, where the database is the configuration and changes go through the UI, the API, or `nxdns export` / `nxdns import` — the packaged systemd unit does that. Which mode is live is printed at every start (`authority: database` / `authority: file (<path>)`); see [docs/explanation/configuration-model.md](docs/explanation/configuration-model.md).
 
-Full install instructions, including the systemd path and the Pi 5 recipe, are in [docs/how-to/install-with-systemd.md](docs/how-to/install-with-systemd.md) and [docs/how-to/install-with-docker.md](docs/how-to/install-with-docker.md).
+Full install instructions, including the systemd path and the Pi 5 recipe, are in [docs/how-to/install-with-systemd.md](docs/how-to/install-with-systemd.md), [docs/how-to/install-with-docker.md](docs/how-to/install-with-docker.md) and, for NixOS, [docs/how-to/install-with-nix.md](docs/how-to/install-with-nix.md).
 
 ## Building from source
 
@@ -70,15 +68,15 @@ The release artifacts come out of the same build graph, so the whole release bui
 ```sh
 (cd admin && npm ci && npm run build)                # required: dist refuses the placeholder
 VERSION=$(sed -n 's/^[[:space:]]*\.version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' build.zig.zon)
-zig build dist -Dversion-string="$VERSION" -Dgit-commit=$(git rev-parse HEAD) \
+zig build dist -Dversion-string="$VERSION" \
     -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe     # tarballs -> zig-out/dist/
-zig build verify-dist -Dversion-string="$VERSION" -Dgit-commit=$(git rev-parse HEAD) \
+zig build verify-dist -Dversion-string="$VERSION" \
     -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe     # the release checks
 ```
 
 The version comes from `build.zig.zon` because `verify-dist` asserts the two agree; a tag sets both.
 
-That is not a claim that your tarball will hash the same as a published one. Nothing in this project measures whether two builds of the same commit on two different machines land on the same bytes, so no document here describes the build as reproducible. The gate that would settle it is a recorded deferral — `specs/milestone-14.md` ruling 12 — and [docs/how-to/verify-a-release.md](docs/how-to/verify-a-release.md) explains what a matching or differing hash is worth in the meantime.
+On the toolchain versions pinned at the top of `.gitea/workflows/gates.yml`, your tarballs hash the same as the published ones of that version. [docs/how-to/verify-a-release.md](docs/how-to/verify-a-release.md) has the rebuild recipe and what to check when a hash differs.
 
 ## Documentation
 

admin/dist-placeholder/index.html

@@ -52,7 +52,7 @@
     });
   fetch("/api/version")
     .then((r) => r.json())
-    .then((v) => { el("version").textContent = v.version + " (" + v.git_commit + ")"; })
+    .then((v) => { el("version").textContent = v.version; })
     .catch(() => {});
 </script>
 </body>

admin/src/features/activity/ActivityDetailPage.test.tsx

@@ -1,4 +1,5 @@
 import { render, screen, waitFor, within } from "@testing-library/react";
+import * as stylex from "@stylexjs/stylex";
 import { QueryClientProvider } from "@tanstack/react-query";
 import { RouterProvider, createMemoryHistory } from "@tanstack/react-router";
 import { AuthProvider } from "@/auth/store";
@@ -7,6 +8,7 @@ import { createAppRouter } from "@/routes";
 import type { QueryDetail } from "@/lib/types";
 import { provenance } from "@/features/provenance/provenanceFixture";
 import { health } from "@/lib/healthFixture";
+import { styles as shared } from "@/ui/styles";
 
 function detail(id: number, sections: Parameters<typeof provenance>[0] = {}): QueryDetail {
 	return { id, ...provenance(sections) };
@@ -16,7 +18,7 @@ let responses: Record<string, unknown>;
 
 beforeEach(() => {
 	responses = {
-		"/api/version": { version: "0.0.0-test", git_commit: "0000000", zig_version: "0.16.0", uptime_seconds: 1 },
+		"/api/version": { version: "0.0.0-test", zig_version: "0.16.0", uptime_seconds: 1 },
 		"/api/health": health(),
 	};
 	vi.stubGlobal(
@@ -282,24 +284,40 @@ async function relatedText(expected: string) {
 	await waitFor(() => expect(related.textContent?.replace(/\s+/g, " ")).toContain(expected));
 }
 
-test("the record keeps the address the query came from, and Related carries the name it has now", async () => {
+/**
+ * The Activity list labels a client "Kids iPad (192.0.2.12)"; the detail page
+ * labels the same query the same way. The address is the recorded fact, and the
+ * intro says once that the device name is today's.
+ */
+test("the client is the device name with its address, as in the Activity list", async () => {
 	responses["/api/queries/12"] = detail(12, { request: { domain: "shop.example", client: "192.0.2.12" } });
 	responses["/api/clients"] = clientList({ ip: "192.0.2.12", name: "Kids iPad", learned_name: "ipad.lan" });
 	renderDetail(12);
 
 	await screen.findByRole("heading", { name: "shop.example" });
-	await relatedText("The client list currently names 192.0.2.12 “Kids iPad”.");
-	expect(factValue("Client")).toBe("192.0.2.12");
+	await waitFor(() => expect(factValue("Client")).toBe("Kids iPad (192.0.2.12)"));
+	expect(screen.getByText(/The device name is the one its address has today\./)).toBeTruthy();
 });
 
-test("a learned name is told as the reverse-DNS lookup it is, never as a recorded fact", async () => {
+test("an address the client list does not know stays a bare address", async () => {
+	responses["/api/queries/14"] = detail(14, { request: { client: "192.0.2.14" } });
+	responses["/api/clients"] = clientList({ ip: "192.0.2.99", name: "Elsewhere", learned_name: "" });
+	renderDetail(14);
+
+	await screen.findByRole("heading", { name: "example.com" });
+	await relatedText("These read the current configuration");
+	expect(factValue("Client")).toBe("192.0.2.14");
+});
+
+test("a learned name is drawn as learned, as in the Activity list", async () => {
 	responses["/api/queries/13"] = detail(13, { request: { client: "192.0.2.13" } });
 	responses["/api/clients"] = clientList({ ip: "192.0.2.13", name: "", learned_name: "printer.lan" });
 	renderDetail(13);
 
 	await screen.findByRole("heading", { name: "example.com" });
-	await relatedText("Reverse DNS currently resolves 192.0.2.13 to printer.lan.");
-	expect(factValue("Client")).toBe("192.0.2.13");
+	await waitFor(() => expect(factValue("Client")).toBe("printer.lan (192.0.2.13)"));
+	const label = screen.getByText("Client").nextElementSibling?.firstElementChild;
+	expect(label?.className).toBe(stylex.props(shared.learnedName).className);
 });
 
 test("a row retention has pruned explains the 404 and keeps the way back to the log", async () => {

admin/src/features/activity/ActivityFilters.tsx

@@ -57,6 +57,12 @@ const PRESETS = [
 
 const CUSTOM_ITEM = "Custom…";
 
+/**
+ * Narrower than the toolbar on one row: the search field's basis, Clients, the
+ * result group, the widest preset's Time label and Clear, with their gaps.
+ */
+const ONE_ROW_DOES_NOT_FIT = "@container (max-width: 48rem)";
+
 const styles = stylex.create({
 	toolbar: {
 		marginTop: "1rem",
@@ -167,13 +173,22 @@ const styles = stylex.create({
 		color: colors.primaryText,
 		outlineColor: { default: null, ":focus-visible": colors.primaryText },
 	},
+	/** The toolbar's controls wrap by the width the form gets, not by the viewport. */
+	form: {
+		containerType: "inline-size",
+	},
 	/**
 	 * Clear keeps its box when there is nothing to clear. It appears the moment a
-	 * filter is set, and a control that appeared by widening the row would move
-	 * every other control out from under the pointer that was reaching for it.
+	 * filter is set, and on the one row the toolbar fits on, a control that
+	 * appeared by widening it would shrink the growing search field and move
+	 * every other control out from under the pointer reaching for it. A toolbar
+	 * too narrow for one row wraps the search field onto a row of its own, so
+	 * there a Clear that appears moves nothing, and a kept box would only wrap
+	 * onto a row of nothing above the table.
 	 */
 	clearHidden: {
 		visibility: "hidden",
+		display: { default: null, [ONE_ROW_DOES_NOT_FIT]: "none" },
 	},
 	customRow: {
 		marginTop: "0.5rem",
@@ -500,7 +515,7 @@ export default function ActivityFilters({ applied, onApply, onClear }: Props) {
 	}
 
 	return (
-		<form onSubmit={flush}>
+		<form onSubmit={flush} {...stylex.props(styles.form)}>
 			<div {...stylex.props(styles.toolbar)}>
 				<div {...stylex.props(styles.searchWrap)}>
 					<span aria-hidden="true" {...stylex.props(styles.searchIcon)}>

admin/src/features/activity/ActivityPage.test.tsx

@@ -12,6 +12,7 @@ import { createAppRouter } from "@/routes";
 import { health } from "@/lib/healthFixture";
 import type { Client, Coverage, QueriesPage, QueryRow } from "@/lib/types";
 import { queryRow } from "@/features/provenance/provenanceFixture";
+import { activityCell } from "./activityCell";
 import { FakeEventSource } from "./fakeEventSource";
 
 function client(id: number, ip: string, name: string, learnedName: string): Client {
@@ -86,7 +87,7 @@ function json(payload: unknown): Response {
 	return new Response(JSON.stringify(payload), { status: 200, headers: { "content-type": "application/json" } });
 }
 
-const VERSION = { version: "0.0.0-test", git_commit: "0000000", zig_version: "0.16.0", uptime_seconds: 1 };
+const VERSION = { version: "0.0.0-test", zig_version: "0.16.0", uptime_seconds: 1 };
 
 /** The shell's own requests, which every test serves the same way. */
 function stubFetch(handler: (url: string) => Response | Promise<Response>) {
@@ -185,17 +186,16 @@ test("renders the first page with the seven columns filled in", async () => {
 		"Route",
 		"Duration",
 	]);
-	const first = screen.getByText("first.example").closest("tr")!;
-	expect(within(first).getByText("HTTPS")).toBeTruthy();
-	expect(within(first).getByText("NOERROR")).toBeTruthy();
-	expect(within(first).getByText("Cache")).toBeTruthy();
-	expect(within(first).getByText("1.2 ms")).toBeTruthy();
+	expect(activityCell("first.example", "Type").textContent).toBe("HTTPS");
+	expect(activityCell("first.example", "Result").textContent).toBe("NOERROR");
+	expect(activityCell("first.example", "Route").textContent).toBe("Cache");
+	expect(activityCell("first.example", "Duration").textContent).toBe("1.2 ms");
 
-	const blocked = screen.getByText("ads.example").closest("tr")!;
 	// The Result cell says Blocked even though the client saw NOERROR, and the
 	// Route cell says how: this is the pair the old Status column could not show.
-	expect(within(blocked).getAllByText("Blocked")).toHaveLength(2);
-	expect(within(blocked).getByText("—")).toBeTruthy();
+	expect(activityCell("ads.example", "Result").textContent).toBe("Blocked");
+	expect(activityCell("ads.example", "Route").textContent).toBe("Blocked");
+	expect(activityCell("ads.example", "Duration").textContent).toBe("—");
 	expect(countLine(/Showing 2 queries/)).toBeTruthy();
 });
 
@@ -216,9 +216,10 @@ test("resolves each row's client to its display name, reading the IP out with it
 	});
 
 	renderPage();
+	await screen.findAllByText("Kitchen Pi");
 
 	// A hand-typed name wins outright; the learned name never surfaces for it.
-	const named = await screen.findByText("Kitchen Pi");
+	const named = within(activityCell("named.example", "Client")).getByText("Kitchen Pi");
 	// The address reads out with the name it replaced, rather than sitting in a
 	// title only a mouse can reach.
 	expect(named.textContent).toBe("Kitchen Pi (192.0.2.10)");
@@ -227,14 +228,39 @@ test("resolves each row's client to its display name, reading the IP out with it
 
 	// A learned name reads muted and nothing more here: the "learned" tag would
 	// repeat on every row of the table, so the Clients page carries it instead.
-	const learned = screen.getByText("laptop.lan");
+	const learned = within(activityCell("learned.example", "Client")).getByText("laptop.lan");
 	expect(learned.textContent).toBe("laptop.lan (192.0.2.11)");
 	expect(within(learned.closest("tr")!).queryByText("learned")).toBeNull();
 
 	// A known client with neither name, and a client the loaded list has never
 	// seen, both fall back to the bare address with nothing standing in for it.
-	expect(screen.getByText("192.0.2.12").textContent).toBe("192.0.2.12");
-	expect(screen.getByText("192.0.2.99").textContent).toBe("192.0.2.99");
+	expect(within(activityCell("nameless.example", "Client")).getByText("192.0.2.12").textContent).toBe("192.0.2.12");
+	expect(within(activityCell("stranger.example", "Client")).getByText("192.0.2.99").textContent).toBe("192.0.2.99");
+});
+
+test("the Domain cell carries the hidden columns' facts for a table too narrow for them", async () => {
+	stubFetch((url) => {
+		if (url === "/api/clients") return json({ clients: CLIENTS });
+		if (url !== "/api/queries") return new Response(JSON.stringify({ error: "not stubbed" }), { status: 404 });
+		return json({
+			queries: [row(20, "named.example", { client_ip: "192.0.2.10" })],
+			next_before: null,
+			coverage: COMPLETE,
+		} satisfies QueriesPage);
+	});
+
+	renderPage();
+	await screen.findAllByText("Kitchen Pi");
+
+	const domain = activityCell("named.example", "Domain");
+	expect(within(domain).getByText("Kitchen Pi").textContent).toBe("Kitchen Pi (192.0.2.10)");
+	const facts = [
+		activityCell("named.example", "Time").textContent,
+		`Type ${activityCell("named.example", "Type").textContent}`,
+		activityCell("named.example", "Route").textContent,
+		activityCell("named.example", "Duration").textContent,
+	].join(" · ");
+	expect(domain.textContent).toContain(facts);
 });
 
 test("load more appends the next page and stops at the end of the log", async () => {

admin/src/features/activity/HistoryActivity.tsx

@@ -36,9 +36,8 @@ const styles = stylex.create({
 	loading: {
 		minHeight: "24rem",
 	},
-	tableWrap: {
-		marginTop: "1rem",
-		overflowX: "auto",
+	/** The shared scrolling wrapper, framed. */
+	framedTable: {
 		borderRadius: metrics.radius,
 		borderWidth: 1,
 		borderStyle: "solid",
@@ -153,7 +152,7 @@ export default function HistoryActivity({ search, onClear }: Props) {
 				</div>
 			) : (
 				<>
-					<div tabIndex={0} {...stylex.props(styles.tableWrap, shared.focusRing)}>
+					<div tabIndex={0} {...stylex.props(shared.tableWrap, styles.framedTable, shared.focusRing)}>
 						<table {...stylex.props(styles.table)}>
 							<ActivityTableHead />
 							<tbody>

admin/src/features/activity/LiveActivity.test.tsx

@@ -15,6 +15,7 @@ import { createAppRouter } from "@/routes";
 import type { Client } from "@/lib/types";
 import { provenance, queryRow } from "@/features/provenance/provenanceFixture";
 import { health } from "@/lib/healthFixture";
+import { activityCell } from "./activityCell";
 import { FakeEventSource } from "./fakeEventSource";
 import LiveActivity from "./LiveActivity";
 import type { ActivitySearch } from "./search";
@@ -48,7 +49,7 @@ const CLIENTS: Client[] = [
 	client("192.0.2.12", "", ""),
 ];
 
-const VERSION = { version: "0.0.0-test", git_commit: "0000000", zig_version: "0.16.0", uptime_seconds: 1 };
+const VERSION = { version: "0.0.0-test", zig_version: "0.16.0", uptime_seconds: 1 };
 
 let sources: FakeEventSource[];
 let fetchMock: ReturnType<typeof vi.fn>;
@@ -187,19 +188,20 @@ test("resolves each row's client to its display name, reading the IP out with it
 		sources[0]!.emit("query", frame(1003, "stranger.example", { request: { client: "192.0.2.99" } }));
 	});
 
-	const named = await screen.findByText("Kitchen Pi");
+	await screen.findAllByText("Kitchen Pi");
+	const named = within(activityCell("named.example", "Client")).getByText("Kitchen Pi");
 	// The address reads out with the name it replaced, rather than sitting in a
 	// title only a mouse can reach.
 	expect(named.textContent).toBe("Kitchen Pi (192.0.2.10)");
 	expect(named.getAttribute("title")).toBeNull();
 	expect(screen.queryByText("pi.lan")).toBeNull();
 
-	const learned = screen.getByText("laptop.lan");
+	const learned = within(activityCell("learned.example", "Client")).getByText("laptop.lan");
 	expect(learned.textContent).toBe("laptop.lan (192.0.2.11)");
 	expect(within(learned.closest("tr")!).queryByText("learned")).toBeNull();
 
-	expect(screen.getByText("192.0.2.12").getAttribute("title")).toBeNull();
-	expect(screen.getByText("192.0.2.99").getAttribute("title")).toBeNull();
+	expect(within(activityCell("nameless.example", "Client")).getByText("192.0.2.12").getAttribute("title")).toBeNull();
+	expect(within(activityCell("stranger.example", "Client")).getByText("192.0.2.99").getAttribute("title")).toBeNull();
 });
 
 test("rows stream in as bare IPs while the client list is still loading", async () => {
@@ -222,11 +224,12 @@ test("rows stream in as bare IPs while the client list is still loading", async
 	await openLive();
 	act(() => sources[0]!.emit("query", frame(1000, "named.example", { request: { client: "192.0.2.10" } })));
 
-	expect(screen.getByText("192.0.2.10")).toBeTruthy();
+	expect(within(activityCell("named.example", "Client")).getByText("192.0.2.10")).toBeTruthy();
 	expect(screen.queryByText("Kitchen Pi")).toBeNull();
 
 	releaseClients();
-	expect(await screen.findByText("Kitchen Pi")).toBeTruthy();
+	await screen.findAllByText("Kitchen Pi");
+	expect(within(activityCell("named.example", "Client")).getByText("Kitchen Pi")).toBeTruthy();
 });
 
 test("repeated connection failures show the viewer-cap state with a retry button", async () => {

admin/src/features/activity/LiveActivity.tsx

@@ -128,9 +128,8 @@ const styles = stylex.create({
 		marginTop: "1.5rem",
 		color: colors.textMuted,
 	},
-	tableWrap: {
-		marginTop: "1rem",
-		overflowX: "auto",
+	/** The shared scrolling wrapper, framed. */
+	framedTable: {
 		borderRadius: metrics.radius,
 		borderWidth: 1,
 		borderStyle: "solid",
@@ -351,7 +350,7 @@ export default function LiveActivity({
 					)
 				) : (
 					<>
-						<div tabIndex={0} {...stylex.props(styles.tableWrap, shared.focusRing)}>
+						<div tabIndex={0} {...stylex.props(shared.tableWrap, styles.framedTable, shared.focusRing)}>
 							<table {...stylex.props(styles.table)}>
 								<ActivityTableHead />
 								<tbody>

admin/src/features/activity/ProvenanceDetail.tsx

@@ -12,7 +12,7 @@ import type { ReactNode } from "react";
 import * as stylex from "@stylexjs/stylex";
 import { formatMicros, formatTime } from "@/lib/format";
 import type { PolicyReason, Provenance } from "@/lib/types";
-import { clientLabel, useClientNames } from "@/features/clients/clientNames";
+import { ClientName, useClientNames } from "@/features/clients/clientNames";
 import {
 	policyActionLabel,
 	policyReasonLabel,
@@ -178,7 +178,6 @@ interface Props {
 export default function ProvenanceDetail({ provenance, persistedId, relatedActions }: Props) {
 	const { request, group, policy, rewrites, route, response } = provenance;
 	const clientNames = useClientNames();
-	const currentClient = clientLabel(request.client, clientNames);
 
 	return (
 		<>
@@ -192,7 +191,8 @@ export default function ProvenanceDetail({ provenance, persistedId, relatedActio
 			<div {...stylex.props(styles.record)}>
 				<p {...stylex.props(styles.recordNote)}>
 					What was recorded when this query was answered. Group and blocklist names are the ones in force at
-					that moment; they may have been renamed or deleted since.
+					that moment; they may have been renamed or deleted since. The device name is the one its address has
+					today.
 					{persistedId === null &&
 						" This is the event as it was streamed; the query log may not have written it yet."}
 				</p>
@@ -203,7 +203,7 @@ export default function ProvenanceDetail({ provenance, persistedId, relatedActio
 						<Mono>{request.domain}</Mono>
 					</Fact>
 					<Fact label="Client">
-						<Mono>{request.client}</Mono>
+						<ClientName ip={request.client} names={clientNames} />
 					</Fact>
 					<Fact label="Type">{qtypeName(request.qtype)}</Fact>
 					<Fact label="Class">{qclassName(request.qclass)}</Fact>
@@ -284,20 +284,6 @@ export default function ProvenanceDetail({ provenance, persistedId, relatedActio
 				<p {...stylex.props(styles.relatedNote)}>
 					These read the current configuration, which may no longer be the one that decided this query.
 				</p>
-				{currentClient !== null && (
-					<p {...stylex.props(styles.relatedNote)}>
-						{currentClient.learned ? (
-							<>
-								Reverse DNS currently resolves <Mono>{request.client}</Mono> to{" "}
-								<Mono>{currentClient.text}</Mono>.
-							</>
-						) : (
-							<>
-								The client list currently names <Mono>{request.client}</Mono> “{currentClient.text}”.
-							</>
-						)}
-					</p>
-				)}
 				<div {...stylex.props(styles.relatedList)}>{relatedActions}</div>
 			</section>
 		</>

admin/src/features/activity/activityCell.ts

@@ -0,0 +1,16 @@
+import { screen, within } from "@testing-library/react";
+import { ACTIVITY_COLUMNS } from "./cells";
+
+/**
+ * Test helper: one column's cell in the row that shows `domain`. jsdom applies
+ * no stylesheet, so the compact Domain cell's copy of the other columns' facts
+ * sits in the document beside the wide cells, and a page-wide text query finds
+ * both.
+ */
+export function activityCell(domain: string, column: (typeof ACTIVITY_COLUMNS)[number]): HTMLElement {
+	const row = screen.getByText(domain).closest("tr");
+	if (row === null) throw new Error(`no row shows ${domain}`);
+	const cell = within(row).getAllByRole("cell")[ACTIVITY_COLUMNS.indexOf(column)];
+	if (cell === undefined) throw new Error(`the row for ${domain} has no ${column} cell`);
+	return cell;
+}

admin/src/features/activity/cells.tsx

@@ -20,6 +20,7 @@ import { ClientName, type ClientNames } from "@/features/clients/clientNames";
 import { rcodeShortName } from "@/features/provenance/provenanceCopy";
 import { qtypeName } from "@/features/provenance/qtype";
 import type { QuerySummary } from "@/features/provenance/querySummary";
+import FactLine from "@/ui/FactLine";
 import { styles as shared } from "@/ui/styles";
 import { colors, metrics } from "@/ui/tokens.stylex";
 
@@ -28,6 +29,15 @@ const DARK = "@media (prefers-color-scheme: dark)";
 /** Wide enough for an ordinary hostname, narrow enough to leave the six other columns room. */
 const DOMAIN_MAX_WIDTH = "24rem";
 
+/**
+ * Narrower than the seven columns need with ordinary data, so the table keeps
+ * two: Domain, which takes the other columns' facts as lines under the name,
+ * and Result. Hiding cells keeps a native table; re-laying its rows out as
+ * blocks would put the table semantics at the mercy of each browser engine.
+ * The wrapper that scrolls is the container.
+ */
+const COMPACT = "@container (max-width: 50rem)";
+
 const styles = stylex.create({
 	head: {
 		backgroundColor: { default: "oklch(98.5% 0 none)", [DARK]: "oklch(21% 0.006 285.885)" },
@@ -52,6 +62,16 @@ const styles = stylex.create({
 	domainCell: {
 		maxWidth: DOMAIN_MAX_WIDTH,
 	},
+	wide: {
+		display: { default: null, [COMPACT]: "none" },
+	},
+	/** A name can be one unbroken label as wide as the table; `anywhere` also lowers the cell's minimum width. */
+	compact: {
+		display: { default: "none", [COMPACT]: "block" },
+		marginTop: "0.125rem",
+		color: colors.textMuted,
+		overflowWrap: "anywhere",
+	},
 	small: {
 		fontSize: "0.75rem",
 		lineHeight: "1rem",
@@ -93,6 +113,7 @@ const styles = stylex.create({
 	 */
 	badge: {
 		display: "inline-block",
+		whiteSpace: "nowrap",
 		borderRadius: metrics.radius,
 		paddingInline: "0.375rem",
 		paddingBlock: "0.125rem",
@@ -152,6 +173,29 @@ export function ResultCellContent({ row }: { row: Pick<QuerySummary, "blocked" |
 	return <span {...stylex.props(styles.small, styles.muted)}>{label}</span>;
 }
 
+/** The facts the hidden columns hold, in their column order, for the compact Domain cell. */
+function CompactFacts({ row, clientNames }: { row: QuerySummary; clientNames: ClientNames }) {
+	// The label stands in for the hidden Type header: a screen reader says a bare "A" as the article.
+	const qtype = (
+		<>
+			<span {...stylex.props(shared.srOnly)}>Type </span>
+			{qtypeName(row.qtype)}
+		</>
+	);
+	const facts: ReactNode[] = [formatTime(row.ts), qtype, routeLabel(row.route_kind)];
+	if (row.response_time_us !== null) facts.push(formatMicros(row.response_time_us));
+	return (
+		<>
+			<span {...stylex.props(styles.compact)}>
+				<ClientName ip={row.client_ip} names={clientNames} />
+			</span>
+			<span {...stylex.props(styles.compact, shared.tabularNums)}>
+				<FactLine facts={facts} />
+			</span>
+		</>
+	);
+}
+
 export function ActivityCells({
 	row,
 	clientNames,
@@ -163,22 +207,23 @@ export function ActivityCells({
 }) {
 	return (
 		<>
-			<td {...stylex.props(styles.cell, styles.nowrap, styles.muted)}>{formatTime(row.ts)}</td>
-			<td
-				title={row.domain}
-				{...stylex.props(styles.cell, styles.small, styles.breakAll, styles.domainCell, shared.mono)}
-			>
-				{renderDomain(row.id, <span {...stylex.props(styles.domainClamp)}>{row.domain}</span>)}
+			<td {...stylex.props(styles.cell, styles.nowrap, styles.muted, styles.wide)}>{formatTime(row.ts)}</td>
+			<td title={row.domain} {...stylex.props(styles.cell, styles.small, styles.domainCell)}>
+				{renderDomain(
+					row.id,
+					<span {...stylex.props(styles.domainClamp, styles.breakAll, shared.mono)}>{row.domain}</span>,
+				)}
+				<CompactFacts row={row} clientNames={clientNames} />
 			</td>
-			<td {...stylex.props(styles.cell, styles.small, styles.nowrap)}>
+			<td {...stylex.props(styles.cell, styles.small, styles.nowrap, styles.wide)}>
 				<ClientName ip={row.client_ip} names={clientNames} />
 			</td>
-			<td {...stylex.props(styles.cell, styles.nowrap)}>{qtypeName(row.qtype)}</td>
+			<td {...stylex.props(styles.cell, styles.nowrap, styles.wide)}>{qtypeName(row.qtype)}</td>
 			<td {...stylex.props(styles.cell, styles.nowrap)}>
 				<ResultCellContent row={row} />
 			</td>
-			<td {...stylex.props(styles.cell, styles.nowrap)}>{routeLabel(row.route_kind)}</td>
-			<td {...stylex.props(styles.cell, styles.nowrap, shared.tabularNums)}>
+			<td {...stylex.props(styles.cell, styles.nowrap, styles.wide)}>{routeLabel(row.route_kind)}</td>
+			<td {...stylex.props(styles.cell, styles.nowrap, shared.tabularNums, styles.wide)}>
 				{row.response_time_us === null ? "—" : formatMicros(row.response_time_us)}
 			</td>
 		</>
@@ -187,12 +232,14 @@ export function ActivityCells({
 
 export const ACTIVITY_COLUMNS = ["Time", "Domain", "Client", "Type", "Result", "Route", "Duration"] as const;
 
+const COMPACT_COLUMNS: ReadonlySet<string> = new Set(["Domain", "Result"]);
+
 export function ActivityTableHead() {
 	return (
 		<thead {...stylex.props(styles.head)}>
 			<tr>
 				{ACTIVITY_COLUMNS.map((column) => (
-					<th key={column} {...stylex.props(styles.th)}>
+					<th key={column} {...stylex.props(styles.th, !COMPACT_COLUMNS.has(column) && styles.wide)}>
 						{column}
 					</th>
 				))}

admin/src/features/clients/ClientsPage.test.tsx

@@ -42,21 +42,42 @@ afterEach(() => {
 	vi.unstubAllGlobals();
 });
 
+const CLIENT_COLUMNS = ["Address", "Name", "Group", "First seen", "Last seen", "Actions"] as const;
+
+/**
+ * One column's cell in the row for `ip`. jsdom applies no stylesheet, so the
+ * compact Address cell's copy of the name and group sits beside the wide cells,
+ * and a page-wide text query finds both.
+ */
+function clientCell(ip: string, column: (typeof CLIENT_COLUMNS)[number]): HTMLElement {
+	const row = screen.getByText(ip).closest("tr")!;
+	return within(row).getAllByRole("cell")[CLIENT_COLUMNS.indexOf(column)]!;
+}
+
 test("renders the identity-first table: address, name, group, first and last seen", async () => {
 	await renderClientsPage();
 
 	const headers = screen.getAllByRole("columnheader").map((cell) => cell.textContent);
-	expect(headers).toEqual(["Address", "Name", "Group", "First seen", "Last seen", "Actions"]);
+	expect(headers).toEqual([...CLIENT_COLUMNS]);
 	expect(screen.getByText("192.168.1.10")).toBeTruthy();
 	expect(screen.getByText("192.168.1.11")).toBeTruthy();
-	expect(screen.getByText("laptop")).toBeTruthy();
+	expect(within(clientCell("192.168.1.10", "Name")).getByText("laptop")).toBeTruthy();
 	expect(screen.getAllByRole("cell", { name: "kids" })).toHaveLength(1);
 });
 
+test("the Address cell carries the name, group and last seen for a table too narrow for them", async () => {
+	await renderClientsPage();
+
+	const address = clientCell("192.168.1.10", "Address");
+	expect(within(address).getByText("laptop")).toBeTruthy();
+	expect(address.textContent).toContain("· default");
+	expect(address.textContent).toContain(`Last seen ${clientCell("192.168.1.10", "Last seen").textContent}`);
+});
+
 test("a named row shows the typed name and hides the learned one", async () => {
 	await renderClientsPage();
 
-	expect(screen.getByText("laptop")).toBeTruthy();
+	expect(within(clientCell("192.168.1.10", "Name")).getByText("laptop")).toBeTruthy();
 	expect(screen.queryByText("laptop-1.lan")).toBeNull();
 });
 
@@ -65,7 +86,7 @@ test("an unnamed row shows the learned name with the learned marker", async () =
 
 	// The cell holds the learned name followed by the marker, so the match is on
 	// the containing span rather than on a bare text node.
-	const learned = screen.getByText(
+	const learned = within(clientCell("192.168.1.11", "Name")).getByText(
 		(content, element) => element?.tagName === "SPAN" && content.startsWith("kids-tablet.lan"),
 	);
 	// The marker is text, not colour, so a screen reader announces it too.

admin/src/features/clients/ClientsPage.tsx

@@ -45,6 +45,13 @@ function clientLabel(client: Client): string {
 	return name === "" ? client.ip : `${name} (${client.ip})`;
 }
 
+/**
+ * Narrower than the six columns need, so the table keeps Address, which takes
+ * the name, group and last-seen time as lines under the link, and the actions.
+ * First seen stays on the client's own page. The wrapper is the container.
+ */
+const COMPACT = "@container (max-width: 50rem)";
+
 const styles = stylex.create({
 	heading: {
 		fontSize: "1.5rem",
@@ -84,7 +91,6 @@ const styles = stylex.create({
 	},
 	table: {
 		width: "100%",
-		minWidth: "48rem",
 		textAlign: "left",
 		fontSize: "0.875rem",
 		lineHeight: "1.25rem",
@@ -107,9 +113,24 @@ const styles = stylex.create({
 	right: {
 		textAlign: "right",
 	},
+	wide: {
+		display: { default: null, [COMPACT]: "none" },
+	},
+	/** A name can be one unbroken label as wide as the table; `anywhere` also lowers the cell's minimum width. */
+	compact: {
+		display: { default: "none", [COMPACT]: "block" },
+		marginTop: "0.125rem",
+		color: colors.textMuted,
+		overflowWrap: "anywhere",
+	},
+	compactName: {
+		color: colors.text,
+	},
+	/** A full IPv6 address is 39 characters of mono, wider than a phone's Address column. */
 	addressLink: {
 		color: colors.primaryOnSurface,
 		textDecorationLine: "none",
+		overflowWrap: "anywhere",
 	},
 	actionGroup: {
 		display: "inline-flex",
@@ -190,10 +211,10 @@ export default function ClientsPage() {
 						<thead>
 							<tr {...stylex.props(styles.headRow)}>
 								<th {...stylex.props(styles.cell)}>Address</th>
-								<th {...stylex.props(styles.cell)}>Name</th>
-								<th {...stylex.props(styles.cell)}>Group</th>
-								<th {...stylex.props(styles.cell)}>First seen</th>
-								<th {...stylex.props(styles.cell)}>Last seen</th>
+								<th {...stylex.props(styles.cell, styles.wide)}>Name</th>
+								<th {...stylex.props(styles.cell, styles.wide)}>Group</th>
+								<th {...stylex.props(styles.cell, styles.wide)}>First seen</th>
+								<th {...stylex.props(styles.cell, styles.wide)}>Last seen</th>
 								<th {...stylex.props(styles.cell)}>
 									<span {...stylex.props(shared.srOnly)}>Actions</span>
 								</th>
@@ -202,23 +223,32 @@ export default function ClientsPage() {
 						<tbody>
 							{rows.map((client) => (
 								<tr key={client.id} {...stylex.props(styles.bodyRow)}>
-									<td {...stylex.props(styles.cell, shared.mono)}>
+									<td {...stylex.props(styles.cell)}>
 										<Link
 											to="/clients/$id"
 											params={{ id: String(client.id) }}
-											{...stylex.props(styles.addressLink, shared.focusRing)}
+											{...stylex.props(styles.addressLink, shared.mono, shared.focusRing)}
 										>
 											{client.ip}
 										</Link>
+										<span {...stylex.props(styles.compact)}>
+											<span {...stylex.props(styles.compactName)}>
+												<ClientDisplayName client={client} />
+											</span>{" "}
+											· {client.group}
+										</span>
+										<span {...stylex.props(styles.compact)}>
+											Last seen {formatTime(client.last_seen)}
+										</span>
 									</td>
-									<td {...stylex.props(styles.cell)}>
+									<td {...stylex.props(styles.cell, styles.wide)}>
 										<span {...stylex.props(styles.name)}>
 											<ClientDisplayName client={client} />
 										</span>
 									</td>
-									<td {...stylex.props(styles.cell)}>{client.group}</td>
-									<td {...stylex.props(styles.cell)}>{formatTime(client.first_seen)}</td>
-									<td {...stylex.props(styles.cell)}>{formatTime(client.last_seen)}</td>
+									<td {...stylex.props(styles.cell, styles.wide)}>{client.group}</td>
+									<td {...stylex.props(styles.cell, styles.wide)}>{formatTime(client.first_seen)}</td>
+									<td {...stylex.props(styles.cell, styles.wide)}>{formatTime(client.last_seen)}</td>
 									<td {...stylex.props(styles.cell, styles.right)}>
 										<span {...stylex.props(styles.actionGroup)}>
 											{/* Naming a client writes configuration, so the affordance is

admin/src/features/clients/NetworkAssignments.tsx

@@ -102,11 +102,14 @@ const styles = stylex.create({
 	},
 	table: {
 		width: "100%",
-		minWidth: "max-content",
 		borderCollapse: "collapse",
 		fontSize: "0.875rem",
 		lineHeight: "1.25rem",
 	},
+	/** A full IPv6 prefix, or a group name, can be one unbroken string wider than a phone's column. */
+	unbroken: {
+		overflowWrap: "anywhere",
+	},
 });
 
 /**
@@ -155,8 +158,8 @@ function AssignmentsTable({ prefixes }: { prefixes: ClientPrefix[] }) {
 				<tbody>
 					{prefixes.map((prefix) => (
 						<tr key={prefix.id}>
-							<td {...stylex.props(shared.td, shared.mono)}>{prefix.prefix}</td>
-							<td {...stylex.props(shared.td)}>{prefix.group}</td>
+							<td {...stylex.props(shared.td, shared.mono, styles.unbroken)}>{prefix.prefix}</td>
+							<td {...stylex.props(shared.td, styles.unbroken)}>{prefix.group}</td>
 							<td {...stylex.props(shared.td, shared.tabularNums)}>{prefix.priority}</td>
 						</tr>
 					))}

admin/src/features/clients/testFixtures.tsx

@@ -50,7 +50,7 @@ export const PREFIXES = {
 	client_prefixes: [{ id: 1, prefix: "192.168.1.0/24", group_id: 2, group: "kids", priority: 100 }],
 };
 
-const VERSION = { version: "0.0.0-test", git_commit: "0000000", zig_version: "0.16.0", uptime_seconds: 1 };
+const VERSION = { version: "0.0.0-test", zig_version: "0.16.0", uptime_seconds: 1 };
 
 export const DATABASE = { authority: "database", path: null, reconciled_at: null, restart_pending: false };
 export const MANAGED_FILE = {

admin/src/features/configuration/LocalReadOnly.tsx

@@ -1,6 +1,7 @@
 import * as stylex from "@stylexjs/stylex";
 import type { ForwardZone, LocalRecord } from "@/lib/types";
 import { styles as shared } from "@/ui/styles";
+import { local, RecordFacts, ZoneResolver } from "./localCells";
 import { styles as config } from "./styles";
 
 /**
@@ -26,18 +27,23 @@ export function RecordsReadOnly({ records }: { records: LocalRecord[] }) {
 						<thead>
 							<tr>
 								<th {...stylex.props(shared.th)}>Name</th>
-								<th {...stylex.props(shared.th)}>Type</th>
-								<th {...stylex.props(shared.th)}>Value</th>
-								<th {...stylex.props(shared.th)}>TTL</th>
+								<th {...stylex.props(shared.th, local.wide)}>Type</th>
+								<th {...stylex.props(shared.th, local.wide)}>Value</th>
+								<th {...stylex.props(shared.th, local.wide)}>TTL</th>
 							</tr>
 						</thead>
 						<tbody>
 							{records.map((record) => (
 								<tr key={record.id}>
-									<td {...stylex.props(shared.td, shared.mono)}>{record.name}</td>
-									<td {...stylex.props(shared.td)}>{record.rtype}</td>
-									<td {...stylex.props(shared.td, shared.mono)}>{record.value}</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>{record.ttl}</td>
+									<td {...stylex.props(shared.td, local.unbroken)}>
+										<span {...stylex.props(shared.mono)}>{record.name}</span>
+										<RecordFacts record={record} />
+									</td>
+									<td {...stylex.props(shared.td, local.wide)}>{record.rtype}</td>
+									<td {...stylex.props(shared.td, shared.mono, local.unbroken, local.wide)}>
+										{record.value}
+									</td>
+									<td {...stylex.props(shared.td, shared.tabularNums, local.wide)}>{record.ttl}</td>
 								</tr>
 							))}
 						</tbody>
@@ -66,14 +72,19 @@ export function ZonesReadOnly({ zones }: { zones: ForwardZone[] }) {
 						<thead>
 							<tr>
 								<th {...stylex.props(shared.th)}>Zone</th>
-								<th {...stylex.props(shared.th)}>Resolver</th>
+								<th {...stylex.props(shared.th, local.wide)}>Resolver</th>
 							</tr>
 						</thead>
 						<tbody>
 							{zones.map((zone) => (
 								<tr key={zone.id}>
-									<td {...stylex.props(shared.td, shared.mono)}>{zone.zone}</td>
-									<td {...stylex.props(shared.td, shared.mono)}>{zone.resolver}</td>
+									<td {...stylex.props(shared.td, shared.mono, local.unbroken)}>
+										{zone.zone}
+										<ZoneResolver zone={zone} />
+									</td>
+									<td {...stylex.props(shared.td, shared.mono, local.unbroken, local.wide)}>
+										{zone.resolver}
+									</td>
 								</tr>
 							))}
 						</tbody>

admin/src/features/configuration/ProtectionGroups.tsx

@@ -19,6 +19,7 @@ import {
 } from "@/lib/queries";
 import type { Blocklist, ConfigStatus, Group, Rule, RuleAction, RuleKind } from "@/lib/types";
 import ConfirmDialog from "@/ui/ConfirmDialog";
+import FactLine from "@/ui/FactLine";
 import DefinitionList from "@/ui/DefinitionList";
 import Select from "@/ui/Select";
 import Switch from "@/ui/Switch";
@@ -43,6 +44,13 @@ const ACTION_OPTIONS = [
 	{ value: "block", label: "block" },
 ];
 
+/**
+ * Narrower than a rule's four columns, or a source's name beside its URL: below
+ * it each table keeps its first column and the actions, and the first cell
+ * carries the rest.
+ */
+const COMPACT = "@container (max-width: 36rem)";
+
 const styles = stylex.create({
 	createForm: {
 		display: "flex",
@@ -96,8 +104,27 @@ const styles = stylex.create({
 	block: {
 		color: colors.danger,
 	},
+	/** A pattern or a URL can be one unbroken string as wide as the table. */
 	pattern: {
 		fontWeight: 500,
+		overflowWrap: "anywhere",
+	},
+	unbroken: {
+		overflowWrap: "anywhere",
+	},
+	/** Read character by character, so a wrapped URL fills each line instead of stranding a "-" on one. */
+	urlText: {
+		wordBreak: "break-all",
+	},
+	wide: {
+		display: { default: null, [COMPACT]: "none" },
+	},
+	compact: {
+		display: { default: "none", [COMPACT]: "block" },
+		marginTop: "0.125rem",
+		color: colors.textMuted,
+		fontWeight: 400,
+		overflowWrap: "anywhere",
 	},
 });
 
@@ -275,6 +302,10 @@ function GroupSourcesReadOnly({ group }: { group: Group }) {
 	);
 }
 
+function ActionLabel({ action }: { action: RuleAction }) {
+	return <span {...stylex.props(action === "allow" ? styles.allow : styles.block)}>{action}</span>;
+}
+
 function AssignedSources({ sourceIds, catalogue }: { sourceIds: number[]; catalogue: Blocklist[] }) {
 	const assigned = catalogue.filter((source) => sourceIds.includes(source.id));
 	if (assigned.length === 0) return <p {...stylex.props(config.empty)}>This group is assigned no sources.</p>;
@@ -284,14 +315,17 @@ function AssignedSources({ sourceIds, catalogue }: { sourceIds: number[]; catalo
 				<thead>
 					<tr>
 						<th {...stylex.props(shared.th)}>Source</th>
-						<th {...stylex.props(shared.th)}>URL</th>
+						<th {...stylex.props(shared.th, styles.wide)}>URL</th>
 					</tr>
 				</thead>
 				<tbody>
 					{assigned.map((source) => (
 						<tr key={source.id}>
-							<td {...stylex.props(shared.td)}>{source.name}</td>
-							<td {...stylex.props(shared.td, shared.mono)}>{source.url}</td>
+							<td {...stylex.props(shared.td, styles.unbroken)}>
+								{source.name}
+								<span {...stylex.props(styles.compact, shared.mono, styles.urlText)}>{source.url}</span>
+							</td>
+							<td {...stylex.props(shared.td, shared.mono, styles.urlText, styles.wide)}>{source.url}</td>
 						</tr>
 					))}
 				</tbody>
@@ -471,9 +505,9 @@ function RulesTable({ rules, editable }: { rules: Rule[]; editable: boolean }) {
 					<thead>
 						<tr>
 							<th {...stylex.props(shared.th)}>Pattern</th>
-							<th {...stylex.props(shared.th)}>Kind</th>
-							<th {...stylex.props(shared.th)}>Action</th>
-							<th {...stylex.props(shared.th)}>Created</th>
+							<th {...stylex.props(shared.th, styles.wide)}>Kind</th>
+							<th {...stylex.props(shared.th, styles.wide)}>Action</th>
+							<th {...stylex.props(shared.th, styles.wide)}>Created</th>
 							{editable && (
 								<th {...stylex.props(shared.th)}>
 									<span {...stylex.props(shared.srOnly)}>Actions</span>
@@ -484,14 +518,23 @@ function RulesTable({ rules, editable }: { rules: Rule[]; editable: boolean }) {
 					<tbody>
 						{rules.map((rule) => (
 							<tr key={rule.id}>
-								<td {...stylex.props(shared.td, styles.pattern)}>{rule.pattern}</td>
-								<td {...stylex.props(shared.td)}>{rule.kind}</td>
-								<td {...stylex.props(shared.td)}>
-									<span {...stylex.props(rule.action === "allow" ? styles.allow : styles.block)}>
-										{rule.action}
+								<td {...stylex.props(shared.td, styles.pattern)}>
+									{rule.pattern}
+									<span {...stylex.props(styles.compact)}>
+										<FactLine
+											facts={[
+												<ActionLabel key="action" action={rule.action} />,
+												rule.kind,
+												`Created ${formatTime(rule.created_at)}`,
+											]}
+										/>
 									</span>
 								</td>
-								<td {...stylex.props(shared.td)}>{formatTime(rule.created_at)}</td>
+								<td {...stylex.props(shared.td, styles.wide)}>{rule.kind}</td>
+								<td {...stylex.props(shared.td, styles.wide)}>
+									<ActionLabel action={rule.action} />
+								</td>
+								<td {...stylex.props(shared.td, styles.wide)}>{formatTime(rule.created_at)}</td>
 								{editable && (
 									<td {...stylex.props(shared.td)}>
 										<button

admin/src/features/configuration/ProtectionPage.test.tsx

@@ -1,4 +1,5 @@
 import { fireEvent, screen, waitFor, within } from "@testing-library/react";
+import { formatTime } from "@/lib/format";
 import { DATABASE, renderPage, stubApi, type Call } from "./testFixtures";
 
 /**
@@ -23,6 +24,15 @@ function writes(method: string): Call[] {
 	return calls.filter((call) => call.method === method);
 }
 
+/**
+ * The first cell of the row that shows `text`. jsdom applies no stylesheet,
+ * so a narrow table's copy of the hidden columns sits in that cell beside the
+ * columns themselves.
+ */
+function firstCell(text: string): HTMLElement {
+	return within(screen.getByText(text).closest("tr")!).getAllByRole("cell")[0]!;
+}
+
 test("the group list is the master, and the selected group is the detail", async () => {
 	await openProtection();
 
@@ -122,6 +132,15 @@ test("only the selected group's rules are listed", async () => {
 	expect(screen.queryByText("ads.example.com")).toBeNull();
 });
 
+test("a rule's Pattern cell carries its action, kind and creation time for a table too narrow for them", async () => {
+	await openProtection(2);
+
+	await screen.findByText("*.social.example");
+	expect(firstCell("*.social.example").textContent).toBe(
+		`*.social.example${["block", "wildcard", `Created ${formatTime(1700000100)}`].join(" · ")}`,
+	);
+});
+
 test("a new rule is created in the selected group, with the pattern posted verbatim for a regex", async () => {
 	await openProtection(2);
 	await screen.findByRole("heading", { name: "Create rule in kids", level: 4 });
@@ -244,6 +263,23 @@ test("the Sources tab lists the catalogue with both skipped columns and their no
 	expect(screen.getByRole("heading", { name: "Add source" })).toBeTruthy();
 });
 
+test("a source's Name cell carries its URL, counts and last update for a table too narrow for them", async () => {
+	calls = stubApi(DATABASE);
+	await renderPage("/configuration/protection?tab=sources", "Protection");
+	await screen.findByText("Trackers");
+
+	const trackers = firstCell("Trackers").textContent;
+	expect(trackers).toContain("https://example.com/trackers.txt");
+	expect(trackers).toContain("50 domains · 0 wildcards · 0 exceptions");
+	expect(trackers).toContain("3 skipped regex · 4 skipped unsupported");
+	expect(trackers).toContain(`Updated ${formatTime(1700000000)}`);
+	// One of each reads in the singular.
+	expect(firstCell("Ads").textContent).toContain("100 domains · 2 wildcards · 1 exception");
+	expect(firstCell("Ads").textContent).toContain("Never updated");
+	// Two zero counts say nothing a reader needs to parse.
+	expect(firstCell("Ads").textContent).toContain("Nothing skipped");
+});
+
 test("a source switch resends the whole row immediately, with no Save step", async () => {
 	calls = stubApi(DATABASE);
 	await renderPage("/configuration/protection?tab=sources", "Protection");

admin/src/features/configuration/ProtectionSources.tsx

@@ -12,6 +12,7 @@ import {
 } from "@/lib/queries";
 import type { Blocklist, BlocklistInput } from "@/lib/types";
 import ConfirmDialog from "@/ui/ConfirmDialog";
+import FactLine from "@/ui/FactLine";
 import { styles as shared } from "@/ui/styles";
 import { colors, metrics } from "@/ui/tokens.stylex";
 import Switch from "@/ui/Switch";
@@ -22,17 +23,24 @@ import QueryPanel from "./QueryPanel";
 import { styles as config } from "./styles";
 
 const SKIPPED_NOTE =
-	"Both “Skipped” columns count lines nxdns read and did not take. Skipped regex lines are patterns nxdns accepts " +
+	"Both skipped counts are lines nxdns read and did not take. Skipped regex lines are patterns nxdns accepts " +
 	"only from you — adopt one you trust as a regex rule. Skipped unsupported lines are syntax nxdns cannot translate " +
 	"into a DNS decision: cosmetic element hiding, browser-only modifiers. A skipped unsupported count that dwarfs the " +
 	"domain count usually means the list is written for a browser extension, and its DNS or hosts variant will block " +
 	"more here.";
 
+/**
+ * Narrower than the ten columns side by side: below it the table keeps Name,
+ * Enabled and the actions, and the Name cell carries the rest.
+ */
+const COMPACT = "@container (max-width: 90rem)";
+
 const styles = stylex.create({
 	name: {
 		fontWeight: 500,
 	},
 	badge: {
+		whiteSpace: "nowrap",
 		marginLeft: "0.5rem",
 		borderRadius: metrics.radius,
 		backgroundColor: colors.border,
@@ -49,15 +57,72 @@ const styles = stylex.create({
 		textOverflow: "ellipsis",
 		whiteSpace: "nowrap",
 	},
+	unbroken: {
+		overflowWrap: "anywhere",
+	},
+	/** Read character by character, so a wrapped URL fills each line instead of stranding a "-" on one. */
+	urlText: {
+		wordBreak: "break-all",
+	},
+	wide: {
+		display: { default: null, [COMPACT]: "none" },
+	},
+	/** A URL or a name can be one unbroken string as wide as the table. */
+	compact: {
+		display: { default: "none", [COMPACT]: "block" },
+		marginTop: "0.125rem",
+		color: colors.textMuted,
+		overflowWrap: "anywhere",
+	},
+	/** Stacked in the narrow form, which gives the first cell the width; the row is several lines tall there already. */
 	actions: {
 		display: "flex",
-		gap: "0.75rem",
+		flexDirection: { default: null, [COMPACT]: "column" },
+		alignItems: { default: null, [COMPACT]: "flex-start" },
+		gap: { default: "0.75rem", [COMPACT]: "0.5rem" },
 	},
 	dimWhenDisabled: {
 		opacity: { default: 1, ":disabled": 0.5 },
 	},
 });
 
+function counted(count: number, one: string, many: string): string {
+	return `${formatCount(count)} ${count === 1 ? one : many}`;
+}
+
+/** The hidden columns' facts, in their column order, for the compact Name cell. */
+function SourceFacts({ source }: { source: Blocklist }) {
+	return (
+		<>
+			<span {...stylex.props(styles.compact, shared.mono, styles.urlText)}>{source.url}</span>
+			<span {...stylex.props(styles.compact, shared.tabularNums)}>
+				<FactLine
+					facts={[
+						counted(source.domain_count, "domain", "domains"),
+						counted(source.wildcard_count, "wildcard", "wildcards"),
+						counted(source.exception_count, "exception", "exceptions"),
+					]}
+				/>
+			</span>
+			<span {...stylex.props(styles.compact, shared.tabularNums)}>
+				{source.skipped_regex_count === 0 && source.skipped_unsupported_count === 0 ? (
+					"Nothing skipped"
+				) : (
+					<FactLine
+						facts={[
+							`${formatCount(source.skipped_regex_count)} skipped regex`,
+							`${formatCount(source.skipped_unsupported_count)} skipped unsupported`,
+						]}
+					/>
+				)}
+			</span>
+			<span {...stylex.props(styles.compact)}>
+				{source.last_updated === null ? "Never updated" : `Updated ${formatTime(source.last_updated)}`}
+			</span>
+		</>
+	);
+}
+
 /**
  * A runtime action: it re-downloads the sources the running process already
  * knows about, so it stays enabled under file authority and while
@@ -142,41 +207,44 @@ function SourcesReadOnly({ blocklists }: { blocklists: Blocklist[] }) {
 						<thead>
 							<tr>
 								<th {...stylex.props(shared.th)}>Name</th>
-								<th {...stylex.props(shared.th)}>URL</th>
+								<th {...stylex.props(shared.th, styles.wide)}>URL</th>
 								<th {...stylex.props(shared.th)}>Enabled</th>
-								<th {...stylex.props(shared.th)}>Domains</th>
-								<th {...stylex.props(shared.th)}>Wildcards</th>
-								<th {...stylex.props(shared.th)}>Exceptions</th>
-								<th {...stylex.props(shared.th)}>Skipped regex</th>
-								<th {...stylex.props(shared.th)}>Skipped unsupported</th>
-								<th {...stylex.props(shared.th)}>Last updated</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Domains</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Wildcards</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Exceptions</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Skipped regex</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Skipped unsupported</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Last updated</th>
 							</tr>
 						</thead>
 						<tbody>
 							{blocklists.map((b) => (
 								<tr key={b.id}>
-									<td {...stylex.props(shared.td)}>
+									<td {...stylex.props(shared.td, styles.unbroken)}>
 										<span {...stylex.props(styles.name)}>{b.name}</span>
 										{b.is_suggested && <span {...stylex.props(styles.badge)}>Suggested</span>}
+										<SourceFacts source={b} />
+									</td>
+									<td {...stylex.props(shared.td, shared.mono, styles.urlText, styles.wide)}>
+										{b.url}
 									</td>
-									<td {...stylex.props(shared.td, shared.mono)}>{b.url}</td>
 									<td {...stylex.props(shared.td)}>{String(b.enabled)}</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>
 										{formatCount(b.domain_count)}
 									</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>
 										{formatCount(b.wildcard_count)}
 									</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>
 										{formatCount(b.exception_count)}
 									</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>
 										{formatCount(b.skipped_regex_count)}
 									</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>
 										{formatCount(b.skipped_unsupported_count)}
 									</td>
-									<td {...stylex.props(shared.td)}>
+									<td {...stylex.props(shared.td, styles.wide)}>
 										{b.last_updated === null ? "never" : formatTime(b.last_updated)}
 									</td>
 								</tr>
@@ -235,14 +303,14 @@ function SourcesEditor({ blocklists }: { blocklists: Blocklist[] }) {
 						<thead>
 							<tr>
 								<th {...stylex.props(shared.th)}>Name</th>
-								<th {...stylex.props(shared.th)}>URL</th>
+								<th {...stylex.props(shared.th, styles.wide)}>URL</th>
 								<th {...stylex.props(shared.th)}>Enabled</th>
-								<th {...stylex.props(shared.th)}>Domains</th>
-								<th {...stylex.props(shared.th)}>Wildcards</th>
-								<th {...stylex.props(shared.th)}>Exceptions</th>
-								<th {...stylex.props(shared.th)}>Skipped regex</th>
-								<th {...stylex.props(shared.th)}>Skipped unsupported</th>
-								<th {...stylex.props(shared.th)}>Last updated</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Domains</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Wildcards</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Exceptions</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Skipped regex</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Skipped unsupported</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Last updated</th>
 								<th {...stylex.props(shared.th)}>
 									<span {...stylex.props(shared.srOnly)}>Actions</span>
 								</th>
@@ -251,11 +319,12 @@ function SourcesEditor({ blocklists }: { blocklists: Blocklist[] }) {
 						<tbody>
 							{blocklists.map((b) => (
 								<tr key={b.id}>
-									<td {...stylex.props(shared.td)}>
+									<td {...stylex.props(shared.td, styles.unbroken)}>
 										<span {...stylex.props(styles.name)}>{b.name}</span>
 										{b.is_suggested && <span {...stylex.props(styles.badge)}>Suggested</span>}
+										<SourceFacts source={b} />
 									</td>
-									<td {...stylex.props(shared.td)}>
+									<td {...stylex.props(shared.td, styles.wide)}>
 										<span {...stylex.props(styles.url)} title={b.url}>
 											{b.url}
 										</span>
@@ -268,22 +337,22 @@ function SourcesEditor({ blocklists }: { blocklists: Blocklist[] }) {
 											onChange={() => toggleEnabled(b)}
 										/>
 									</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>
 										{formatCount(b.domain_count)}
 									</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>
 										{formatCount(b.wildcard_count)}
 									</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>
 										{formatCount(b.exception_count)}
 									</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>
 										{formatCount(b.skipped_regex_count)}
 									</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>
 										{formatCount(b.skipped_unsupported_count)}
 									</td>
-									<td {...stylex.props(shared.td)}>
+									<td {...stylex.props(shared.td, styles.wide)}>
 										{b.last_updated === null ? "never" : formatTime(b.last_updated)}
 									</td>
 									<td {...stylex.props(shared.td)}>

admin/src/features/configuration/RecordsTab.tsx

@@ -12,6 +12,7 @@ import InlineError from "@/lib/InlineError";
 import ConfirmDialog from "@/ui/ConfirmDialog";
 import Select from "@/ui/Select";
 import { useCrudForm } from "@/ui/useCrudForm";
+import { local, RecordFacts } from "./localCells";
 import QueryPanel from "./QueryPanel";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
@@ -230,13 +231,13 @@ export default function RecordsTab() {
 									<th scope="col" {...stylex.props(styles.headCell)}>
 										Name
 									</th>
-									<th scope="col" {...stylex.props(styles.headCell)}>
+									<th scope="col" {...stylex.props(styles.headCell, local.wide)}>
 										Type
 									</th>
-									<th scope="col" {...stylex.props(styles.headCell)}>
+									<th scope="col" {...stylex.props(styles.headCell, local.wide)}>
 										Value
 									</th>
-									<th scope="col" {...stylex.props(styles.headCell)}>
+									<th scope="col" {...stylex.props(styles.headCell, local.wide)}>
 										TTL
 									</th>
 									<th scope="col" {...stylex.props(styles.headCellLast)}>
@@ -266,10 +267,22 @@ export default function RecordsTab() {
 											</td>
 										) : (
 											<>
-												<td {...stylex.props(styles.cell, shared.mono)}>{record.name}</td>
-												<td {...stylex.props(styles.cell)}>{record.rtype}</td>
-												<td {...stylex.props(styles.cell, shared.mono)}>{record.value}</td>
-												<td {...stylex.props(styles.cell)}>{record.ttl}</td>
+												<td {...stylex.props(styles.cell, local.unbroken)}>
+													<span {...stylex.props(shared.mono)}>{record.name}</span>
+													<RecordFacts record={record} />
+												</td>
+												<td {...stylex.props(styles.cell, local.wide)}>{record.rtype}</td>
+												<td
+													{...stylex.props(
+														styles.cell,
+														shared.mono,
+														local.unbroken,
+														local.wide,
+													)}
+												>
+													{record.value}
+												</td>
+												<td {...stylex.props(styles.cell, local.wide)}>{record.ttl}</td>
 												<td {...stylex.props(styles.actionCell)}>
 													<button
 														type="button"

admin/src/features/configuration/ResolutionPage.test.tsx

@@ -1,5 +1,5 @@
 import { fireEvent, screen, waitFor, within } from "@testing-library/react";
-import { DATABASE, contentArea, renderPage, stubApi, type Call } from "./testFixtures";
+import { DATABASE, MANAGED_FILE, contentArea, renderPage, stubApi, type Call } from "./testFixtures";
 
 /**
  * Resolution in database mode: the upstream pool, the local records and the
@@ -22,6 +22,15 @@ async function openResolution(tab?: string, options: Parameters<typeof stubApi>[
 	return renderPage(`/configuration/resolution${suffix}`, "Resolution");
 }
 
+/**
+ * The first cell of the row that shows `text`. jsdom applies no stylesheet,
+ * so a narrow table's copy of the hidden columns sits in that cell beside the
+ * columns themselves.
+ */
+function firstCell(text: string): HTMLElement {
+	return within(screen.getByText(text).closest("tr")!).getAllByRole("cell")[0]!;
+}
+
 /** The row Delete opens the dialog; the dialog's own Delete is the confirm. */
 async function openDeleteDialog(index = 0) {
 	fireEvent.click(screen.getAllByRole("button", { name: "Delete" })[index]!);
@@ -40,6 +49,15 @@ test("the upstream pool is the default tab and lists every field", async () => {
 	expect(screen.getByText(/applies to the next query/)).toBeTruthy();
 });
 
+test("an upstream's URL cell carries its priority and TLS name for a table too narrow for them", async () => {
+	await openResolution();
+	await screen.findByText("tls://9.9.9.9:853");
+
+	expect(firstCell("tls://9.9.9.9:853").textContent).toBe("tls://9.9.9.9:853Priority 200 · TLS name dns.quad9.net");
+	// An empty TLS name has nothing to say in a line of facts.
+	expect(firstCell("udp://1.1.1.1:53").textContent).toBe("udp://1.1.1.1:53Priority 100");
+});
+
 test("adding an upstream posts every field", async () => {
 	await openResolution();
 	await screen.findByRole("heading", { name: "Add upstream" });
@@ -236,6 +254,31 @@ test("the record delete dialog names the record and only deletes on confirm", as
 	expect(writes()[0]).toMatchObject({ method: "DELETE", url: "/api/local-records/1" });
 });
 
+test("a record's Name cell carries its answer and TTL for a table too narrow for them", async () => {
+	await openResolution("records");
+	await screen.findByText("nas.lan.home");
+
+	expect(firstCell("nas.lan.home").textContent).toBe("nas.lan.homeType A value 192.168.1.5TTL 300");
+});
+
+test("a zone's cell carries its resolver for a table too narrow for it", async () => {
+	await openResolution("zones");
+	await screen.findByText("lan.home");
+
+	expect(firstCell("lan.home").textContent).toBe("lan.homeResolver udp://192.168.1.1:53");
+});
+
+test("under file authority the records and zones tables carry the same narrow form", async () => {
+	calls = stubApi(MANAGED_FILE);
+	await renderPage("/configuration/resolution?tab=records", "Resolution");
+	await screen.findByText("nas.lan.home");
+	expect(firstCell("nas.lan.home").textContent).toBe("nas.lan.homeType A value 192.168.1.5TTL 300");
+
+	fireEvent.click(screen.getByRole("tab", { name: "Forward zones" }));
+	await screen.findByText("lan.home");
+	expect(firstCell("lan.home").textContent).toBe("lan.homeResolver udp://192.168.1.1:53");
+});
+
 test("the forward zone delete dialog names the zone and only deletes on confirm", async () => {
 	await openResolution("zones");
 	await screen.findByText("lan.home");

admin/src/features/configuration/UpstreamsTab.tsx

@@ -5,6 +5,7 @@ import InlineError from "@/lib/InlineError";
 import { upstreamCreateMutation, upstreamDeleteMutation, upstreamUpdateMutation, upstreamsQuery } from "@/lib/queries";
 import type { Upstream, UpstreamInput } from "@/lib/types";
 import ConfirmDialog from "@/ui/ConfirmDialog";
+import FactLine from "@/ui/FactLine";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
 import Switch from "@/ui/Switch";
@@ -16,18 +17,41 @@ import { styles as config } from "./styles";
 
 const INTRO = "The pool is rebuilt as you save, so an edit here applies to the next query.";
 
+/**
+ * Narrower than the four columns side by side: below it the table keeps URL,
+ * Enabled and the actions, and the URL cell carries the rest.
+ */
+const COMPACT = "@container (max-width: 42rem)";
+
 const styles = stylex.create({
+	/** Cut to one line beside the other columns; whole, wrapping, where it is the row's only text column. */
 	url: {
 		display: "block",
 		maxWidth: "18rem",
 		overflow: "hidden",
 		textOverflow: "ellipsis",
-		whiteSpace: "nowrap",
+		whiteSpace: { default: "nowrap", [COMPACT]: "normal" },
+		overflowWrap: "anywhere",
 		fontWeight: 500,
 	},
+	unbroken: {
+		overflowWrap: "anywhere",
+	},
+	wide: {
+		display: { default: null, [COMPACT]: "none" },
+	},
+	compact: {
+		display: { default: "none", [COMPACT]: "block" },
+		marginTop: "0.125rem",
+		color: colors.textMuted,
+		overflowWrap: "anywhere",
+	},
+	/** Stacked in the narrow form, which gives the first cell the width; the row is several lines tall there already. */
 	actions: {
 		display: "flex",
-		gap: "0.75rem",
+		flexDirection: { default: null, [COMPACT]: "column" },
+		alignItems: { default: null, [COMPACT]: "flex-start" },
+		gap: { default: "0.75rem", [COMPACT]: "0.5rem" },
 	},
 	dimWhenDisabled: {
 		opacity: { default: 1, ":disabled": 0.5 },
@@ -37,6 +61,17 @@ const styles = stylex.create({
 	},
 });
 
+/** The hidden columns' facts for the compact URL cell; an empty TLS name has nothing to say there. */
+function UpstreamFacts({ upstream }: { upstream: Upstream }) {
+	const facts = [`Priority ${upstream.priority}`];
+	if (upstream.tls_name !== "") facts.push(`TLS name ${upstream.tls_name}`);
+	return (
+		<span {...stylex.props(styles.compact, shared.tabularNums)}>
+			<FactLine facts={facts} />
+		</span>
+	);
+}
+
 export default function UpstreamsTab() {
 	const upstreams = useQuery(upstreamsQuery());
 	return (
@@ -78,18 +113,21 @@ function UpstreamsReadOnly({ upstreams }: { upstreams: Upstream[] }) {
 						<thead>
 							<tr>
 								<th {...stylex.props(shared.th)}>URL</th>
-								<th {...stylex.props(shared.th)}>Priority</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Priority</th>
 								<th {...stylex.props(shared.th)}>Enabled</th>
-								<th {...stylex.props(shared.th)}>TLS name</th>
+								<th {...stylex.props(shared.th, styles.wide)}>TLS name</th>
 							</tr>
 						</thead>
 						<tbody>
 							{upstreams.map((u) => (
 								<tr key={u.id}>
-									<td {...stylex.props(shared.td, shared.mono)}>{u.url}</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>{u.priority}</td>
+									<td {...stylex.props(shared.td, styles.unbroken)}>
+										<span {...stylex.props(shared.mono)}>{u.url}</span>
+										<UpstreamFacts upstream={u} />
+									</td>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>{u.priority}</td>
 									<td {...stylex.props(shared.td)}>{String(u.enabled)}</td>
-									<td {...stylex.props(shared.td)}>
+									<td {...stylex.props(shared.td, styles.unbroken, styles.wide)}>
 										{u.tls_name === "" ? (
 											<span {...stylex.props(styles.absent)}>empty</span>
 										) : (
@@ -151,9 +189,9 @@ function UpstreamsEditor({ upstreams }: { upstreams: Upstream[] }) {
 						<thead>
 							<tr>
 								<th {...stylex.props(shared.th)}>URL</th>
-								<th {...stylex.props(shared.th)}>Priority</th>
+								<th {...stylex.props(shared.th, styles.wide)}>Priority</th>
 								<th {...stylex.props(shared.th)}>Enabled</th>
-								<th {...stylex.props(shared.th)}>TLS name</th>
+								<th {...stylex.props(shared.th, styles.wide)}>TLS name</th>
 								<th {...stylex.props(shared.th)}>
 									<span {...stylex.props(shared.srOnly)}>Actions</span>
 								</th>
@@ -166,8 +204,9 @@ function UpstreamsEditor({ upstreams }: { upstreams: Upstream[] }) {
 										<span {...stylex.props(styles.url)} title={u.url}>
 											{u.url}
 										</span>
+										<UpstreamFacts upstream={u} />
 									</td>
-									<td {...stylex.props(shared.td, shared.tabularNums)}>{u.priority}</td>
+									<td {...stylex.props(shared.td, shared.tabularNums, styles.wide)}>{u.priority}</td>
 									<td {...stylex.props(shared.td)}>
 										<Switch
 											aria-label={`${u.url} enabled`}
@@ -176,7 +215,9 @@ function UpstreamsEditor({ upstreams }: { upstreams: Upstream[] }) {
 											onChange={() => toggleEnabled(u)}
 										/>
 									</td>
-									<td {...stylex.props(shared.td)}>{u.tls_name === "" ? "—" : u.tls_name}</td>
+									<td {...stylex.props(shared.td, styles.unbroken, styles.wide)}>
+										{u.tls_name === "" ? "—" : u.tls_name}
+									</td>
 									<td {...stylex.props(shared.td)}>
 										<div {...stylex.props(styles.actions)}>
 											<button

admin/src/features/configuration/ZonesTab.tsx

@@ -11,6 +11,7 @@ import type { ForwardZone, ForwardZoneInput } from "@/lib/types";
 import InlineError from "@/lib/InlineError";
 import ConfirmDialog from "@/ui/ConfirmDialog";
 import { useCrudForm } from "@/ui/useCrudForm";
+import { local, ZoneResolver } from "./localCells";
 import QueryPanel from "./QueryPanel";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
@@ -200,7 +201,7 @@ export default function ZonesTab() {
 									<th scope="col" {...stylex.props(styles.headCell)}>
 										Zone
 									</th>
-									<th scope="col" {...stylex.props(styles.headCell)}>
+									<th scope="col" {...stylex.props(styles.headCell, local.wide)}>
 										Resolver
 									</th>
 									<th scope="col" {...stylex.props(styles.headCellLast)}>
@@ -230,8 +231,20 @@ export default function ZonesTab() {
 											</td>
 										) : (
 											<>
-												<td {...stylex.props(styles.cell, shared.mono)}>{zone.zone}</td>
-												<td {...stylex.props(styles.cell, shared.mono)}>{zone.resolver}</td>
+												<td {...stylex.props(styles.cell, shared.mono, local.unbroken)}>
+													{zone.zone}
+													<ZoneResolver zone={zone} />
+												</td>
+												<td
+													{...stylex.props(
+														styles.cell,
+														shared.mono,
+														local.unbroken,
+														local.wide,
+													)}
+												>
+													{zone.resolver}
+												</td>
 												<td {...stylex.props(styles.actionCell)}>
 													<button
 														type="button"

admin/src/features/configuration/localCells.tsx

@@ -0,0 +1,56 @@
+import * as stylex from "@stylexjs/stylex";
+import type { ForwardZone, LocalRecord } from "@/lib/types";
+import { styles as shared } from "@/ui/styles";
+import { colors } from "@/ui/tokens.stylex";
+
+/**
+ * The compact forms of the local-records and forward-zones tables, for both
+ * the editable tabs and their file-mode renderings. Below the width a record's
+ * four columns, or a zone beside its resolver, need, a table keeps its first
+ * column and the actions, and the first cell carries the rest. The scrolling
+ * wrapper is the container.
+ */
+const COMPACT = "@container (max-width: 28rem)";
+
+export const local = stylex.create({
+	/** A name, a value or a resolver can be one unbroken string as wide as the table. */
+	unbroken: {
+		overflowWrap: "anywhere",
+	},
+	wide: {
+		display: { default: null, [COMPACT]: "none" },
+	},
+	compact: {
+		display: { default: "none", [COMPACT]: "block" },
+		marginTop: "0.125rem",
+		color: colors.textMuted,
+		overflowWrap: "anywhere",
+	},
+});
+
+/**
+ * The answer, then how long it is cached. The labels stand in for the hidden
+ * headers: a screen reader says a bare "A" as the article, and a CNAME's value
+ * is a second name beside the record's own.
+ */
+export function RecordFacts({ record }: { record: LocalRecord }) {
+	return (
+		<>
+			<span {...stylex.props(local.compact)}>
+				<span {...stylex.props(shared.srOnly)}>Type </span>
+				{record.rtype} <span {...stylex.props(shared.srOnly)}>value </span>
+				<span {...stylex.props(shared.mono)}>{record.value}</span>
+			</span>
+			<span {...stylex.props(local.compact, shared.tabularNums)}>TTL {record.ttl}</span>
+		</>
+	);
+}
+
+export function ZoneResolver({ zone }: { zone: ForwardZone }) {
+	return (
+		<span {...stylex.props(local.compact)}>
+			<span {...stylex.props(shared.srOnly)}>Resolver </span>
+			<span {...stylex.props(shared.mono)}>{zone.resolver}</span>
+		</span>
+	);
+}

admin/src/features/configuration/styles.ts

@@ -77,7 +77,6 @@ export const styles = stylex.create({
 	},
 	table: {
 		width: "100%",
-		minWidth: "max-content",
 		borderCollapse: "collapse",
 		fontSize: "0.875rem",
 		lineHeight: "1.25rem",
@@ -102,8 +101,10 @@ export const styles = stylex.create({
 		flexDirection: "column",
 		gap: "0.25rem",
 	},
+	/** A group name can be one unbroken string wider than a phone's line. */
 	masterLink: {
 		display: "block",
+		overflowWrap: "anywhere",
 		borderRadius: metrics.radius,
 		paddingInline: "0.75rem",
 		paddingBlock: "0.375rem",

admin/src/features/configuration/testFixtures.tsx

@@ -194,7 +194,7 @@ function defaultResponses(status: ConfigStatus): Record<string, unknown> {
 	return {
 		"GET /api/config/status": status,
 		"GET /api/health": health(),
-		"GET /api/version": { version: "0.0.0-test", git_commit: "0000000", zig_version: "0.16.0", uptime_seconds: 1 },
+		"GET /api/version": { version: "0.0.0-test", zig_version: "0.16.0", uptime_seconds: 1 },
 		"GET /api/groups": { groups: GROUPS },
 		"GET /api/groups/1/sources": { source_ids: [1] },
 		"GET /api/groups/2/sources": { source_ids: [] },

admin/src/features/diagnostics/DiagnosticDetailPage.test.tsx

@@ -35,7 +35,7 @@ let requested: string[];
 beforeEach(() => {
 	requested = [];
 	responses = {
-		"/api/version": { version: "0.0.0-test", git_commit: "0000000", zig_version: "0.16.0", uptime_seconds: 1 },
+		"/api/version": { version: "0.0.0-test", zig_version: "0.16.0", uptime_seconds: 1 },
 		// The shell reads health for the Diagnostics nav badge on every route.
 		"/api/health": health(),
 	};

admin/src/features/diagnostics/DiagnosticsPage.test.tsx

@@ -44,7 +44,13 @@ const ACTIVE = page([
 ]);
 
 const RESOLVED = page([
-	event(30, { code: "disk.space", component: "disk", subject: "data", resolved_at: NOW_S - 7200 }),
+	event(30, {
+		code: "disk.space",
+		component: "disk",
+		subject: "data",
+		first_seen: NOW_S - 9000,
+		resolved_at: NOW_S - 7200,
+	}),
 ]);
 
 /**
@@ -77,7 +83,7 @@ let requested: string[];
 beforeEach(() => {
 	requested = [];
 	responses = {
-		"/api/version": { version: "0.0.0-test", git_commit: "0000000", zig_version: "0.16.0", uptime_seconds: 1 },
+		"/api/version": { version: "0.0.0-test", zig_version: "0.16.0", uptime_seconds: 1 },
 		// The health strip at the top of the page; quiet on a healthy box, which is
 		// what every test below wants it to be.
 		"/api/health": health(),
@@ -165,6 +171,16 @@ test("active episodes come first, each with its title, subject, age and count",
 	expect(footerLine("Showing 1 resolved entry — end of history")).toBeTruthy();
 });
 
+test("the Event cell carries the severity, subject and timing for a table too narrow for them", async () => {
+	renderRoute();
+
+	const row = (await screen.findByText("Disk space low")).closest("tr")!;
+	const event = within(row).getAllByRole("cell")[1]!;
+	expect(within(event).getByText("Warning")).toBeTruthy();
+	expect(within(event).getByText("data")).toBeTruthy();
+	expect(event.textContent).toMatch(/Resolved .+ · lasted 30m · 3 occurrences/);
+});
+
 test("nothing open reads as good news, not as a broken page", async () => {
 	responses["/api/diagnostics?state=active"] = page([]);
 	renderRoute();

admin/src/features/diagnostics/DiagnosticsPage.tsx

@@ -14,6 +14,7 @@ import { formatCount, formatDuration, formatTime } from "@/lib/format";
 import { diagnosticPurgeMutation, diagnosticsInfiniteQuery, diagnosticsPurgeResolvedMutation } from "@/lib/queries";
 import type { DiagnosticEvent, DiagnosticSeverity, DiagnosticState, DiagnosticsPage as Page } from "@/lib/types";
 import ConfirmDialog from "@/ui/ConfirmDialog";
+import FactLine from "@/ui/FactLine";
 import Select from "@/ui/Select";
 import { styles as shared } from "@/ui/styles";
 import { colors, metrics } from "@/ui/tokens.stylex";
@@ -41,6 +42,13 @@ const COMPONENT_OPTIONS = [
 	...DIAGNOSTIC_COMPONENTS.map((component) => ({ value: component, label: componentLabel(component) })),
 ];
 
+/**
+ * Narrower than the seven history columns need, so the table keeps Event, which
+ * takes the severity, the subject and the timing as lines around the link, as
+ * an active card does, and the Purge action. The wrapper is the container.
+ */
+const COMPACT = "@container (max-width: 56rem)";
+
 const styles = stylex.create({
 	heading: {
 		fontSize: "1.5rem",
@@ -161,9 +169,9 @@ const styles = stylex.create({
 		lineHeight: "1.25rem",
 		color: colors.textSecondary,
 	},
-	tableWrap: {
+	/** The shared scrolling wrapper, framed. */
+	framedTable: {
 		marginTop: "0.75rem",
-		overflowX: "auto",
 		borderRadius: metrics.radius,
 		borderWidth: 1,
 		borderStyle: "solid",
@@ -197,6 +205,17 @@ const styles = stylex.create({
 	nowrap: {
 		whiteSpace: "nowrap",
 	},
+	wide: {
+		display: { default: null, [COMPACT]: "none" },
+	},
+	compactBadge: {
+		display: { default: "none", [COMPACT]: "inline-block" },
+		marginInlineEnd: "0.5rem",
+	},
+	compact: {
+		display: { default: "none", [COMPACT]: "block" },
+		marginTop: "0.125rem",
+	},
 	rowLink: {
 		color: colors.primaryOnSurface,
 		textDecorationLine: "none",
@@ -207,6 +226,9 @@ const styles = stylex.create({
 		alignItems: "center",
 		gap: "0.75rem",
 	},
+	count: {
+		marginTop: "0.75rem",
+	},
 	note: {
 		fontSize: "0.875rem",
 		lineHeight: "1.25rem",
@@ -340,10 +362,13 @@ function HistoryRow({ event, onPurge, busy }: { event: DiagnosticEvent; onPurge:
 	const copy = copyFor(event.code);
 	return (
 		<tr {...stylex.props(styles.row)}>
-			<td {...stylex.props(styles.cell)}>
+			<td {...stylex.props(styles.cell, styles.wide)}>
 				<SeverityBadge severity={event.severity} />
 			</td>
 			<td {...stylex.props(styles.cell)}>
+				<span {...stylex.props(styles.compactBadge)}>
+					<SeverityBadge severity={event.severity} />
+				</span>
 				<Link
 					to="/diagnostics/$id"
 					params={{ id: String(event.id) }}
@@ -351,13 +376,31 @@ function HistoryRow({ event, onPurge, busy }: { event: DiagnosticEvent; onPurge:
 				>
 					{copy.title}
 				</Link>
+				<span {...stylex.props(styles.compact, styles.subject)}>{event.subject}</span>
+				<span {...stylex.props(styles.compact, styles.meta, shared.tabularNums)}>
+					<FactLine
+						facts={[
+							...(event.resolved_at === null
+								? [`Started ${formatTime(event.first_seen)}`]
+								: [
+										`Resolved ${formatTime(event.resolved_at)}`,
+										`lasted ${formatDuration(event.resolved_at - event.first_seen)}`,
+									]),
+							occurrenceText(event.occurrences),
+						]}
+					/>
+				</span>
 			</td>
-			<td {...stylex.props(styles.cell)}>{event.subject}</td>
-			<td {...stylex.props(styles.cell, styles.nowrap, shared.tabularNums)}>{formatTime(event.first_seen)}</td>
-			<td {...stylex.props(styles.cell, styles.nowrap, shared.tabularNums)}>
+			<td {...stylex.props(styles.cell, styles.wide)}>{event.subject}</td>
+			<td {...stylex.props(styles.cell, styles.nowrap, shared.tabularNums, styles.wide)}>
+				{formatTime(event.first_seen)}
+			</td>
+			<td {...stylex.props(styles.cell, styles.nowrap, shared.tabularNums, styles.wide)}>
 				{event.resolved_at === null ? "—" : formatTime(event.resolved_at)}
 			</td>
-			<td {...stylex.props(styles.cell, styles.nowrap, shared.tabularNums)}>{formatCount(event.occurrences)}</td>
+			<td {...stylex.props(styles.cell, styles.nowrap, shared.tabularNums, styles.wide)}>
+				{formatCount(event.occurrences)}
+			</td>
 			<td {...stylex.props(styles.cell, styles.nowrap)}>
 				<button
 					type="button"
@@ -495,16 +538,16 @@ export default function DiagnosticsPage() {
 						<p {...stylex.props(styles.empty)}>Nothing has failed and recovered in the retained window.</p>
 					) : (
 						<>
-							<div tabIndex={0} {...stylex.props(styles.tableWrap, shared.focusRing)}>
+							<div tabIndex={0} {...stylex.props(shared.tableWrap, styles.framedTable, shared.focusRing)}>
 								<table {...stylex.props(styles.table)}>
 									<thead {...stylex.props(styles.head)}>
 										<tr>
-											<th {...stylex.props(styles.th)}>Severity</th>
+											<th {...stylex.props(styles.th, styles.wide)}>Severity</th>
 											<th {...stylex.props(styles.th)}>Event</th>
-											<th {...stylex.props(styles.th)}>Subject</th>
-											<th {...stylex.props(styles.th)}>Started</th>
-											<th {...stylex.props(styles.th)}>Resolved</th>
-											<th {...stylex.props(styles.th)}>Occurrences</th>
+											<th {...stylex.props(styles.th, styles.wide)}>Subject</th>
+											<th {...stylex.props(styles.th, styles.wide)}>Started</th>
+											<th {...stylex.props(styles.th, styles.wide)}>Resolved</th>
+											<th {...stylex.props(styles.th, styles.wide)}>Occurrences</th>
 											<th {...stylex.props(styles.th)}>
 												<span {...stylex.props(shared.srOnly)}>Actions</span>
 											</th>
@@ -522,7 +565,7 @@ export default function DiagnosticsPage() {
 									</tbody>
 								</table>
 							</div>
-							<p {...stylex.props(styles.footer, styles.note)}>
+							<p {...stylex.props(styles.count, styles.note)}>
 								Showing{" "}
 								<span {...stylex.props(shared.tabularNums)}>{formatCount(historyRows.length)}</span>{" "}
 								resolved {historyRows.length === 1 ? "entry" : "entries"}

admin/src/features/diagnostics/HealthStrip.test.tsx

@@ -42,7 +42,7 @@ beforeEach(() => {
 				return healthFails ? json({ error: "health unavailable" }, 400) : json(healthBody);
 			}
 			if (url === "/api/version")
-				return json({ version: "0.0.0-test", git_commit: "0000000", zig_version: "0.16.0", uptime_seconds: 1 });
+				return json({ version: "0.0.0-test", zig_version: "0.16.0", uptime_seconds: 1 });
 			if (url.startsWith("/api/diagnostics"))
 				return json({ events: [], next_before: null, active: { warnings: 0, errors: 0 } });
 			return json({ error: "not stubbed" }, 404);

admin/src/features/diagnostics/HealthStrip.tsx

@@ -38,11 +38,11 @@ const styles = stylex.create({
 		gap: "0.5rem",
 		// Five is prime, so every count between one and five leaves a short last
 		// row; three columns made it 3 then 2, which reads as a layout that ran out
-		// of room rather than one that chose. So the strip goes from one column
-		// straight to two and then to a single row of five, and is never ragged.
+		// of room rather than one that chose. Two columns, then a single row of
+		// five. One column on a phone stacked five cards over the episodes the
+		// page exists to show.
 		gridTemplateColumns: {
-			default: "minmax(0, 1fr)",
-			"@media (min-width: 640px)": "repeat(2, minmax(0, 1fr))",
+			default: "repeat(2, minmax(0, 1fr))",
 			"@media (min-width: 1100px)": "repeat(5, minmax(0, 1fr))",
 		},
 		listStyleType: "none",
@@ -51,6 +51,8 @@ const styles = stylex.create({
 	fact: {
 		display: "flex",
 		flexWrap: "wrap",
+		// A card stretches to the tallest card in its row; the lines stay at the top.
+		alignContent: "flex-start",
 		alignItems: "baseline",
 		gap: "0.375rem",
 		borderRadius: metrics.radius,
@@ -73,8 +75,10 @@ const styles = stylex.create({
 	label: {
 		color: colors.textSecondary,
 	},
+	/** Below 640px a value always starts its own line, so every card has the same shape. */
 	value: {
 		fontWeight: 500,
+		flexBasis: { default: null, "@media (max-width: 639px)": "100%" },
 	},
 	detail: {
 		flexBasis: "100%",

admin/src/features/overview/ClientChart.test.tsx

@@ -4,6 +4,7 @@ import { createQueryClient } from "@/lib/queryClient";
 import { formatTime } from "@/lib/format";
 import ClientChart, { type ClientChartData } from "./ClientChart";
 import { OTHER_KEY, clientSeriesColor, seriesColor } from "./seriesColors";
+import { STILL_COUNTING_OPACITY } from "./chartKit";
 
 const SINCE = 1_700_000_000;
 const BUCKET = 1800;
@@ -73,7 +74,10 @@ test("the columns are timestamped from this response's own window", () => {
 	render(TWO_BUCKETS);
 
 	const rows = within(screen.getByRole("table")).getAllByRole("rowheader");
-	expect(rows.map((row) => row.textContent)).toEqual([formatTime(SINCE), formatTime(SINCE + BUCKET)]);
+	expect(rows.map((row) => row.textContent)).toEqual([
+		formatTime(SINCE),
+		`${formatTime(SINCE + BUCKET)} · still counting`,
+	]);
 });
 
 /**
@@ -100,7 +104,7 @@ test("the series are coloured by rank, and Other in its own gray", () => {
 		),
 	);
 
-	const fills = Array.from(container.querySelectorAll("rect"))
+	const fills = Array.from(container.querySelectorAll("rect:not([data-still-counting])"))
 		.map((rect) => rect.getAttribute("fill"))
 		.filter((fill) => fill !== "transparent");
 	expect(fills).toEqual([clientSeriesColor(0), clientSeriesColor(1), seriesColor(OTHER_KEY)]);
@@ -209,8 +213,9 @@ test("a refresh that rolls the window takes the tooltip down instead of relabell
 	rerender({ ...TWO_BUCKETS, since: SINCE + BUCKET });
 
 	expect(container.querySelectorAll("dl")).toHaveLength(0);
+	// No dimming is left; the last column stays faint because it is still counting.
 	const stacks = Array.from(container.querySelectorAll("svg > g.visx-group[opacity]"));
-	expect(stacks.every((group) => group.getAttribute("opacity") === "1")).toBe(true);
+	expect(stacks.map((group) => group.getAttribute("opacity"))).toEqual(["1", String(STILL_COUNTING_OPACITY)]);
 });
 
 /** The placement the hand-rolled tooltip had, restored over visx's 10px defaults. */
@@ -261,7 +266,7 @@ test("pointing at a bucket names its busiest clients, then Other, then the total
 	expect(swatches[2]).toContain(seriesColor(OTHER_KEY));
 
 	const stacks = Array.from(container.querySelectorAll("svg > g.visx-group[opacity]"));
-	expect(stacks.map((group) => group.getAttribute("opacity"))).toEqual(["1", "0.55"]);
+	expect(stacks.map((group) => group.getAttribute("opacity"))).toEqual(["1", String(0.55 * STILL_COUNTING_OPACITY)]);
 });
 
 /**
@@ -294,8 +299,9 @@ test("leaving the chart takes the tooltip and the dimming with it", () => {
 
 	fireEvent.mouseOut(container.querySelector("svg") as SVGSVGElement);
 	expect(container.querySelectorAll("dl")).toHaveLength(0);
+	// No dimming is left; the last column stays faint because it is still counting.
 	const stacks = Array.from(container.querySelectorAll("svg > g.visx-group[opacity]"));
-	expect(stacks.every((group) => group.getAttribute("opacity") === "1")).toBe(true);
+	expect(stacks.map((group) => group.getAttribute("opacity"))).toEqual(["1", String(STILL_COUNTING_OPACITY)]);
 });
 
 /**
@@ -310,6 +316,7 @@ test("a window where Other counted nothing keeps it in the legend and the table,
 	expect(Array.from(container.querySelectorAll("ul li")).map((item) => item.textContent)).toEqual([
 		"192.0.2.30",
 		"Other",
+		"Still counting",
 	]);
 	expect(
 		within(screen.getByRole("table"))
@@ -326,3 +333,28 @@ test("the hidden table groups its counts like every other figure on the page", (
 	render(clients([{ client: "192.0.2.30", buckets: [12345] }], [0]));
 	expect(within(screen.getByRole("table")).getByRole("cell", { name: "12,345" })).toBeTruthy();
 });
+
+/**
+ * The API ends every window at the end of the bucket that holds "now", so the
+ * last column is still filling. Drawn like the others it reads as a collapse in
+ * traffic; it is drawn faint inside a dashed outline, and every text says so.
+ */
+test("the last column is still counting, and says so in the drawing, the tooltip and the table", () => {
+	const { container } = render(TWO_BUCKETS);
+
+	const outlines = container.querySelectorAll("rect[data-still-counting]");
+	expect(outlines).toHaveLength(1);
+	expect(outlines[0].getAttribute("stroke-dasharray")).toBeTruthy();
+	expect(screen.getByRole("img").getAttribute("aria-label")).toMatch(/the last still counting$/);
+
+	fireEvent.mouseOver(overlayRects(container)[1]);
+	const tooltip = container.querySelector("dl") as HTMLElement;
+	expect(tooltip.previousElementSibling?.textContent).toBe(`${formatTime(SINCE + BUCKET)} · still counting`);
+});
+
+test("a last column with nothing in it yet draws no outline", () => {
+	const { container } = render(clients([{ client: "192.0.2.30", buckets: [10, 0] }], [2, 0]));
+
+	expect(container.querySelectorAll("rect[data-still-counting]")).toHaveLength(0);
+	expect(Array.from(container.querySelectorAll("ul li")).at(-1)?.textContent).toBe("Still counting");
+});

admin/src/features/overview/ClientChart.tsx

@@ -12,9 +12,10 @@
 import * as stylex from "@stylexjs/stylex";
 import { Group } from "@visx/group";
 import { BarStack } from "@visx/shape";
-import { formatCount, formatTime } from "@/lib/format";
+import { formatCount } from "@/lib/format";
 import type { OverviewClientSeries } from "@/lib/types";
 import { styles as shared } from "@/ui/styles";
+import { colors } from "@/ui/tokens.stylex";
 import { clientLabel, useClientNames, type ClientNames } from "@/features/clients/clientNames";
 import {
 	CHART_HEIGHT,
@@ -25,8 +26,11 @@ import {
 	EmptyChart,
 	HitBands,
 	STACK_BLEED,
+	STILL_COUNTING_DASH,
+	STILL_COUNTING_OPACITY,
 	StackSegment,
 	bandScale,
+	bucketTitle,
 	labelTickValues,
 	plotArea,
 	slotCenter,
@@ -38,6 +42,15 @@ import {
 } from "./chartKit";
 import { OTHER_KEY, clientKey, clientSeriesColor, seriesColor } from "./seriesColors";
 
+const styles = stylex.create({
+	/** The column's outline, over its faint fill: the bucket that is still filling. */
+	stillCounting: {
+		fill: "none",
+		stroke: colors.textSecondary,
+		strokeWidth: 1,
+	},
+});
+
 /** How many named clients a bucket's tooltip lists before the aggregate and the total. */
 const TOOLTIP_CLIENTS = 4;
 
@@ -110,6 +123,7 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 	const yTicks = valueTicks(yScale);
 	const colorOf = new Map(series.map((one) => [one.key, one.color]));
 	const centers = timestamps.map((ts) => slotCenter(xScale, ts, plot));
+	const last = bucketCount - 1;
 
 	/**
 	 * The bucket's busiest clients, then Other, then the total — eight named
@@ -131,7 +145,7 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 			value: formatCount(column[one.key]),
 		}));
 		return {
-			title: formatTime(column.ts),
+			title: bucketTitle(column.ts, index === last),
 			rows: [...rows, { key: "total", label: "All clients", value: formatCount(totals[index]) }],
 		};
 	}
@@ -140,7 +154,7 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 		<ChartRoot containerRef={containerRef}>
 			<svg
 				role="img"
-				aria-label={`Client activity over time, ${formatCount(bucketCount)} buckets, ${formatCount(series.length)} series`}
+				aria-label={`Client activity over time, ${formatCount(bucketCount)} buckets, ${formatCount(series.length)} series, the last still counting`}
 				width="100%"
 				height={CHART_HEIGHT}
 				viewBox={`0 0 ${width} ${CHART_HEIGHT}`}
@@ -166,7 +180,10 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 						columns.map((column, index) => (
 							<Group
 								key={column.ts}
-								opacity={hovered.index === null || hovered.index === index ? 1 : 0.55}
+								opacity={
+									(hovered.index === null || hovered.index === index ? 1 : 0.55) *
+									(index === last ? STILL_COUNTING_OPACITY : 1)
+								}
 							>
 								{stacks.map((stack) => {
 									const bar = stack.bars[index];
@@ -187,6 +204,17 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 						))
 					}
 				</BarStack>
+				{totals[last] > 0 && (
+					<rect
+						data-still-counting=""
+						x={xScale(columns[last].ts) ?? plot.x}
+						y={yScale(totals[last])}
+						width={xScale.bandwidth()}
+						height={plot.bottom - yScale(totals[last])}
+						strokeDasharray={STILL_COUNTING_DASH}
+						{...stylex.props(styles.stillCounting)}
+					/>
+				)}
 				<HitBands plot={plot} centers={centers} onEnter={hovered.show} />
 			</svg>
 			{hovered.index !== null && (
@@ -207,9 +235,9 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 						</tr>
 					</thead>
 					<tbody>
-						{columns.map((column) => (
+						{columns.map((column, index) => (
 							<tr key={column.ts}>
-								<th scope="row">{formatTime(column.ts)}</th>
+								<th scope="row">{bucketTitle(column.ts, index === last)}</th>
 								{series.map((one) => (
 									<td key={one.key}>{formatCount(column[one.key])}</td>
 								))}

admin/src/features/overview/OverviewFrame.tsx

@@ -60,10 +60,14 @@ const styles = stylex.create({
 	toolbar: {
 		display: "flex",
 		gap: "0.5rem",
+		// Without this the row's minimum is both labels at full length, and a
+		// long device name pushes the period picker past the viewport edge.
+		minWidth: 0,
 		flexBasis: { default: null, [NARROW]: "100%" },
 	},
 	control: {
 		minWidth: { default: "11rem", [NARROW]: 0 },
+		maxWidth: { default: "20rem", [NARROW]: "none" },
 		flex: { default: null, [NARROW]: 1 },
 	},
 	/** Under the Device control: the list behind it did not load, so the control offers the household only. */

admin/src/features/overview/OverviewPage.test.tsx

@@ -113,7 +113,7 @@ beforeEach(() => {
 			}
 			if (url === "/api/health") return json(healthBody);
 			if (url === "/api/version")
-				return json({ version: "0.0.0-test", git_commit: "0000000", zig_version: "0.16.0", uptime_seconds: 1 });
+				return json({ version: "0.0.0-test", zig_version: "0.16.0", uptime_seconds: 1 });
 			if (url.startsWith("/api/diagnostics")) {
 				return json({ events: [], next_before: null, active: { warnings: 0, errors: 0 } });
 			}

admin/src/features/overview/TimeseriesChart.test.tsx

@@ -450,7 +450,7 @@ test("the legend names the two curves, and the table adds the remainder", () =>
 	);
 
 	const legend = Array.from(container.querySelectorAll("ul li")).map((item) => item.textContent);
-	expect(legend).toEqual(["Total queries", "Blocked"]);
+	expect(legend).toEqual(["Total queries", "Blocked", "Still counting"]);
 	expect(
 		within(screen.getByRole("table"))
 			.getAllByRole("columnheader")
@@ -470,3 +470,42 @@ test("the hidden table groups its counts like every other figure on the page", (
 			.map((cell) => cell.textContent),
 	).toEqual(["12,345", "1,234", "11,111"]);
 });
+
+/**
+ * The API ends every window at the end of the bucket that holds "now", so the
+ * last bucket is still filling, and a curve falling into it read as a collapse
+ * in traffic. The stretch into the last point is drawn dashed over a fainter
+ * fill, the settled curve stops where it starts, and every text says so.
+ */
+test("the curve into the last bucket is drawn as still counting", () => {
+	const { container } = render(
+		<TimeseriesChart
+			data={timeseries([
+				{ ts: SINCE, queries: 900, blocked: 90, cached: 0 },
+				{ ts: SINCE + 1800, queries: 800, blocked: 80, cached: 0 },
+				{ ts: SINCE + 3600, queries: 130, blocked: 13, cached: 0 },
+			])}
+		/>,
+	);
+
+	const counting = container.querySelector('g[data-series="queries"] g[data-still-counting]') as SVGGElement;
+	const [area, line] = Array.from(counting.querySelectorAll("path"));
+	expect(line.getAttribute("stroke-dasharray")).toBeTruthy();
+	expect(Number(area.getAttribute("fill-opacity"))).toBeLessThan(0.13);
+	expect(seriesPaths(container, "queries").line.getAttribute("stroke-dasharray")).toBeNull();
+
+	// The two clips meet at the second-to-last point, where the settled curve ends.
+	const middleX = pathPoints(seriesPaths(container, "queries").line.getAttribute("d") ?? "")[3][0];
+	const clips = Array.from(container.querySelectorAll("defs rect"));
+	expect(clips).toHaveLength(2);
+	expect(clips[0].getAttribute("width")).toBe(clips[1].getAttribute("x"));
+	expect(Number(clips[0].getAttribute("width"))).toBeCloseTo(middleX, 0);
+
+	expect(screen.getByRole("img").getAttribute("aria-label")).toMatch(/the last still counting$/);
+	fireEvent.mouseOver(overlayRects(container)[2]);
+	const tooltip = container.querySelector("dl") as HTMLElement;
+	expect(tooltip.previousElementSibling?.textContent).toBe(`${formatTime(SINCE + 3600)} · still counting`);
+	const rows = within(screen.getByRole("table")).getAllByRole("rowheader");
+	expect(rows.at(-1)?.textContent).toBe(`${formatTime(SINCE + 3600)} · still counting`);
+	expect(rows[0].textContent).toBe(formatTime(SINCE));
+});

admin/src/features/overview/TimeseriesChart.tsx

@@ -6,8 +6,9 @@
  * the reader is looking at.
  */
 
+import { useId } from "react";
 import * as stylex from "@stylexjs/stylex";
-import { formatCount, formatTime } from "@/lib/format";
+import { formatCount } from "@/lib/format";
 import type { Bucket } from "@/lib/types";
 import { styles as shared } from "@/ui/styles";
 import { colors } from "@/ui/tokens.stylex";
@@ -19,11 +20,15 @@ import {
 	ChartTooltip,
 	EmptyChart,
 	HitBands,
+	STILL_COUNTING_DASH,
+	STILL_COUNTING_OPACITY,
 	areaPath,
+	bucketTitle,
 	labelTickValues,
 	plotArea,
 	pointScale,
 	smoothPath,
+	svgId,
 	useActiveIndex,
 	useMeasuredWidth,
 	valueScale,
@@ -75,9 +80,9 @@ function columnsOf(buckets: Bucket[]): Column[] {
 	}));
 }
 
-function tooltipOf(column: Column): TooltipContent {
+function tooltipOf(column: Column, stillCounting: boolean): TooltipContent {
 	return {
-		title: formatTime(column.ts),
+		title: bucketTitle(column.ts, stillCounting),
 		rows: [
 			...SERIES.map((series) => ({
 				key: series.key,
@@ -105,6 +110,7 @@ export default function TimeseriesChart({ data }: { data: TimeseriesData }) {
 	// A hover survives a re-render only while it still names the same bucket at
 	// the same place: a poll that rolls the window, or a resize, retires it.
 	const hovered = useActiveIndex(`${data.since}:${data.bucket_seconds}:${data.buckets.length}:${width}`);
+	const clipId = svgId(useId());
 
 	if (data.buckets.length === 0 || data.buckets.every((bucket) => bucket.queries === 0)) {
 		return <EmptyChart containerRef={containerRef} />;
@@ -120,12 +126,16 @@ export default function TimeseriesChart({ data }: { data: TimeseriesData }) {
 	const centers = timestamps.map((ts) => xScale(ts) ?? plot.x);
 	const pointsOf = (key: SeriesKey): [number, number][] =>
 		columns.map((column, i) => [centers[i], yScale(column[key])]);
+	const last = columns.length - 1;
+	// The curve into the last point belongs to the bucket that is still
+	// filling, so everything right of the point before it is drawn as such.
+	const settledEdge = last > 0 ? centers[last - 1] : plot.x;
 
 	return (
 		<ChartRoot containerRef={containerRef}>
 			<svg
 				role="img"
-				aria-label={`Queries over time, ${formatCount(data.buckets.length)} buckets: total and blocked queries per bucket`}
+				aria-label={`Queries over time, ${formatCount(data.buckets.length)} buckets: total and blocked queries per bucket, the last still counting`}
 				width="100%"
 				height={CHART_HEIGHT}
 				viewBox={`0 0 ${width} ${CHART_HEIGHT}`}
@@ -139,16 +149,22 @@ export default function TimeseriesChart({ data }: { data: TimeseriesData }) {
 					xTickValues={labelTickValues(timestamps, plot.width)}
 					bucketSeconds={data.bucket_seconds}
 				/>
+				<defs>
+					<clipPath id={`${clipId}-settled`}>
+						<rect x={0} y={0} width={settledEdge} height={CHART_HEIGHT} />
+					</clipPath>
+					<clipPath id={`${clipId}-counting`}>
+						<rect x={settledEdge} y={0} width={Math.max(0, width - settledEdge)} height={CHART_HEIGHT} />
+					</clipPath>
+				</defs>
 				{SERIES.map((series) => {
 					const points = pointsOf(series.key);
 					const line = smoothPath(points, plot.y, plot.bottom);
+					const area = areaPath(line, points, plot);
 					return (
 						<g key={series.key} data-series={series.key}>
-							<path
-								d={areaPath(line, points, plot)}
-								fill={series.color}
-								fillOpacity={series.fillOpacity}
-							/>
+							<g clipPath={`url(#${clipId}-settled)`}>
+								<path d={area} fill={series.color} fillOpacity={series.fillOpacity} />
 								<path
 									d={line}
 									fill="none"
@@ -157,6 +173,22 @@ export default function TimeseriesChart({ data }: { data: TimeseriesData }) {
 									strokeLinejoin="round"
 								/>
 							</g>
+							<g clipPath={`url(#${clipId}-counting)`} data-still-counting="">
+								<path
+									d={area}
+									fill={series.color}
+									fillOpacity={series.fillOpacity * STILL_COUNTING_OPACITY}
+								/>
+								<path
+									d={line}
+									fill="none"
+									stroke={series.color}
+									strokeWidth={LINE_WIDTH}
+									strokeLinejoin="round"
+									strokeDasharray={STILL_COUNTING_DASH}
+								/>
+							</g>
+						</g>
 					);
 				})}
 				{hovered.index !== null && (
@@ -185,7 +217,7 @@ export default function TimeseriesChart({ data }: { data: TimeseriesData }) {
 			{hovered.index !== null && (
 				<ChartTooltip
 					index={hovered.index}
-					content={tooltipOf(columns[hovered.index])}
+					content={tooltipOf(columns[hovered.index], hovered.index === last)}
 					left={centers[hovered.index]}
 					top={yScale(columns[hovered.index].queries)}
 					beside
@@ -206,9 +238,9 @@ export default function TimeseriesChart({ data }: { data: TimeseriesData }) {
 						</tr>
 					</thead>
 					<tbody>
-						{columns.map((column) => (
+						{columns.map((column, index) => (
 							<tr key={column.ts}>
-								<th scope="row">{formatTime(column.ts)}</th>
+								<th scope="row">{bucketTitle(column.ts, index === last)}</th>
 								<td>{formatCount(column.queries)}</td>
 								<td>{formatCount(column.blocked)}</td>
 								<td>{formatCount(column.allowed)}</td>

admin/src/features/overview/chartKit.tsx

@@ -15,7 +15,7 @@ import { AxisBottom, AxisLeft, type TickRendererProps } from "@visx/axis";
 import { GridRows } from "@visx/grid";
 import { scaleBand, scaleLinear, scalePoint } from "@visx/scale";
 import { TooltipWithBounds } from "@visx/tooltip";
-import { formatBucketTime, formatCount } from "@/lib/format";
+import { formatBucketTime, formatCount, formatTime } from "@/lib/format";
 import { styles as shared } from "@/ui/styles";
 import { colors, layers, metrics } from "@/ui/tokens.stylex";
 
@@ -405,6 +405,30 @@ export function StackSegment({
 /** The amount one upper segment overlaps the one under it, in plot units. */
 export const STACK_BLEED = 0.5;
 
+/**
+ * The name for the last bucket of every window. The API ends a window at the
+ * end of the bucket that holds "now" (overview.zig `window`), so that bucket is
+ * still filling, and drawn like the others it reads as a collapse in traffic.
+ * Both charts draw it faint and dashed, and the legend says what that means, so
+ * the meaning does not depend on a hover.
+ */
+export const STILL_COUNTING = "Still counting";
+
+/** Faint enough to read as unfinished beside the settled buckets, not as absent. */
+export const STILL_COUNTING_OPACITY = 0.45;
+
+export const STILL_COUNTING_DASH = "4 3";
+
+/** A tooltip or table title for a bucket, naming the one that is still filling. */
+export function bucketTitle(ts: number, stillCounting: boolean): string {
+	return stillCounting ? `${formatTime(ts)} · ${STILL_COUNTING.toLowerCase()}` : formatTime(ts);
+}
+
+/** `useId` output made safe inside an SVG `url(#…)` reference. */
+export function svgId(reactId: string): string {
+	return reactId.replace(/[^A-Za-z0-9_-]/g, "");
+}
+
 /**
  * The transparent hit targets: one per bucket, spanning the whole plot height so
  * that pointing at the empty space above a short column or a low point still
@@ -607,6 +631,11 @@ const legendStyles = stylex.create({
 		borderRadius: "0.125rem",
 	},
 	swatchColor: (color: string) => ({ backgroundColor: color }),
+	swatchCounting: {
+		borderWidth: 1,
+		borderStyle: "dashed",
+		borderColor: colors.textSecondary,
+	},
 });
 
 /** The key under a chart: one swatch and one name per drawn series, in drawing order. */
@@ -622,6 +651,10 @@ export function ChartLegend({ entries }: { entries: { key: string; label: string
 					{entry.label}
 				</li>
 			))}
+			<li {...stylex.props(legendStyles.item)}>
+				<span aria-hidden="true" {...stylex.props(legendStyles.swatch, legendStyles.swatchCounting)} />
+				{STILL_COUNTING}
+			</li>
 		</ul>
 	);
 }

admin/src/lib/contractSamples.gen.ts

@@ -70,7 +70,6 @@ export const sample_get_health: Health = {
 };
 
 export const sample_get_version: Version = {
-	git_commit: "<build>",
 	uptime_seconds: 0,
 	version: "w10-test",
 	zig_version: "<build>",

admin/src/lib/types.ts

@@ -63,7 +63,6 @@ export interface Health {
 
 export interface Version {
 	version: string;
-	git_commit: string;
 	zig_version: string;
 	uptime_seconds: number;
 }

admin/src/shell/AppShell.test.tsx

@@ -33,7 +33,7 @@ const RESPONSES: Record<string, unknown> = {
 		coverage: { complete: true, available_since: 0 },
 	},
 	"/api/diagnostics?state=active": { events: [], next_before: null, active: { warnings: 0, errors: 0 } },
-	"/api/version": { version: "0.0.0-test", git_commit: "0000000", zig_version: "0.16.0", uptime_seconds: 1 },
+	"/api/version": { version: "0.0.0-test", zig_version: "0.16.0", uptime_seconds: 1 },
 };
 
 /** Null makes the health poll fail, which the nav badge has to treat as unknown. */

admin/src/shell/AppShell.tsx

@@ -213,7 +213,14 @@ const styles = stylex.create({
 		paddingInline: "0.5rem",
 		paddingBlock: "0.5rem",
 	},
+	/**
+	 * Positioned, so it is the containing block of every `srOnly` box on a page,
+	 * such as a chart's data table. A scroll container clips only the absolutely
+	 * positioned boxes it contains; the others extend the document past the
+	 * shell, a second scroll under the one the page already has.
+	 */
 	main: {
+		position: "relative",
 		flex: 1,
 		minHeight: { default: null, [WIDE]: 0 },
 		minWidth: { default: null, [WIDE]: 0 },
@@ -318,7 +325,7 @@ function VersionFooter() {
 	const { data } = useQuery(versionQuery());
 	return (
 		<footer {...stylex.props(styles.versionFooter)}>
-			{data === undefined ? "nxdns" : `nxdns v${data.version} (${data.git_commit.slice(0, 7)})`}
+			{data === undefined ? "nxdns" : `nxdns v${data.version}`}
 		</footer>
 	);
 }

admin/src/styles.css

@@ -32,8 +32,15 @@
 	 * chevron, and Segoe UI does not carry that glyph, so on Windows the stack
 	 * has to reach a font that does before it falls back to a substitute box.
 	 */
+	/*
+	 * `overflow-wrap: break-word` breaks a word only where it cannot fit its line:
+	 * a group or source name is the user's text and can be one unbroken string
+	 * wider than a phone. It leaves min-content alone, so a table cell or a flex
+	 * item that holds such a name still needs `anywhere` of its own.
+	 */
 	html {
 		line-height: 1.5;
+		overflow-wrap: break-word;
 		-webkit-text-size-adjust: 100%;
 		/* The tokens carry both schemes; this tells the UA to match its own chrome — form controls, scrollbars. */
 		color-scheme: light dark;

admin/src/ui/Checkbox.tsx

@@ -55,7 +55,8 @@ const styles = stylex.create({
 	/**
 	 * The whole label is the hit area, so it carries the 44px pointer-target
 	 * floor the dialog's Close button already sets, on both axes. The text is
-	 * 20px tall, and a one-word source name is narrower than 44px again.
+	 * 20px tall, and a one-word source name is narrower than 44px again. A
+	 * source name can also be one unbroken string wider than a phone's line.
 	 */
 	label: {
 		minHeight: 44,
@@ -65,6 +66,7 @@ const styles = stylex.create({
 		gap: "0.5rem",
 		fontSize: "0.875rem",
 		lineHeight: "1.25rem",
+		overflowWrap: "anywhere",
 	},
 	box: {
 		flexShrink: 0,

admin/src/ui/FactLine.tsx

@@ -0,0 +1,25 @@
+import { Fragment, type ReactNode } from "react";
+import * as stylex from "@stylexjs/stylex";
+
+const styles = stylex.create({
+	fact: {
+		display: "inline-block",
+	},
+});
+
+/**
+ * Short facts joined by " · ". A narrow line breaks after a separator, and a
+ * fact moves to the next line whole: "1" and "occurrence" on two lines read as
+ * two facts. Only a fact wider than the whole line breaks inside itself.
+ */
+export default function FactLine({ facts }: { facts: readonly ReactNode[] }) {
+	return facts.map((fact, index) => (
+		<Fragment key={index}>
+			{index > 0 && " "}
+			<span {...stylex.props(styles.fact)}>
+				{fact}
+				{index < facts.length - 1 && " ·"}
+			</span>
+		</Fragment>
+	));
+}

admin/src/ui/Select.tsx

@@ -80,6 +80,9 @@ const styles = stylex.create({
 	},
 	/** Rectangular, hairline, full hit height: the decision record's toolbar selector. */
 	toolbar: {
+		// A button keeps its content width even as a flex container, so without
+		// this the scope picker's 11rem wrapper shows as dead space beside it.
+		width: "100%",
 		minHeight: metrics.hitTarget,
 		borderRadius: metrics.radius,
 		borderWidth: 1,

admin/src/ui/styles.ts

@@ -264,10 +264,21 @@ export const styles = stylex.create({
 		paddingInline: "0.75rem",
 		paddingBlock: "0.5rem",
 	},
-	/** Focusable: a table wider than a phone scrolls sideways, and a keyboard must be able to reach the scroll. */
+	/**
+	 * Focusable: a table whose data is wider than its compact form still
+	 * scrolls sideways, and a keyboard must be able to reach the scroll. It is
+	 * also the size container each table's compact form queries.
+	 *
+	 * Positioned, so it is the containing block of the `srOnly` labels in its
+	 * header cells. A scroll container clips only the absolutely positioned
+	 * boxes it contains; an unclipped label at the far end of a wide table
+	 * widens the whole document, and a phone then zooms the page out to fit it.
+	 */
 	tableWrap: {
+		position: "relative",
 		marginTop: "1rem",
 		overflowX: "auto",
+		containerType: "inline-size",
 	},
 	/**
 	 * Not a faithful port: `space-y-3` set sibling margins on a block container,

build.zig

@@ -43,7 +43,6 @@ pub fn build(b: *std.Build) void {
     // the default, so `zig build` and `zig build test` need no flag.
     const version_option = b.option([]const u8, "version-string", "Version reported by `nxdns version` (required by `dist`)");
     const version_string = version_option orelse "0.1.0-dev";
-    const git_commit = b.option([]const u8, "git-commit", "Git commit reported by `nxdns version`") orelse "unknown";
     const admin_dist = b.option(
         []const u8,
         "admin-dist",
@@ -77,7 +76,6 @@ pub fn build(b: *std.Build) void {
     options.addOption(bool, "integration", integration);
     options.addOption(bool, "live", live);
     options.addOption([]const u8, "version_string", version_string);
-    options.addOption([]const u8, "git_commit", git_commit);
     options.addOption([]const u8, "zig_version_string", builtin.zig_version_string);
     options.addOption([]const u8, "contract_samples_out", contract_samples_out);
 
@@ -318,11 +316,39 @@ pub fn build(b: *std.Build) void {
     // disk, so the test binary has to run at the build root.
     cut_tests_run.setCwd(b.path("."));
     test_step.dependOn(&cut_tests_run.step);
+    // The test binary analyses only what the tests reference; `main` and the
+    // stages behind it are compiled here so a type error in the cut itself
+    // fails `zig build test` and not the release.
+    test_step.dependOn(&cut_tool.step);
+
+    // `dist_stage` owns the release archive bytes, and its reproducibility is
+    // the property the flake pins depend on, so it is tested like any other
+    // decision this build makes.
+    const dist_stage_tests = b.addTest(.{
+        .name = "dist-stage-tool",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("tools/dist_stage.zig"),
+            .target = b.graph.host,
+            .optimize = optimize,
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(dist_stage_tests).step);
+
+    // `gen_admin_assets` decides which files reach the binary, and that set must
+    // not depend on the bundle's provenance, so it is tested here too.
+    const gen_admin_assets_tests = b.addTest(.{
+        .name = "gen-admin-assets-tool",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("tools/gen_admin_assets.zig"),
+            .target = b.graph.host,
+            .optimize = optimize,
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(gen_admin_assets_tests).step);
 
     addDist(b, options, admin_assets, .{
         .version = version_option,
         .version_string = version_string,
-        .git_commit = git_commit,
         .admin_dist = admin_dist,
     });
 }
@@ -355,14 +381,18 @@ const DistOptions = struct {
     /// from one that happens to equal the default.
     version: ?[]const u8,
     version_string: []const u8,
-    git_commit: []const u8,
     admin_dist: []const u8,
 };
 
-/// `dist` builds everything releasable; `verify-dist` asserts the result.
-/// Both run on a laptop exactly as they run on the runner, which is the point:
-/// release checks that only exist in CI shell are the brittleness milestone 14
-/// set out to remove.
+/// `dist` builds everything releasable; `verify-dist` asserts the result;
+/// `pin-flake` writes the resulting hashes into `flake.nix` and `verify-pins`
+/// asserts that they still describe the bytes under `zig-out/dist`.
+///
+/// All four run on a laptop exactly as they run on the runner, which is the
+/// point: release checks that only exist in CI shell are the brittleness
+/// milestone 14 set out to remove. The pins depend on it twice over — the cut
+/// writes them here and CI recomputes them there, and the two only agree
+/// because it is one build graph rather than two scripts.
 fn addDist(
     b: *std.Build,
     options: *std.Build.Step.Options,
@@ -371,11 +401,15 @@ fn addDist(
 ) void {
     const dist_step = b.step("dist", "Build the release tarballs, checksums and staged payloads");
     const verify_step = b.step("verify-dist", "Verify the release artifacts under zig-out/dist");
+    const pin_step = b.step("pin-flake", "Write the release hashes under zig-out/dist into flake.nix");
+    const verify_pins_step = b.step("verify-pins", "Check flake.nix pins the hashes of the release under zig-out/dist");
 
     if (distPreflight(b, dist_options)) |problem| {
         const fail = b.addFail(problem);
         dist_step.dependOn(&fail.step);
         verify_step.dependOn(&fail.step);
+        pin_step.dependOn(&fail.step);
+        verify_pins_step.dependOn(&fail.step);
         return;
     }
 
@@ -401,7 +435,6 @@ fn addDist(
     verify_run.addArgs(&.{ "--dist-dir", b.getInstallPath(.prefix, "dist") });
     verify_run.addArgs(&.{ "--work-dir", b.getInstallPath(.prefix, "dist-verify") });
     verify_run.addArgs(&.{ "--version", dist_options.version_string });
-    verify_run.addArgs(&.{ "--git-commit", dist_options.git_commit });
     verify_run.addArg("--zon");
     verify_run.addFileArg(b.path("build.zig.zon"));
     verify_run.addArgs(&.{ "--max-bytes", b.fmt("{d}", .{max_binary_bytes}) });
@@ -447,36 +480,19 @@ fn addDist(
         stage_run.addArg("--licenses");
         stage_run.addDirectoryArg(staged_licenses);
 
-        // Two commands, never one: `addSystemCommand` executes argv directly
-        // and does not interpret `|`, and a shell pipeline without `pipefail`
-        // would report only gzip's status while a failed tar passed silently.
-        const tar_run = b.addSystemCommand(&.{
-            "tar",
-            "--format=gnu",
-            "--sort=name",
-            "--mtime=@0",
-            "--owner=0",
-            "--group=0",
-            "--numeric-owner",
-            "-c",
-            "-f",
-        });
-        setReproducibleEnv(tar_run);
-        const tar_file = tar_run.addOutputFileArg(b.fmt("{s}.tar", .{name}));
-        tar_run.addArg("-C");
+        // The tarball is written by our own tool rather than by the runner's
+        // `tar` and `gzip`: the release hashes are pinned in `flake.nix` before
+        // CI rebuilds them, so the bytes may depend on the staged tree and on
+        // nothing else the host supplies.
+        const archive_run = b.addRunArtifact(stage_tool);
+        archive_run.addArg("archive");
+        archive_run.addArg("--root");
         // The staged payload is the sole entry of its cache directory, so its
-        // parent is what `-C` needs and declaring it declares the payload.
-        tar_run.addDirectoryArg(staged.dirname());
-        tar_run.addArg(name);
-
-        // `-n` is required because `--mtime=@0` normalises the tar member times
-        // but not the timestamp gzip writes into its own header. `-c` is
-        // required because plain `gzip <file>` rewrites its input in place, and
-        // the input here is a content-addressed cache entry.
-        const gzip_run = b.addSystemCommand(&.{ "gzip", "-n", "-9", "-c" });
-        setReproducibleEnv(gzip_run);
-        gzip_run.addFileArg(tar_file);
-        const tarball = gzip_run.captureStdOut(.{ .basename = b.fmt("{s}.tar.gz", .{name}) });
+        // parent is what `--root` needs and declaring it declares the payload.
+        archive_run.addDirectoryArg(staged.dirname());
+        archive_run.addArgs(&.{ "--payload", name });
+        archive_run.addArg("--out");
+        const tarball = archive_run.addOutputFileArg(b.fmt("{s}.tar.gz", .{name}));
 
         const install_binary = b.addInstallFile(
             staged.path(b, "nxdns"),
@@ -513,6 +529,38 @@ fn addDist(
 
     verify_run.step.dependOn(dist_step);
     verify_step.dependOn(&verify_run.step);
+
+    // The pins in `flake.nix` are written before CI ever builds the release, so
+    // the run that rebuilds it has to prove they describe its own bytes.
+    //
+    // It is a step of its own and NOT part of `verify-dist`. An ordinary commit
+    // between two cuts builds the `build.zig.zon` version from a tree that
+    // differs from the released one, so its bytes never match the pins and
+    // checking them there would fail every such build. The two CI jobs that may
+    // not skip it call it by name: the package job on the bump commit, and the
+    // publish job unconditionally before any upload.
+    const pin_check_run = b.addRunArtifact(stage_tool);
+    pin_check_run.has_side_effects = true;
+    pin_check_run.addArg("pin-check");
+    pin_check_run.addArgs(&.{ "--sums", b.getInstallPath(.prefix, "dist/SHA256SUMS") });
+    pin_check_run.addArg("--flake");
+    pin_check_run.addFileArg(b.path("flake.nix"));
+    pin_check_run.addArgs(&.{ "--version", dist_options.version_string });
+    pin_check_run.step.dependOn(dist_step);
+    verify_pins_step.dependOn(&pin_check_run.step);
+
+    // The write half, run by the cut and by nothing else. `flake.nix` is named
+    // as a plain path rather than a `LazyPath`: this run edits the source file
+    // in place, and a file argument would declare it an input of a step that is
+    // in fact its author.
+    const pin_run = b.addRunArtifact(stage_tool);
+    pin_run.has_side_effects = true;
+    pin_run.addArg("pin");
+    pin_run.addArgs(&.{ "--sums", b.getInstallPath(.prefix, "dist/SHA256SUMS") });
+    pin_run.addArgs(&.{ "--flake", b.pathFromRoot("flake.nix") });
+    pin_run.addArgs(&.{ "--version", dist_options.version_string });
+    pin_run.step.dependOn(dist_step);
+    pin_step.dependOn(&pin_run.step);
 }
 
 /// The one message `dist` and `verify-dist` fail with when the release inputs
@@ -564,13 +612,6 @@ fn hostTool(b: *std.Build, name: []const u8) *std.Build.Step.Compile {
     });
 }
 
-/// Locale and time zone leak into archive metadata and into tool output.
-/// Pinning both is the cheap half of reproducibility (milestone-14 ruling 12).
-fn setReproducibleEnv(run: *std.Build.Step.Run) void {
-    run.setEnvironmentVariable("LC_ALL", "C");
-    run.setEnvironmentVariable("TZ", "UTC");
-}
-
 /// Milestone-15 ruling 4: every `*.zig` under `src/` must appear in
 /// `src/tests.zig` as a line that trims to exactly `_ = @import("<path>");`,
 /// where `<path>` is relative to `src/`. Whole-line equality, not a substring
@@ -744,7 +785,10 @@ fn addExecutable(
     exe.root_module.addAnonymousImport("admin_assets", .{ .root_source_file = admin_assets });
     exe.root_module.linkLibrary(sqliteLibrary(b, target, optimize));
     exe.root_module.linkLibrary(mbedtlsLibrary(b, target, optimize));
-    exe.root_module.addCSourceFile(.{ .file = b.path("src/platform/mbedtls_shim.c") });
+    exe.root_module.addCSourceFile(.{
+        .file = b.path("src/platform/mbedtls_shim.c"),
+        .flags = &.{filePrefixMap(b, .build_root)},
+    });
     addMbedtlsThreadingMacros(exe.root_module);
     return exe;
 }
@@ -810,6 +854,8 @@ fn sqliteLibrary(
             "-DSQLITE_THREADSAFE=1",
             "-DSQLITE_DEFAULT_WAL_SYNCHRONOUS=1",
             "-DSQLITE_OMIT_LOAD_EXTENSION",
+            filePrefixMap(b, .build_root),
+            filePrefixMap(b, .global_cache),
         },
     });
     return lib;
@@ -846,19 +892,34 @@ fn mbedtlsLibrary(
         lib.root_module.addIncludePath(dep.path(include_dir));
     }
 
+    const c_flags = [_][]const u8{ filePrefixMap(b, .build_root), filePrefixMap(b, .global_cache) };
     lib.root_module.addCSourceFiles(.{
         .root = dep.path("library"),
         .files = &mbedtls_library_sources,
+        .flags = &c_flags,
     });
     lib.root_module.addCSourceFiles(.{
         .root = dep.path("3rdparty"),
         .files = &mbedtls_3rdparty_sources,
+        .flags = &c_flags,
     });
     lib.installHeadersDirectory(dep.path("include/mbedtls"), "mbedtls", .{});
     lib.installHeadersDirectory(dep.path("include/psa"), "psa", .{});
     return lib;
 }
 
+/// `__FILE__` in the C sources (mbedTLS debug and assertion macros) would
+/// otherwise embed the absolute checkout path into the release binary, and the
+/// flake pins require the bytes to be the same on every machine that builds
+/// the tag. Both roots a dependency can be stored under are mapped.
+fn filePrefixMap(b: *std.Build, root: enum { build_root, global_cache }) []const u8 {
+    const path = switch (root) {
+        .build_root => b.build_root.path orelse ".",
+        .global_cache => b.graph.global_cache_root.path orelse ".",
+    };
+    return b.fmt("-ffile-prefix-map={s}=.", .{path});
+}
+
 /// Context sizes change with threading enabled, so every compilation unit that
 /// includes mbedTLS headers (the library itself and `mbedtls_shim.c`) must see
 /// the same macros. Concurrent handshakes share `ssl_config`, the CTR-DRBG, and

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .nxdns,
-    .version = "0.0.16",
+    .version = "0.0.24",
     .minimum_zig_version = "0.16.0",
     .paths = .{""},
     .fingerprint = 0x3307b311dded1d91,

deploy/docker/Dockerfile

@@ -1,7 +1,7 @@
 # The binary is NOT compiled here. Build it first, from the repository root:
 #
 #   (cd admin && npm ci && npm run build)
-#   zig build dist -Dversion-string=<V> -Dgit-commit=<SHA> \
+#   zig build dist -Dversion-string=<V> \
 #       -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe
 #
 # then build the image with the repository root as context:

deploy/docker/compose.yaml

@@ -1,10 +1,11 @@
 services:
   nxdns:
-    # Published multi-architecture image. Pin an exact version in production:
-    # NXDNS_VERSION=0.0.1 docker compose up -d. To run a locally built image
-    # instead, build it first (see deploy/docker/Dockerfile) and set
-    # NXDNS_IMAGE=nxdns.
-    image: ${NXDNS_IMAGE:-git.mial.net/mokhtar/nxdns:${NXDNS_VERSION:-latest}}
+    # Published multi-architecture image. The default is the release this file
+    # is tagged with: `zig build cut` moves it in the bump commit, so the file
+    # from a tag runs that tag's image. NXDNS_VERSION picks another release. To
+    # run a locally built image instead, build it first (see
+    # deploy/docker/Dockerfile) and set NXDNS_IMAGE=nxdns.
+    image: ${NXDNS_IMAGE:-git.mial.net/mokhtar/nxdns:${NXDNS_VERSION:-0.0.24}}
     restart: unless-stopped
     # `run --config` makes the file the sole source of configuration: nxdns
     # reconciles the database onto ./etc-nxdns/config.zon at every start, and

docs/README.md

@@ -22,6 +22,7 @@ Steps for a goal you already have. They assume you know what nxdns is.
 - [how-to/verify-a-release.md](how-to/verify-a-release.md) — check the signature and the checksums before you run anything, and what they prove.
 - [how-to/install-with-systemd.md](how-to/install-with-systemd.md) — a real install as a system service, including the Raspberry Pi 5 aarch64 binary.
 - [how-to/install-with-docker.md](how-to/install-with-docker.md) — the published container image and the compose file.
+- [how-to/install-with-nix.md](how-to/install-with-nix.md) — the flake input pinned to a release tag, the `services.nxdns` NixOS module, and Renovate for tag bumps.
 - [how-to/upgrade.md](how-to/upgrade.md) — move to a new release without losing state.
 - [how-to/troubleshoot.md](how-to/troubleshoot.md) — what to do when it does not answer, does not block, or will not start.
 - [how-to/enable-doh-and-dot.md](how-to/enable-doh-and-dot.md) — serve encrypted DNS with certificates.

docs/docs.zig

@@ -11,6 +11,7 @@ pub const tutorial_first_run_md = @embedFile("tutorial/first-run.md");
 pub const howto_back_up_and_restore_md = @embedFile("how-to/back-up-and-restore.md");
 pub const howto_enable_doh_and_dot_md = @embedFile("how-to/enable-doh-and-dot.md");
 pub const howto_install_with_docker_md = @embedFile("how-to/install-with-docker.md");
+pub const howto_install_with_nix_md = @embedFile("how-to/install-with-nix.md");
 pub const howto_install_with_systemd_md = @embedFile("how-to/install-with-systemd.md");
 pub const howto_measure_performance_md = @embedFile("how-to/measure-performance.md");
 pub const howto_set_up_admin_authentication_md = @embedFile("how-to/set-up-admin-authentication.md");
@@ -34,6 +35,7 @@ pub const pages: []const Page = &.{
     .{ .path = "docs/how-to/back-up-and-restore.md", .text = howto_back_up_and_restore_md },
     .{ .path = "docs/how-to/enable-doh-and-dot.md", .text = howto_enable_doh_and_dot_md },
     .{ .path = "docs/how-to/install-with-docker.md", .text = howto_install_with_docker_md },
+    .{ .path = "docs/how-to/install-with-nix.md", .text = howto_install_with_nix_md },
     .{ .path = "docs/how-to/install-with-systemd.md", .text = howto_install_with_systemd_md },
     .{ .path = "docs/how-to/measure-performance.md", .text = howto_measure_performance_md },
     .{ .path = "docs/how-to/set-up-admin-authentication.md", .text = howto_set_up_admin_authentication_md },

docs/explanation/performance-and-testing.md

@@ -79,8 +79,6 @@ Two honest gaps remain, stated so nobody has to rediscover them:
 
 The same distinction applies one level out, to the artifacts. A release is signed, and the signature is worth having: it says the artifact came from this project's pipeline and reached you unaltered. It does not say the binary was built from the source in this repository, because the machine that ran the build also held the signing key. An attacker with that machine produces something that verifies cleanly and contains whatever they put in it.
 
-The control that closes that gap is a reproducibility gate — an independent build, in a different directory on a different machine, landing on the same bytes. It does not exist. It is a recorded deferral (`specs/milestone-14.md` ruling 12), not something nobody thought of, and until it exists no document here describes the build as reproducible: nobody has measured whether it is. The cheap inputs to reproducibility are already in place — `gzip -n`, `--mtime=@0`, `LC_ALL=C`, `TZ=UTC`, exact Zig and Node pins — which makes the gate cheap to add later and proves nothing on its own.
+The control that closes that gap is a reproducibility gate — an independent build, in a different directory on a different machine, landing on the same bytes. Every release from 0.0.17 on passes one (milestone 40, which closed the deferral in `specs/milestone-14.md` ruling 12). The cut builds the tarballs on the maintainer's machine and writes their hashes into `flake.nix`; the release job rebuilds them on the CI runner from the tagged tree, and `zig build verify-pins` refuses to let anything be uploaded unless the two builds landed on the same bytes. What makes that hold: the binary embeds no commit sha, the archive is written by the project's own tool with fixed modes, zero timestamps and sorted entries, and Zig, Node and npm are pinned to exact versions and run in a normalized environment.
 
-What the release pipeline is required to hold to is narrower: two runs of `zig build dist` on the same commit **in the same directory** produce byte-identical tarballs. Same-directory determinism is a much weaker property than reproducibility, and conflating the two is exactly the kind of claim this page exists to refuse.
-
-[Verify a release](../how-to/verify-a-release.md) states the same limits where an operator will actually meet them, and gives the rebuild-and-compare recipe with the caveat that a differing hash is not evidence of tampering while this gap is open.
+What the gate does not show: both builds run on machines the maintainer controls, so it proves the pipeline is deterministic across two hosts, not that someone independent of the project has rebuilt it. That is what the rebuild recipe in [Verify a release](../how-to/verify-a-release.md) is for, and anyone can run it. It reproduces the release only on x86_64 Linux with glibc, because the admin bundle is built with host-native Rolldown and Lightning CSS bindings.

docs/how-to/install-with-docker.md

@@ -6,18 +6,9 @@ The image is multi-architecture — `linux/amd64` and `linux/arm64` — so the s
 
 For what each configuration field means, see [the configuration reference](../reference/configuration.md).
 
-> Verification: the failure modes, the run and the two checks in step 3 were run
-> on the machine that wrote an earlier revision of this page, against an image
-> built from this checkout rather than pulled from the registry — no release is
-> published yet, so nothing on this page could be run against a pulled image,
-> and step 1 could not be run at all. One command was run in altered form: host
-> port 8080 was occupied there, so the run and the verification commands in
-> step 3 were executed with the host side of the port mappings moved to 25353
-> and 28088 rather than the 53 and 8080 printed below. The container side was
-> unchanged. See the note in step 3. The `chown` to uid 65532 needs root and was
-> not run.
+> Verification: on 2026-10-02, steps 1 to 3 were run against the published `v0.0.21` release with an image pulled anonymously from the registry, on the host ports printed below; the notes in those steps carry the detail. The failure modes in step 2 were run on the machine that wrote an earlier revision of this page, against an image built from this checkout. The `chown` to uid 65532 needs root and was not run.
 >
-> **Not re-run for the file-mode revision.** The compose file now ships
+> **Earlier, for the file-mode revision.** The compose file now ships
 > `command: ["run", "--config=/etc/nxdns/config.zon"]`, and no container was
 > started against that command on this host: staging a release image needs
 > `zig build dist`, which refuses to run while `admin/dist` is stale, and the web
@@ -56,12 +47,7 @@ cut -d@ -f2 IMAGE-DIGEST.txt
 
 The last two have to print the same string — `IMAGE-DIGEST.txt` holds a whole pinned reference, `name:tag@sha256:…`, so the `cut` is what reduces it to the digest `imagetools` prints. [Verify a release](verify-a-release.md) covers the key, the fingerprint, every failure message, and what the signature does and does not prove.
 
-> Not verified on this host: no image and no release are published yet, so
-> `docker pull` and every URL here fail today, and the `releases/latest` lookup
-> returns 404 and leaves `VERSION` empty. That lookup was run against
-> `gitea.com/gitea/tea` on Gitea `1.27.0+dev` and printed `0.15.1`. The
-> `docker buildx imagetools inspect --format` shape was run here against
-> `alpine:3.22` on Docker Hub and printed that image's index digest.
+> Verified on 2026-10-02 against `v0.0.21`, with an empty `DOCKER_CONFIG`, so no registry credentials: the lookup printed `0.0.21`, `docker pull` succeeded without a login, `gpg --verify` printed `Good signature` with the primary fingerprint above, `sha256sum -c` printed `OK` for all three files, and `imagetools inspect` and the `cut` both printed `sha256:ce1fef32c7ee6c23656abd94e53e4d4d6b1d34fe88a2c842b82c7202d8b904c3`.
 
 ## 2. Get the compose file and write the configuration
 
@@ -72,9 +58,7 @@ mkdir -p ~/nxdns && cd ~/nxdns
 curl -fLO "$BASE/raw/tag/v$VERSION/deploy/docker/compose.yaml"
 ```
 
-> Not verified against nxdns: there is no tag yet. The Gitea raw-file URL shape
-> `<repo>/raw/tag/<tag>/<path>` was run here against `gitea.com/gitea/tea` on
-> Gitea `1.27.0+dev` and returned the file with a 200.
+> Verified on 2026-10-02: the `curl` returned `compose.yaml` from the `v0.0.21` tag with a 200.
 
 Compose bind-mounts `deploy/docker/etc-nxdns` read-only at `/etc/nxdns`. Create it and put the configuration in it:
 
@@ -148,17 +132,17 @@ chmod 0600 deploy/docker/etc-nxdns/config.zon
 ## 3. Run it
 
 ```sh
-NXDNS_VERSION=$VERSION docker compose -f deploy/docker/compose.yaml up -d
+docker compose -f deploy/docker/compose.yaml up -d
 docker compose -f deploy/docker/compose.yaml logs -f
 ```
 
-`compose.yaml` reads the image from two variables: `${NXDNS_IMAGE:-git.mial.net/mokhtar/nxdns:${NXDNS_VERSION:-latest}}`. Set `NXDNS_VERSION` to pin a release; set `NXDNS_IMAGE` to run something else entirely, which is what the build-from-source section at the bottom does.
+`compose.yaml` names the release it was tagged with: its image is `${NXDNS_IMAGE:-git.mial.net/mokhtar/nxdns:${NXDNS_VERSION:-<release>}}`, and `zig build cut` writes `<release>` in the same commit that bumps `build.zig.zon`, so the file from the `v$VERSION` tag runs `$VERSION` with no variable set. Set `NXDNS_VERSION` to run a different release with the same file; set `NXDNS_IMAGE` to run something else entirely, which is what the build-from-source section at the bottom does. Compose files from `v0.0.22` and earlier default to `:latest` instead, so with one of those, set `NXDNS_VERSION=$VERSION` on every command.
 
-> Verified on this host with `docker compose -f deploy/docker/compose.yaml
-> config`, which resolves the variables without contacting a registry: no
-> variables gives `git.mial.net/mokhtar/nxdns:latest`, `NXDNS_VERSION=0.0.1`
-> gives `git.mial.net/mokhtar/nxdns:0.0.1`, and `NXDNS_IMAGE=nxdns` gives
-> `nxdns`.
+> Verified on 2026-10-20 with `docker compose -f deploy/docker/compose.yaml
+> config` on a tree whose `build.zig.zon` declares `0.0.22`, which resolves
+> the variables without contacting a registry: no variables gives
+> `git.mial.net/mokhtar/nxdns:0.0.22`, `NXDNS_VERSION=0.0.21` gives
+> `git.mial.net/mokhtar/nxdns:0.0.21`, and `NXDNS_IMAGE=nxdns` gives `nxdns`.
 
 Every block on this page runs from the repository root, and none of them change directory, so they can be pasted in order. `-f` is what makes that work: Compose resolves the relative paths inside `compose.yaml` — the `etc-nxdns` bind mount — against the directory holding the file, not against your shell, and it takes the project name `docker` from that directory either way, which is why the container is `docker-nxdns-1`.
 
@@ -166,7 +150,7 @@ A healthy first start logs the reconcile, the authority and the bound sockets:
 
 ```
 info(migrations): config.db migrated from schema version 0 to 1
-reconciled '/etc/nxdns/config.zon': upstreams +1 ~0 -0; settings +45 ~0 -0;
+reconciled '/etc/nxdns/config.zon': upstreams +1 ~0 -0; settings +46 ~0 -0;
 settings keys changed: dns.bind_ipv4 dns.bind_ipv6 dns.port web.bind web.port …
 web authentication is now enabled
 info(nxdns): authority: file (/etc/nxdns/config.zon)
@@ -183,15 +167,7 @@ dig @127.0.0.1 example.com A +short
 curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/
 ```
 
-> On the machine that wrote this page, host port 8080 was already taken by an
-> unrelated process, so the container was verified with the host side of the
-> port mappings moved to 25353 and 28088 — everything inside the container was
-> unchanged, and the log still reads `serving on udp [::]:53`. Against those
-> ports `dig` returned the A records for `example.com` and `curl` returned 200.
-> `docker compose up -d` fails with
-> `failed to bind host port 0.0.0.0:8080/tcp: address already in use` when a
-> host port is occupied; free the port or edit the `ports:` list. The image
-> under test was built locally, not pulled: there is nothing published to pull.
+> Verified on 2026-10-02 with the pulled `v0.0.21` image, the configuration above and the unchanged `compose.yaml`, on host ports 53 and 8080: the first start logged the lines above, `dig` returned the A records for `example.com`, `curl` returned 200, and `/api/health` reported `"status":"ok"` with one of one upstreams available. `docker compose up -d` fails with `failed to bind host port 0.0.0.0:8080/tcp: address already in use` when a host port is occupied; free the port or edit the `ports:` list.
 
 The compose file publishes 53/udp, 53/tcp and 8080, keeps `/var/lib/nxdns` in the named volume `nxdns-data`, and sets the per-namespace sysctl `net.ipv4.ip_unprivileged_port_start=0` so uid 65532 can bind port 53 without any capability. Uncomment the 443 and 853 mappings when you enable the DoH or DoT listener; see [Enable DoH and DoT](enable-doh-and-dot.md).
 
@@ -209,9 +185,7 @@ To pull the arm64 image from an x86_64 machine — to inspect it, or to save and
 docker pull --platform linux/arm64 git.mial.net/mokhtar/nxdns:$VERSION
 ```
 
-> Not verified on this host: nothing is published to pull, and this host is
-> x86_64 with no emulation, so an arm64 image could not be started here even
-> if it were.
+> Verified on 2026-10-02 against `v0.0.21`: `imagetools inspect` lists `linux/amd64` and `linux/arm64`, and the pull above fetched an image whose `docker image inspect` reports `linux/arm64`. It was not started: this host is x86_64 with no emulation.
 
 ## Build the image from source instead
 
@@ -220,7 +194,7 @@ The Dockerfile does not compile anything. It assembles a filesystem around binar
 ```sh
 (cd admin && npm ci && npm run build)
 VERSION=$(sed -n 's/^[[:space:]]*\.version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' build.zig.zon)
-zig build dist -Dversion-string="$VERSION" -Dgit-commit="$(git rev-parse HEAD)" \
+zig build dist -Dversion-string="$VERSION" \
     -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe
 DOCKER_BUILDKIT=1 docker build -t nxdns -f deploy/docker/Dockerfile .
 ```

docs/how-to/install-with-nix.md

@@ -0,0 +1,126 @@
+# Install nxdns with Nix
+
+Adds nxdns to a NixOS machine as a flake input pinned to a release tag and runs it with the flake's `services.nxdns` module. At the end the machine serves DNS on port 53 from a configuration file that the pinned binary checked at build time, and a Renovate custom manager opens a pull request when a new tag appears.
+
+nxdns publishes its own `flake.nix`. Its packages do not build nxdns from source: each one fetches the release tarball for the target and pins its SHA-256 hash, so a changed byte fails the build. The two supported systems are `aarch64-linux` and `x86_64-linux`, both static musl builds that need nothing on the host.
+
+For the signature and checksum checks a human does once, see [verify a release](verify-a-release.md). For what each configuration field means, see [the configuration reference](../reference/configuration.md).
+
+> Verification: the commands in step 1 and step 2 were run on the machine that wrote this page, against the flake at nxdns 0.0.16. `nix flake check --no-build` passed and `nix build` produced a binary that printed `nxdns 0.0.16`. Step 3 was verified on 2026-10-20 by the flake's own checks, built with Nix 2.35.3 on an x86_64 host with KVM and the module running the 0.0.22 release: `checks.x86_64-linux.nixos-module` boots a NixOS VM with the module and `openFirewall`, gets `nas.lan` from `dig @127.0.0.1`, finds the packaged unit with its drop-in in `systemctl cat`, finds port 53 open over UDP and TCP, and switches to a configuration-only change that restarts the service and changes the answer; `checks.x86_64-linux.nixos-module-rejects-config` fails a system build on a bad regex with `FAIL rules[0].pattern: '(' is not a valid regex pattern`. The Renovate snippet in step 4 is copied from the shape `rpi.mial.net` already uses for another flake input of the same author.
+
+## 1. Add the input, pinned to a tag
+
+In the consuming flake:
+
+```nix
+inputs = {
+  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+  nxdns = {
+    url = "git+https://git.mial.net/mokhtar/nxdns.git?ref=refs/tags/v0.0.16";
+    inputs.nixpkgs.follows = "nixpkgs";
+  };
+};
+```
+
+Pin a tag, not a branch. A branch pin moves the version under you at the next `nix flake update`, and the hashes in the flake belong to whatever release that branch last cut.
+
+The `follows` line is not cosmetic. Without it Nix fetches and evaluates nxdns's own nixpkgs as a second nixpkgs, which costs a download and an evaluation for a package that only needs `stdenv`, `fetchurl`, and `lib`.
+
+Write the lock entry:
+
+```sh
+nix flake lock
+```
+
+## 2. Check what you pinned
+
+```sh
+nix flake check --no-build
+nix eval .#packages.x86_64-linux.default.outPath
+```
+
+Evaluation does not fetch the tarball. The download happens at build time, and the hash in nxdns's flake is what the build asserts the bytes against.
+
+## 3. Run the service
+
+`nixosModules.default` exists from the first release after `v0.0.22`; pin that tag or a later one. A tag up to `v0.0.22` has the package only.
+
+Write the configuration next to the NixOS configuration that uses it. The smallest file that starts is one group named `default` and one enabled upstream:
+
+```zon
+.{
+    .groups = .{ .{ .name = "default" } },
+    .upstreams = .{ .{ .url = "https://cloudflare-dns.com/dns-query" } },
+}
+```
+
+Pass the flake inputs to the module system, import the module, and enable it:
+
+```nix
+{ inputs, ... }:
+{
+  imports = [ inputs.nxdns.nixosModules.default ];
+
+  services.nxdns = {
+    enable = true;
+    configFile = ./nxdns-config.zon;
+    openFirewall = true;
+  };
+}
+```
+
+Then `nixos-rebuild switch`. The module has four options:
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `enable` | `false` | Runs nxdns as `nxdns.service`, as the `nxdns` system user. |
+| `package` | the release of the pinned tag | The nxdns release to run. |
+| `configFile` | none, required | The configuration, in ZON. It is installed at `/etc/nxdns/config.zon`. |
+| `openFirewall` | `false` | Opens port 53 over UDP and TCP. The web interface on port 8080 and the DoH and DoT ports stay closed; open them yourself if you want them reachable from the network. |
+
+`configFile` is copied into the Nix store, which every local user can read. Do not put a plaintext `web.password` in it: put the `web.password_hash` from an export there instead, as [set up admin authentication](set-up-admin-authentication.md) describes.
+
+What the module does with them:
+
+- **The build checks the configuration.** `nxdns import` from the pinned `package` reads `configFile` into a throwaway database during the build. A file that `import` rejects, because it does not parse, breaks a field rule or does not reconcile, fails `nixos-rebuild` with the binary's own reason, as in `FAIL rules[0].pattern: ...`, and nothing is deployed. `nxdns check` is not used, because it queries every upstream and the build sandbox has no network. So the build does not load the DoH and DoT certificate and key files, and does not reach the upstreams: a missing certificate still stops the service at start. The build also says nothing about the database already on the machine; see the rollback note below.
+- **nxdns runs in file mode.** The service runs `nxdns run --config=/etc/nxdns/config.zon`: every start reconciles the database onto the file, and the web interface refuses configuration edits. Change the file and switch to change anything. A switch that changes only the configuration restarts the service.
+- **The unit is the packaged one.** The package installs `deploy/systemd/nxdns.service` from the release tarball, with its sandboxing and its `RestartPreventExitStatus=2 64`, and the module adds a drop-in that changes only the command line and leaves `/etc/nxdns` to NixOS. `systemctl cat nxdns.service` shows both.
+
+The module does not touch the machine's own resolver. If you point `networking.nameservers` at `127.0.0.1`, the machine loses name resolution whenever nxdns is down, including while you repair it; a resolver outside the machine avoids that.
+
+**Rolling back.** A `nixos-rebuild --rollback` or an older generation puts an older binary in front of a database that the newer one may have migrated. That binary refuses the database with `SchemaTooNew`, exit 2, and the unit stops instead of restarting. [Upgrade](upgrade.md#what-happens-to-the-database) describes the recovery.
+
+The package alone is also available, for a machine that runs nxdns some other way: `inputs.nxdns.packages.${pkgs.stdenv.hostPlatform.system}.default` installs `bin/nxdns`, `lib/systemd/system/nxdns.service`, and `LICENSE` and `THIRD-PARTY-NOTICES` under `share/doc/nxdns`. It sets `meta.mainProgram`, so `lib.getExe` resolves to the binary.
+
+## 4. Let Renovate bump the tag
+
+Renovate's built-in `nix` manager does not do this. It only advances `flake.lock` along the ref an input already tracks, and a `refs/tags/vX.Y.Z` ref never moves, so it reports no releases for a tag-pinned input. Verified on 2026-09-09 with Renovate 42.99.0 against a Gitea host: all flake inputs, GitHub-hosted ones included, came back with an empty release list.
+
+What works is a regex custom manager that treats the tag in the input URL as a version string, with the `gitea-tags` datasource:
+
+```json
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "customManagers": [
+    {
+      "customType": "regex",
+      "managerFilePatterns": ["/^flake\\.nix$/"],
+      "matchStrings": ["git\\+https://git\\.mial\\.net/mokhtar/nxdns\\.git\\?ref=refs/tags/(?<currentValue>v\\d+\\.\\d+\\.\\d+)"],
+      "depNameTemplate": "mokhtar/nxdns",
+      "datasourceTemplate": "gitea-tags",
+      "registryUrlTemplate": "https://git.mial.net",
+      "versioningTemplate": "semver"
+    }
+  ]
+}
+```
+
+Verified on 2026-09-09: with this manager, Renovate opened the pull request for v0.0.18 on the day of the tag. That pull request rewrites the tag in `flake.nix` only. `flake.lock` still records the old revision, so the same pull request must also refresh the lock, either with a `postUpgradeTasks` command (`nix flake update nxdns`, which needs the self-hosted `allowedCommands` setting) or with a CI job on the Renovate branch that commits the lock. The datasource proposes only tags that already exist, so it never pins a release that has not been cut.
+
+Between the tag push and the asset upload there is a window in which the tag exists and the release tarballs do not. A pin written by hand during that window evaluates, then fails at build time with a 404 from the release download URL. Wait for the release to be published, or re-run the build once it is. Renovate's own pull requests are not affected by the window in practice, because it runs on a schedule rather than on the tag push.
+
+## Upgrading
+
+Change the `?ref=refs/tags/vX.Y.Z` in the input, run `nix flake lock --update-input nxdns`, and rebuild. Read the release notes first: nxdns is pre-0.1 and breaks on purpose, and [upgrade](upgrade.md) lists what state a version change touches.

docs/how-to/install-with-systemd.md

@@ -14,12 +14,7 @@ For what each flag does, see [the CLI reference](../reference/cli.md); for what
 > target host — `install`, `systemd-sysusers`, `systemctl` — were not run; they
 > are marked where they appear.
 >
-> The download in step 1 could not be run at all: this repository has no tags
-> and no published release, so every release URL on this page is a 404 today.
-> Its commands are the ones [Verify a release](verify-a-release.md) covers in
-> full, and the URL shapes — including the `releases/latest` redirect the
-> version is read from — were probed there against `gitea.com`, a public
-> instance running the same Gitea series.
+> The download in step 1 was run on 2026-10-02 against the published `v0.0.21` release; its note carries the detail.
 >
 > The `zig build dist` and `zig build verify-dist` blocks in the last section
 > were run here, both to completion and both exiting 0; that section carries
@@ -62,10 +57,7 @@ The extracted directory `nxdns-$VERSION-x86_64-linux-musl/` holds everything thi
 | `THIRD-PARTY-NOTICES` | Licences of everything compiled or bundled in |
 | `INSTALL.md` | A short version of this page |
 
-> Not verified on this host: no release exists yet, so none of these commands
-> could be run against one — the `releases/latest` lookup returns 404 for this
-> repository and leaves `VERSION` empty. The same lookup was run against
-> `gitea.com/gitea/tea` on Gitea `1.27.0+dev` and printed `0.15.1`.
+> Verified on 2026-10-02 against `v0.0.21`, from a clean directory with a clean `GNUPGHOME` holding only the key from keys.openpgp.org: the lookup printed `0.0.21`, `gpg --verify` printed `Good signature` over primary fingerprint `A206 1F6A B24D F2C0 E923  46FD 1509 B549 46D0 8A95`, `sha256sum -c` printed `OK` for both tarballs and `IMAGE-DIGEST.txt`, and the extracted directory held the six files in the table below at the modes given, with `./nxdns version` printing `nxdns 0.0.21`.
 
 ## 2. Copy the files to the target
 
@@ -364,9 +356,7 @@ scp nxdns nxdns.service nxdns.conf pi:/tmp/
 
 Then follow steps 3 to 6 on the Pi.
 
-> Not verified on this host: no release exists to download, `pi` is a
-> placeholder for your Pi's hostname, and this page was written on an x86_64
-> machine with no Pi attached.
+> Partly verified on 2026-10-02: the `v0.0.21` aarch64 tarball downloaded and `sha256sum -c` printed `OK` for it. The `scp` and steps 3 to 6 were not run: `pi` is a placeholder for your Pi's hostname, and this page was written on an x86_64 machine with no Pi attached.
 
 ## Build from source instead
 
@@ -377,13 +367,13 @@ Requires Zig 0.16.0 and Node.js. From the repository root:
 ```sh
 (cd admin && npm ci && npm run build)
 VERSION=$(sed -n 's/^[[:space:]]*\.version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' build.zig.zon)
-zig build dist -Dversion-string="$VERSION" -Dgit-commit="$(git rev-parse HEAD)" \
+zig build dist -Dversion-string="$VERSION" \
     -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe
 ```
 
 The first command builds the admin interface into `admin/dist`; the last one embeds that directory in the binary. Build the interface every time, before the binary: a stale `admin/dist` ships an admin UI that does not match the API it talks to. `dist` refuses to run against the `admin/dist-placeholder` default for exactly that reason, so there is no way to skip it by accident.
 
-`-Dversion-string` is required and has no default. It is what `nxdns version` prints. Take it from `build.zig.zon` rather than inventing one: `verify-dist` asserts that the version under build equals `.version` there, so a made-up string like `0.0.0-local` builds but then fails verification. `-Dgit-commit` is what distinguishes your build from the published one of the same version.
+`-Dversion-string` is required and has no default. It is what `nxdns version` prints. Take it from `build.zig.zon` rather than inventing one: `verify-dist` asserts that the version under build equals `.version` there, so a made-up string like `0.0.0-local` builds but then fails verification.
 
 What comes out under `zig-out/dist/` is the same set a release publishes, minus the signature and the image digest:
 
@@ -397,7 +387,7 @@ The two targets are `x86_64-linux-musl` and `aarch64-linux-musl`. Both binaries
 Check the result the same way the release pipeline does:
 
 ```sh
-zig build verify-dist -Dversion-string="$VERSION" -Dgit-commit="$(git rev-parse HEAD)" \
+zig build verify-dist -Dversion-string="$VERSION" \
     -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe
 ```
 

docs/how-to/measure-performance.md

@@ -114,6 +114,26 @@ Read the client's own rate and the server's `/metrics` together: a load generato
 
 **Not verified on this host:** `dnsperf` is not installed here and the target platform is a Raspberry Pi 5, not this development machine. The command above is the shape of the measurement, not a transcript.
 
+## Measure memory on a running server
+
+The bench measures one structure at a time. A running server's memory also depends on the most concurrent work it has seen since it started, so read it on the server itself, after it has served a normal day:
+
+```sh
+pid=$(pidof nxdns)
+grep -E 'VmRSS|VmHWM|Threads' /proc/$pid/status
+curl -s http://127.0.0.1:8080/metrics | grep '^nxdns_.*_peak'
+```
+
+- `VmRSS` is what the process holds resident now. `VmHWM` is the most it has ever held, which is normally the last blocklist refresh.
+- `Threads` is a high-water too: the I/O runtime adds a worker thread only when every existing worker is busy, and never retires one. The count is the largest the worker pool has been since start, plus the main thread.
+- `nxdns_dns_in_flight_peak` is the most queries handled at once, every listener together.
+- `nxdns_tcp_server_connections_peak`, `nxdns_dot_server_connections_peak` and `nxdns_doh_server_connections_peak` are the most connections one listener has held at once. TCP/53 has one listener per address family; the gauge is the larger of the two.
+- `nxdns_querylog_queue_peak` is the most entries that have waited for the query log writer at once. It can overstate the true peak by the entries in transit at that instant, never understate it.
+
+Each worker thread's stack is its own anonymous mapping in `/proc/$pid/smaps`, directly above a one-page `---p` guard, and every worker's mapping has the same size. Its `Rss` is the stack that thread has actually touched.
+
+**Verified on this host** against a static x86_64 musl build under a burst of 300 UDP queries: the gauges and the stack mappings behave as described. Not yet run on the Pi.
+
 ## Where to run it
 
 The target platform is a Raspberry Pi 5. Numbers from a development x86_64 box do not transfer — the Pi's Cortex-A76 is far slower — so a passing run here is evidence the harness works and a baseline for spotting regressions on the machine development happens on, and nothing more. Run `--assert` on the Pi, where the numbers mean something.

docs/how-to/troubleshoot.md

@@ -273,6 +273,28 @@ curl -s http://127.0.0.1:8080/metrics | grep nxdns_upstream_
 
 **Fix.** Raise `upstream.total_timeout_ms` if the queue drains but drains too slowly for the budget. Otherwise the queue is telling you the upstream is slow: an upstream answering in a few milliseconds does not fill eight concurrent slots at household query rates, so sustained queueing points at the resolver you configured, and a faster one is the fix. Adding a second upstream helps only with saturation, not with latency: failover is strict priority, not load spreading. A query does take the next upstream when the first one's slots are all busy — priority orders the candidates that can be admitted right now — but once every eligible upstream is full it blocks on the highest-priority one, and it still sends one query to one upstream at a time. The per-upstream slot count is compiled, not configured, so there is no knob to widen one upstream either.
 
+## SERVFAIL rows that name no upstream
+
+**Symptom.** The query log shows SERVFAIL rows whose `upstream` is empty, and `/api/health` shows every upstream healthy.
+
+**Diagnosis.** A failed exchange names no upstream only when no attributable attempt happened, and two pool-wide counters say why:
+
+```sh
+curl -s http://127.0.0.1:8080/metrics | grep -E 'nxdns_upstream_(budget_exhausted|local_resource)_total'
+```
+
+`nxdns_upstream_budget_exhausted_total` is a query whose own budget ran out first; the previous section covers it. `nxdns_upstream_local_resource_total` is an exchange this process ended on its own resources: out of memory, out of file descriptors, or a system error the runtime has no name for. Neither is charged to an upstream, because no upstream caused it, and a local failure does not fail over, because the next upstream would hit the same wall. Both count exchanges, not rows without an upstream: when an earlier upstream had already failed in the same exchange, the row names that one.
+
+**Fix.** For `local_resource_total`, look at the process's limits: `grep -E 'Max open files' /proc/$(pidof nxdns)/limits` against `ls /proc/$(pidof nxdns)/fd | wc -l`, and `VmRSS` in `/proc/$(pidof nxdns)/status` against the memory the host has. A connect that fails for a reason the runtime cannot name — a blackhole route to the upstream is one — is not counted here: it is charged to that upstream as `ConnectFailed (cause Unexpected)`, and the query fails over.
+
+## A DoH upstream fails with `HttpStatus (status 505 HTTP Version Not Supported)`
+
+**Symptom.** Diagnostics shows the upstream failing with that cause, and no query ever succeeds against it.
+
+**Diagnosis.** The server refuses HTTP/1.1. nxdns speaks DoH over HTTP/1.1 only, and some public resolvers (Quad9's `https://dns.quad9.net/dns-query`, for one) require HTTP/2. Other statuses name themselves the same way: a 403 or 404 is usually a wrong URL path.
+
+**Fix.** Use that provider's DoT endpoint instead (for Quad9, `tls://9.9.9.9:853` with `tls_name = "dns.quad9.net"`), or a DoH upstream that accepts HTTP/1.1.
+
 ## The disk is filling up
 
 **Symptom.** Writes stop but DNS keeps answering. The journal shows the transition:

docs/how-to/upgrade.md

@@ -13,10 +13,7 @@ The normal path is to download the new release, verify it, and swap the binary.
 > where the substitution matters, or which was not run at all, carries its own
 > note. Nothing here was verified except where a note says so.
 >
-> Step 2 could not be run at all: no nxdns release is published yet, so every
-> release URL and the `docker compose pull` on this page fail today. The URL
-> shapes and the verification commands are covered by
-> [Verify a release](verify-a-release.md), which says what was probed and how.
+> The download in step 2 was run on 2026-10-02 against the published `v0.0.21` release; its note carries the detail.
 
 ## Breaking change: `run --config` now means file authority
 
@@ -137,10 +134,7 @@ Take `aarch64-linux-musl` for a Raspberry Pi 5. Verify every time, not only on t
 
 Under Docker there is nothing to download: step 3 pulls the image, and the `IMAGE-DIGEST.txt` asset is what you verify instead.
 
-> Not verified on this host: no release exists yet, so the `releases/latest`
-> lookup returns 404 and leaves `VERSION` empty, and every `curl` below it is a
-> 404 too. The lookup form was run against `gitea.com/gitea/tea` on Gitea
-> `1.27.0+dev` and printed `0.15.1`.
+> Verified on 2026-10-02 against `v0.0.21`: the lookup printed `0.0.21`, every `curl` succeeded, `gpg --verify` printed `Good signature`, `sha256sum -c` printed `OK`, and the tarball extracted. [Install with systemd](install-with-systemd.md) has the detail.
 
 ## 3. Replace the binary
 
@@ -174,20 +168,36 @@ journalctl -u nxdns -f
 
 ### Docker
 
+The compose file names the release it belongs to, so upgrading the image is upgrading the file. A new release's compose file can change more than the image — the `command:` line or a port — so both ways below replace yours: if you edited it by hand, carry your edits over to the new one. To keep your own file as it is, skip the `curl` or the `git checkout` and set `NXDNS_VERSION=$VERSION` on the `pull` and `up` lines instead: it overrides the release the file names. A compose file from `v0.0.22` or earlier defaults to `:latest`, so with one of those the variable is needed on both lines, or `pull` and `up` can land on different images if a release happens between them.
+
+With the single downloaded file of [Install with Docker](install-with-docker.md), fetch the new release's copy over it in its directory, then pull and recreate:
+
 ```sh
-NXDNS_VERSION=$VERSION docker compose -f deploy/docker/compose.yaml pull
-NXDNS_VERSION=$VERSION docker compose -f deploy/docker/compose.yaml up -d
+cd ~/nxdns
+curl -fLO "$BASE/raw/tag/v$VERSION/deploy/docker/compose.yaml"
+docker compose pull
+docker compose up -d
+```
+
+With a checkout of the repository, fetch the tag and move to it, from the repository root:
+
+```sh
+git fetch origin tag "v$VERSION"
+git checkout "v$VERSION"
+docker compose -f deploy/docker/compose.yaml pull
+docker compose -f deploy/docker/compose.yaml up -d
 ```
 
 Compose recreates the container against the same `nxdns-data` volume. What happens to the file in `etc-nxdns` depends on the `command:` in your compose file: with the shipped `run --config=/etc/nxdns/config.zon` the file is the configuration and the restart reconciles onto it; without it, the database in the volume is the configuration and the file is read by nothing.
 
-Set `NXDNS_VERSION` on both lines, or export it. Without it the compose file falls back to `:latest`, and `pull` and `up` could then land on different images if a release happens between them.
-
-> Not run on this host: `pull` needs a published image, and there is none.
-> What was run is `docker compose -f deploy/docker/compose.yaml config`, which
-> resolves the variables without contacting a registry: `NXDNS_VERSION=0.0.1`
-> gave `image: git.mial.net/mokhtar/nxdns:0.0.1`, and no variable at all gave
-> `:latest`.
+> Not run on this host: `pull` and `up` were not run against a new release.
+> What was run on 2026-10-20 is `docker compose -f deploy/docker/compose.yaml
+> config` on a tree whose `build.zig.zon` declares `0.0.22`, which resolves
+> the variables without contacting a registry: no variable gave
+> `image: git.mial.net/mokhtar/nxdns:0.0.22`, and `NXDNS_VERSION=0.0.21` gave
+> `image: git.mial.net/mokhtar/nxdns:0.0.21`.
+> The fetch half was run the same day against `v0.0.22`: the `curl` URL
+> returned 200, and `git fetch --dry-run origin tag v0.0.22` exited 0.
 
 ## 4. Confirm the upgrade
 
@@ -218,7 +228,7 @@ OK: no problems found
 >
 > ```
 > $ nxdns version
-> nxdns <version> (unknown)
+> nxdns <version>
 > zig 0.16.0
 > ```
 >
@@ -338,13 +348,13 @@ If you are running something you built rather than a release, step 2 is a build
 ```sh
 (cd admin && npm ci && npm run build)
 VERSION=$(sed -n 's/^[[:space:]]*\.version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' build.zig.zon)
-zig build dist -Dversion-string="$VERSION" -Dgit-commit="$(git rev-parse HEAD)" \
+zig build dist -Dversion-string="$VERSION" \
     -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe
 ```
 
 Rebuild `admin/dist` before the binary on every upgrade. The admin interface is embedded at build time, and an old bundle against a new API is a broken System page. `dist` refuses the `admin/dist-placeholder` default outright, so the only way to ship a stale bundle is to leave an old `admin/dist` in place.
 
-The staged payload for each target is under `zig-out/dist/stage/nxdns-<version>-<triple>/`, and step 3 continues from there with that path in place of the extracted one. The version string has to equal `.version` in `build.zig.zon` — `verify-dist` asserts it, so a made-up one builds and then fails verification. What tells your build apart from the published release of the same version is `-Dgit-commit`, which `nxdns version` prints beside the version.
+The staged payload for each target is under `zig-out/dist/stage/nxdns-<version>-<triple>/`, and step 3 continues from there with that path in place of the extracted one. The version string has to equal `.version` in `build.zig.zon` — `verify-dist` asserts it, so a made-up one builds and then fails verification. Your build reports the same two lines as the published release of that version, so compare the tarball hashes rather than the `nxdns version` output when you need to tell them apart.
 
 Under Docker, build the image and name it instead of pulling:
 

docs/how-to/verify-a-release.md

@@ -97,7 +97,7 @@ curl -fsSL https://keys.openpgp.org/vks/v1/by-fingerprint/A2061F6AB24DF2C0E92346
 ```
 
 > Verified: the key is published, and that exact `curl | gpg --import` reported
-> `key 1509B54946D08A95: public key "Mokhtar Mial (pc) <mokhtar@mial.net>"
+> `key 1509B54946D08A95: public key "Mokhtar Mial (pc) <…>"
 > imported` into a clean `GNUPGHOME`.
 
 Then verify:
@@ -109,7 +109,7 @@ gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt
 ```
 gpg: Signature made Sun 09 Aug 2026 01:26:42 AM CEST
 gpg:                using EDDSA key 019D00DF8417EBFDA5471E5EF7319CC024FB5A96
-gpg: Good signature from "Mokhtar Mial (pc) <mokhtar@mial.net>" [unknown]
+gpg: Good signature from "Mokhtar Mial (pc) <…>" [unknown]
 gpg: WARNING: This key is not certified with a trusted signature!
 gpg:          There is no indication that the signature belongs to the owner.
 Primary key fingerprint: A206 1F6A B24D F2C0 E923  46FD 1509 B549 46D0 8A95
@@ -134,7 +134,7 @@ A tampered `SHA256SUMS.txt` looks like this, and exits 1:
 ```
 gpg: Signature made Sun 09 Aug 2026 01:26:42 AM CEST
 gpg:                using EDDSA key 019D00DF8417EBFDA5471E5EF7319CC024FB5A96
-gpg: BAD signature from "Mokhtar Mial (pc) <mokhtar@mial.net>" [unknown]
+gpg: BAD signature from "Mokhtar Mial (pc) <…>" [unknown]
 ```
 
 > Verified against `v0.0.1`, from a clean `GNUPGHOME` holding only the imported
@@ -197,13 +197,11 @@ tar -xzf nxdns-$VERSION-x86_64-linux-musl.tar.gz
 ./nxdns-$VERSION-x86_64-linux-musl/nxdns version
 ```
 
-`version` prints the version and the git commit it was built from, then the Zig version. The version has to match the tag you downloaded, and the commit has to match the commit the tag points at.
+`version` prints the version, then the Zig version the binary was built with. The version has to match the tag you downloaded. The binary carries no commit sha, so the check that ties a release to its source is the rebuild below rather than a string in this output.
 
 > Verified against `v0.0.1`: both tarballs listed exactly the one directory and
 > six files with the stated modes, no symlinks and no absolute or `..` paths,
-> and the extracted binary printed `nxdns 0.0.1
-> (3c2d0d41f04570038e805b759da4541e198eae17)` — the commit `v0.0.1` points at —
-> then `zig 0.16.0`.
+> and the extracted binary printed `nxdns 0.0.1` then `zig 0.16.0`.
 
 ## 6. Verify the container image
 
@@ -262,22 +260,42 @@ It proves two things:
 
 It does not prove that the binary in the tarball was built from the source in this repository. The machine that ran the build also held the signing key, so a compromise of that machine produces an artifact that is signed, verifies cleanly, and contains whatever the attacker put in it. The signature is a statement about origin and integrity in transit. It is not a statement about provenance from source.
 
-Closing that gap needs a reproducibility gate — an independent build, run somewhere else, that lands on the same bytes — and this project does not have one. It is a recorded deferral, not an oversight: see `specs/milestone-14.md` ruling 12. Until it exists, nothing here claims the build is reproducible, because nobody has measured whether it is.
+Closing that gap needs a reproducible build — an independent build, run somewhere else, that lands on the same bytes. The release tarballs are reproducible: the binary carries no commit sha, the archive is written by the project's own tool with fixed modes, zero timestamps and sorted entries, and CI rebuilds the same bytes and compares them against the pinned hashes before it uploads anything. The rebuild below is how you check that for yourself.
 
 The signing key is a subkey rather than the primary key, which limits the damage of the case above: a leaked release subkey is revoked on its own and the identity, the commit signatures and everyone's existing trust in the key survive.
 
 ## Rebuild it yourself
 
-You can still build the same version from source and compare. That gets you a binary whose provenance you know, and the comparison is worth making — read the paragraph after the recipe before you draw a conclusion from it.
+Build the same version from source and compare the hashes. Match the toolchain first: `ZIG_VERSION`, `NODE_VERSION` and `NPM_VERSION` at the top of `.gitea/workflows/gates.yml` are the exact versions the release used, and a different patch release of any of them changes the bytes.
+
+Zig has to be the official ziglang.org tarball for that version, not your distribution's package of it. A distro package of `0.16.0` is built against the system LLVM and emits different machine code than the official build, and both print `0.16.0`, so the version string tells you nothing. This is not hypothetical: the first cut of `flake.nix` pinned hashes CI could not reproduce for exactly that reason, and the release cut now downloads the official tarball itself rather than trusting `PATH`. Fetch and verify it the same way, against the `ZIG_TARBALL_SHA256` pin that sits next to `ZIG_VERSION` in `gates.yml` (CI installs the same bytes through setup-zig, which checks them by minisign):
 
 ```sh
 git clone https://git.mial.net/mokhtar/nxdns
 cd nxdns
 git checkout "v$VERSION"
 git verify-tag "v$VERSION"
-(cd admin && npm ci && npm run build)
-zig build dist -Dversion-string="$VERSION" -Dgit-commit="$(git rev-parse HEAD)" \
-  -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe
+
+ZIG_VERSION=$(sed -n 's/^  ZIG_VERSION: "\(.*\)"$/\1/p' .gitea/workflows/gates.yml)
+ZIG_TARBALL_SHA256=$(sed -n 's/^  ZIG_TARBALL_SHA256: "\(.*\)"$/\1/p' .gitea/workflows/gates.yml)
+curl -fsSL -o ../zig.tar.xz "https://ziglang.org/download/$ZIG_VERSION/zig-x86_64-linux-$ZIG_VERSION.tar.xz"
+(cd .. && echo "$ZIG_TARBALL_SHA256  zig.tar.xz" | sha256sum -c - && tar -xJf zig.tar.xz)
+ZIG="$(cd .. && pwd)/zig-x86_64-linux-$ZIG_VERSION/zig"
+"$ZIG" version
+```
+
+The host matters too: the admin bundle is built with host-native Rolldown and Lightning CSS bindings, which the lockfile ships per platform and libc, so the recipe reproduces the release only on x86_64 Linux with glibc, the runner CI uses. The two `npm_config_*` paths must not exist on your machine; the recipe relies on npm finding no config file there. The environment matters as much as the toolchain. The release cut and CI both build the bundle under exactly nine variables and a `022` umask, so the recipe below does the same: a locale, a time zone, a build timestamp or a file mode picked up from your shell each move the bytes. The Zig build gets a private `--cache-dir` so a stale local cache cannot leak into them; the global Zig cache stays shared, because it is content-addressed and a fresh one refetches every dependency (see `specs/release-cut.md`).
+
+```sh
+env -i PATH="$PATH" HOME="$HOME" LC_ALL=C LANG=C TZ=UTC SOURCE_DATE_EPOCH=0 CI=true npm_config_userconfig=/nonexistent/npmrc-user npm_config_globalconfig=/nonexistent/npmrc-global \
+  sh -c 'cd admin && umask 022 && npm ci && npm run build'
+
+env -i PATH="$PATH" HOME="$HOME" LC_ALL=C LANG=C TZ=UTC SOURCE_DATE_EPOCH=0 CI=true npm_config_userconfig=/nonexistent/npmrc-user npm_config_globalconfig=/nonexistent/npmrc-global \
+  sh -c 'umask 022 && exec "'"$ZIG"'" build dist \
+    -Dversion-string="'"$VERSION"'" \
+    -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe \
+    --cache-dir "$(mktemp -d)"'
+
 sha256sum zig-out/dist/nxdns-"$VERSION"-*.tar.gz
 ```
 
@@ -285,20 +303,13 @@ sha256sum zig-out/dist/nxdns-"$VERSION"-*.tar.gz
 
 `zig build dist` writes `zig-out/dist/`: the two tarballs, a staging directory per target under `stage/`, the stripped binaries under `bin/<triple>/`, and a `SHA256SUMS` covering the two tarballs. The published `SHA256SUMS.txt` is that file with a third line for `IMAGE-DIGEST.txt` appended by the release job, so the two tarball lines should match and the local file has no third line to compare.
 
-Now the caveat, and it is the whole reason this section is last. **A hash that differs does not mean the release was tampered with.** Nothing in this project measures whether two builds of the same commit on two different machines produce the same bytes, and there are several ordinary reasons they would not: a different Zig patch release, a different Node version, a different path to the build directory, a different npm lockfile resolution. A hash that matches is real evidence. A hash that does not match tells you only that something about the two builds differed, and finding out what is on you.
+The tarball is written by `zig build dist` itself rather than by the host's `tar` and `gzip`, so its layout is fixed and a rebuild on a matching toolchain reproduces it byte for byte. Entries are sorted by their full path as bytes, with the payload directory first. The payload directory and `nxdns` carry mode `0755`; every other file carries `0644`. Every entry has a zero modification time, uid 0, gid 0, and no user or group name. The gzip wrapper carries no original filename and a zero header timestamp, which is what makes two archives of the same tree compare equal.
 
-If you want the comparison to mean as much as it can, match the toolchain the release used. The Zig version is the second line of `nxdns version`, and both it and the Node version are pinned to exact patch releases at the top of `.gitea/workflows/gates.yml`, which is the workflow the release runs.
+Compare your two tarball hashes against two things: the published `SHA256SUMS.txt`, and the `hashes` block of `flake.nix` at the tag, which carries the same digests in SRI form. All three agree on a matching toolchain, and the release pipeline fails before it uploads anything if they do not.
 
-> Verified against `v0.0.1`, and the result is the caveat above in action. The
-> whole recipe ran from a fresh clone: `git verify-tag v0.0.1` printed
-> `Good signature` under the same signing subkey as the release, and
-> `zig build dist` produced both tarballs. The hashes did **not** match the
-> published `SHA256SUMS.txt` — the binaries themselves already differ. The Zig
-> version matched the pin exactly; the Node version did not (24.14.1 against
-> the pinned 24.19.0) and the build path differed, two of the ordinary causes
-> listed above. That is a measurement of what an unpinned rebuild gives you,
-> not evidence of tampering: the signature, checksum and image checks earlier
-> on this page all passed against the same release.
+A hash that differs is a signal to check the toolchain and the environment first. A distribution's Zig package instead of the official tarball is the first thing to rule out; an unpinned Node or npm version is the next ordinary explanation, and a build run outside the normalized environment above is the next one. Rule both out before you conclude anything about the release itself.
+
+> Verified on 2026-10-19 against `v0.0.21`, on x86_64 Linux with glibc, Node 24.19.0 and npm 11.17.0: from a fresh clone, `git verify-tag v0.0.21` printed `Good signature`, the freshly downloaded Zig tarball passed its `sha256sum -c`, and both rebuilt tarball hashes matched the published `SHA256SUMS.txt` and the `flake.nix` pins at the tag (`26615c4b…b3b4ce` for x86_64, `29746c9a…7f19af` for aarch64). The two `sh -c` wrappers were replaced by the same nine-variable `env -i` and a `022` umask set in the calling shell. The host was the maintainer's own machine, in a fresh directory with a private `--cache-dir`, so this run shows the recipe works; it is not a third-party reproduction. An earlier run against `v0.0.1`, before the build was reproducible, did not match.
 
 ## If a check fails
 

docs/reference/cli.md

@@ -202,7 +202,12 @@ If a restart and an import race for the write lock, one of them simply wins: bot
 
 ## `version`
 
-Prints two lines: the nxdns version with the git commit, then the Zig version the binary was built with. Takes no flags and no arguments.
+Prints two lines: the nxdns version, then the Zig version the binary was built with. Takes no flags and no arguments.
+
+```
+nxdns <version>
+zig 0.16.0
+```
 
 ## `help`
 

docs/reference/configuration.md

@@ -207,6 +207,8 @@ A `tls://` upstream's host must be an IP literal. nxdns does not resolve an upst
 
 A DoH upstream is not affected: `https://` goes through the HTTP client, which resolves normally, so a hostname there is the usual form.
 
+The DoH client speaks HTTP/1.1 only (HTTP/2 is out of scope), so a DoH server that requires HTTP/2 fails every exchange. Quad9 is one: `https://dns.quad9.net/dns-query` answers HTTP/1.1 with `505` (checked 2026-10-19). Reach Quad9 over DoT instead, as in the example above.
+
 ### clients
 
 Known clients with a fixed group assignment.
@@ -425,7 +427,7 @@ The smallest file that passes validation: a `default` group and one enabled upst
 ```zon
 .{
     .groups = .{ .{ .name = "default" } },
-    .upstreams = .{ .{ .url = "https://dns.quad9.net/dns-query" } },
+    .upstreams = .{ .{ .url = "https://cloudflare-dns.com/dns-query" } },
 }
 ```
 
@@ -483,7 +485,7 @@ The smallest file that passes validation: a `default` group and one enabled upst
     // tls_name is needed when a tls:// upstream is written as an IP
     // literal, so certificate verification has a DNS name to match.
     .upstreams = .{
-        .{ .url = "https://dns.quad9.net/dns-query", .priority = 10 },
+        .{ .url = "https://cloudflare-dns.com/dns-query", .priority = 10 },
         .{ .url = "tls://9.9.9.9:853", .priority = 20, .tls_name = "dns.quad9.net" },
     },
 

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1788752844,
+        "narHash": "sha256-VaWGJ6+cIYN2erfSecbRV+4ljI185Ty2wUrXyvQbgOw=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "dc5d91f840324650bac8c379428c7037a416959a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,124 @@
+{
+  description = "nxdns: DNS sinkhole with per-client policy groups";
+
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+  outputs =
+    { self, nixpkgs, ... }:
+    let
+      # `zig build cut` rewrites the lines between the delimiters by text replacement.
+      # BEGIN GENERATED BY zig build cut
+      version = "0.0.24";
+      hashes = {
+        "aarch64-linux" = "sha256-nsjFtsFlUJHp3AJj7ccrXmgBq1QK2tRAvmdofeTqc2E=";
+        "x86_64-linux" = "sha256-VxDq+UiOWPO4Wyhwdgky1X0QVAqeDgAqD7KeqbTLOJ8=";
+      };
+      # END GENERATED BY zig build cut
+
+      triples = {
+        "aarch64-linux" = "aarch64-linux-musl";
+        "x86_64-linux" = "x86_64-linux-musl";
+      };
+
+      systems = builtins.attrNames hashes;
+
+      package =
+        system:
+        let
+          pkgs = nixpkgs.legacyPackages.${system};
+          lib = pkgs.lib;
+          triple = triples.${system};
+        in
+        pkgs.stdenv.mkDerivation {
+          pname = "nxdns";
+          inherit version;
+
+          src = pkgs.fetchurl {
+            url = "https://git.mial.net/mokhtar/nxdns/releases/download/v${version}/nxdns-${version}-${triple}.tar.gz";
+            hash = hashes.${system};
+          };
+
+          # Static musl binary: the install check asserts that no interpreter was patched in.
+          dontPatchELF = true;
+          dontStrip = true;
+
+          installPhase = ''
+            runHook preInstall
+
+            install -Dm755 nxdns $out/bin/nxdns
+            install -Dm644 nxdns.service $out/lib/systemd/system/nxdns.service
+            substituteInPlace $out/lib/systemd/system/nxdns.service \
+              --replace-fail "ExecStart=/usr/local/bin/nxdns run" "ExecStart=$out/bin/nxdns run"
+            install -Dm644 LICENSE $out/share/doc/nxdns/LICENSE
+            install -Dm644 THIRD-PARTY-NOTICES $out/share/doc/nxdns/THIRD-PARTY-NOTICES
+
+            runHook postInstall
+          '';
+
+          doInstallCheck = true;
+
+          # GNU readelf prints `INTERP`, not `PT_INTERP`; `${READELF:?}` keeps an unset variable from turning the grep into a pass.
+          installCheckPhase = ''
+            runHook preInstallCheck
+
+            # Captured first: piping readelf straight into grep hides its exit
+            # status, so a readelf that failed to read the file at all would
+            # print nothing, match nothing, and pass as "static".
+            if ! segments="$(''${READELF:?} -l "$out/bin/nxdns")"; then
+              echo "readelf -l failed on $out/bin/nxdns" >&2
+              exit 1
+            fi
+            if printf '%s' "$segments" | grep -q INTERP; then
+              echo "nxdns has an INTERP segment: it is dynamically linked, not static" >&2
+              exit 1
+            fi
+
+            if ! dynamic="$(''${READELF:?} -d "$out/bin/nxdns")"; then
+              echo "readelf -d failed on $out/bin/nxdns" >&2
+              exit 1
+            fi
+            if printf '%s' "$dynamic" | grep -q NEEDED; then
+              echo "nxdns has DT_NEEDED entries: it links against shared libraries" >&2
+              exit 1
+            fi
+
+            if ! reported="$($out/bin/nxdns version)"; then
+              echo "nxdns version exited non-zero: the binary does not run here" >&2
+              exit 1
+            fi
+
+            # Prefix match: releases before 0.0.17 print a commit sha after the version.
+            case "$reported" in
+              "nxdns ${version}"*) echo "nxdns version reports: $reported" ;;
+              *)
+                echo "nxdns version reports '$reported'; expected it to start with 'nxdns ${version}'" >&2
+                exit 1
+                ;;
+            esac
+
+            runHook postInstallCheck
+          '';
+
+          meta = {
+            description = "DNS sinkhole with per-client policy groups";
+            homepage = "https://git.mial.net/mokhtar/nxdns";
+            license = lib.licenses.eupl12;
+            mainProgram = "nxdns";
+            platforms = systems;
+            sourceProvenance = [ lib.sourceTypes.binaryNativeCode ];
+          };
+        };
+    in
+    {
+      packages = nixpkgs.lib.genAttrs systems (system: {
+        default = package system;
+      });
+
+      nixosModules.default = import ./nix/module.nix { inherit self; };
+
+      checks.x86_64-linux = import ./nix/tests.nix {
+        inherit self;
+        pkgs = nixpkgs.legacyPackages.x86_64-linux;
+      };
+    };
+}

nix/module.nix

@@ -0,0 +1,105 @@
+# `services.nxdns`: the packaged unit, run in file mode against a configuration
+# that the pinned binary accepted at build time.
+#
+# The unit is `deploy/systemd/nxdns.service` from the release tarball, installed
+# by the package and picked up through `systemd.packages`. This module only adds
+# a drop-in, so the hardening lives in that one file and a change to it reaches
+# NixOS with the release that ships it.
+{ self }:
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  cfg = config.services.nxdns;
+
+  # Nix treats the ZON as opaque data, so without this a configuration the
+  # pinned binary rejects evaluates, builds and deploys, and fails only when
+  # the service starts. `import` into a throwaway data directory is the offline
+  # validator: it shares the parser, the validator and the reconcile engine
+  # with `run`, and its delete gate is inert on an empty database. `check` is
+  # not usable here: it probes every upstream, and the build sandbox has no
+  # network.
+  validatedConfig =
+    pkgs.runCommand "nxdns-config.zon"
+      {
+        nativeBuildInputs = [ cfg.package ];
+        src = cfg.configFile;
+      }
+      ''
+        mkdir -p "$TMPDIR/validate"
+        nxdns import --data-dir "$TMPDIR/validate" "$src"
+        cp "$src" "$out"
+      '';
+in
+{
+  options.services.nxdns = {
+    enable = lib.mkEnableOption "nxdns, a DNS sinkhole for a household network";
+
+    package = lib.mkOption {
+      type = lib.types.package;
+      default = self.packages.${pkgs.stdenv.hostPlatform.system}.default;
+      defaultText = lib.literalExpression "nxdns.packages.\${pkgs.stdenv.hostPlatform.system}.default";
+      description = "The nxdns release to run. The default is the release of the flake revision this module comes from.";
+    };
+
+    configFile = lib.mkOption {
+      type = lib.types.path;
+      example = lib.literalExpression "./nxdns-config.zon";
+      description = ''
+        The nxdns configuration, in ZON. nxdns runs in file mode: every start
+        reconciles the database onto this file, and the web interface refuses
+        configuration edits. The build fails when `nxdns import` from
+        `package` rejects the file.
+      '';
+    };
+
+    openFirewall = lib.mkOption {
+      type = lib.types.bool;
+      default = false;
+      description = "Open port 53 over UDP and TCP. The web interface port and the DoH and DoT ports stay closed.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    environment.etc."nxdns/config.zon".source = validatedConfig;
+
+    users.users.nxdns = {
+      isSystemUser = true;
+      group = "nxdns";
+      description = "nxdns DNS sinkhole";
+    };
+    users.groups.nxdns = { };
+
+    systemd.packages = [ cfg.package ];
+
+    systemd.services.nxdns = {
+      wantedBy = [ "multi-user.target" ];
+
+      # The unit file does not change when only the configuration does, so
+      # without this a configuration-only switch restarts nothing and the old
+      # configuration keeps serving with no error anywhere.
+      restartTriggers = [ validatedConfig ];
+
+      serviceConfig = {
+        # The empty entry clears the packaged ExecStart: a drop-in cannot
+        # replace it otherwise.
+        ExecStart = [
+          ""
+          "${lib.getExe cfg.package} run --config=/etc/nxdns/config.zon"
+        ];
+        # `environment.etc` creates /etc/nxdns and owns what is in it. A
+        # ConfigurationDirectory would make systemd adjust the same directory
+        # at every start.
+        ConfigurationDirectory = "";
+      };
+    };
+
+    networking.firewall = lib.mkIf cfg.openFirewall {
+      allowedUDPPorts = [ 53 ];
+      allowedTCPPorts = [ 53 ];
+    };
+  };
+}

nix/tests.nix

@@ -0,0 +1,97 @@
+# The acceptance checks for `services.nxdns`. Neither runs in CI: the VM test
+# needs KVM, and both need a nixpkgs closure the shared runner should not
+# download on every push. AGENTS.md says when to run them.
+{ self, pkgs }:
+let
+  lib = pkgs.lib;
+
+  # A local record answers without any upstream, which the test VM cannot reach.
+  configWith =
+    address:
+    pkgs.writeText "nxdns-test.zon" ''
+      .{
+          .groups = .{ .{ .name = "default" } },
+          .upstreams = .{ .{ .url = "tls://192.0.2.1:853", .tls_name = "dns.example" } },
+          .local_records = .{ .{ .name = "nas.lan", .rtype = .a, .value = "${address}" } },
+      }
+    '';
+
+  rejected = pkgs.writeText "nxdns-rejected.zon" ''
+    .{
+        .groups = .{ .{ .name = "default" } },
+        .upstreams = .{ .{ .url = "tls://192.0.2.1:853", .tls_name = "dns.example" } },
+        .rules = .{ .{ .group = "default", .pattern = "(", .kind = .regex, .action = .block } },
+    }
+  '';
+
+  machineWith = configFile: {
+    imports = [ self.nixosModules.default ];
+    services.nxdns = {
+      enable = true;
+      inherit configFile;
+    };
+    boot.loader.grub.enable = false;
+    fileSystems."/" = {
+      device = "none";
+      fsType = "tmpfs";
+    };
+    system.stateVersion = lib.trivial.release;
+  };
+in
+{
+  nixos-module = pkgs.testers.runNixOSTest {
+    name = "nxdns-module";
+
+    nodes.machine =
+      { pkgs, ... }:
+      {
+        imports = [ self.nixosModules.default ];
+        services.nxdns = {
+          enable = true;
+          configFile = configWith "192.0.2.5";
+          openFirewall = true;
+        };
+        environment.systemPackages = [ pkgs.dnsutils ];
+        specialisation.changed.configuration.services.nxdns.configFile = lib.mkForce (
+          configWith "192.0.2.6"
+        );
+      };
+
+    testScript = ''
+      machine.wait_for_unit("nxdns.service")
+      machine.wait_until_succeeds("dig +short @127.0.0.1 nas.lan A | grep -x 192.0.2.5")
+
+      # The packaged unit runs, with the module's drop-in on top of it.
+      unit = machine.succeed("systemctl cat nxdns.service")
+      assert "/lib/systemd/system/nxdns.service" in unit, unit
+      assert "ProtectSystem=strict" in unit, unit
+      assert "run --config=/etc/nxdns/config.zon" in unit, unit
+      machine.succeed("systemctl show -p User --value nxdns.service | grep -x nxdns")
+      machine.succeed("test -z \"$(systemctl show -p ConfigurationDirectory --value nxdns.service)\"")
+      machine.succeed("systemctl show -p ReadOnlyPaths --value nxdns.service | tr ' ' '\\n' | grep -Fx /etc/nxdns")
+      machine.succeed("stat -c %U /etc/nxdns | grep -x root")
+      machine.succeed("iptables -S nixos-fw | grep -- '-p udp .*--dport 53 '")
+      machine.succeed("iptables -S nixos-fw | grep -- '-p tcp .*--dport 53 '")
+
+      # A switch that changes only the configuration restarts the service.
+      before = machine.succeed("systemctl show -p InvocationID --value nxdns.service").strip()
+      machine.succeed("/run/current-system/specialisation/changed/bin/switch-to-configuration test")
+      machine.wait_for_unit("nxdns.service")
+      after = machine.succeed("systemctl show -p InvocationID --value nxdns.service").strip()
+      assert before != after, "a configuration-only switch did not restart nxdns"
+      machine.wait_until_succeeds("dig +short @127.0.0.1 nas.lan A | grep -x 192.0.2.6")
+    '';
+  };
+
+  # A configuration the pinned binary rejects must fail the system build, and
+  # the build log must carry the binary's own reason.
+  nixos-module-rejects-config =
+    let
+      system = pkgs.nixos (machineWith rejected);
+      failure = pkgs.testers.testBuildFailure system.config.environment.etc."nxdns/config.zon".source;
+    in
+    pkgs.runCommand "nxdns-module-rejects-config" { } ''
+      grep -F 'FAIL rules[0].pattern' ${failure}/testBuildFailure.log
+      touch "$out"
+    '';
+}

specs/memory-budget.md

@@ -0,0 +1,97 @@
+# Memory budget: pay for what the household uses
+
+Measured on the deployed Pi (0.0.21, aarch64, 2.85M blocklist entries, 18 days up): VmRSS 238 MiB, VmHWM 358 MiB, 207 threads, almost all private anonymous memory. `docs/explanation/performance-and-testing.md` promises "memory with ~1M blocked domains < 100 MiB". Nothing leaks. Every MiB below has a measured owner, and each owner pays for a worst case the household never reaches, or pays twice.
+
+| Owner | Resident | How it was measured |
+|---|---|---|
+| Blocklist snapshot | 71 MiB, of which ~32 MiB is ABP domains stored twice | Pi smaps; `.list` and `.wild` bodies of the ABP sources are byte-identical (md5) |
+| Fixed buffers | ~52 MiB: query-log writer queue 17.5, two TCP listeners 2 × 8.7, two UDP listeners 2 × 4.8, SSE hub 3.6, cache slots 3.3 | Sizes from source; resident at once because safe builds fill new allocations with 0xaa |
+| Idle worker threads | ~41 MiB for ~200 parked workers | `std.Io.Threaded` never retires a worker; one burst of 64 in-flight UDP queries × 3 tasks each grows the pool for good (replica: 14 → 206 threads) |
+| Heap slabs kept after peaks | ~61 MiB free + ~8 MiB live | Decoded `SmpAllocator` free lists from two `/proc/<pid>/mem` dumps; owners from each slot's size header and a local tracing build |
+| Peak during refresh | +120 MiB over steady state | Old snapshot + new snapshot + every compiled body read at once; replica reproduced 350 MiB |
+
+Heap owners, from the dumps and the trace:
+
+- 8 KiB class, 25 MiB free: SQLite page-cache blocks (4,376 B requests in 8 KiB slots). Seven connections, no `cache_size` pragma, so each keeps the 2 MiB default, which costs ~3.7 MiB of slabs once filled.
+- 128 B + 256 B classes, ~21 MiB free: `std.Io.Threaded` `Group.Task` blocks — one per UDP query (`UdpServer.receiveLoop`), two per upstream exchange (`transport.raceUntilTagged`), two per query-log wait (`Logger.getWithin`).
+- 512 B class, 7.7 MiB free: `DnsCache.put` copies of cached responses (`src/cache/dns_cache.zig:356`).
+
+Why freed small blocks stay resident: with libc linked, `malloc` is zig's `lib/c/malloc.zig` on `std.heap.SmpAllocator`, which never unmaps a 64 KiB slab. `free` pushes onto the freeing thread's slot and `alloc` searches one other slot before it maps a new slab (`max_alloc_search = 1`), so producer/consumer pairs map more slabs than their live peak needs. Upstream: ziglang/zig#23592. Fewer tasks and smaller peaks shrink this retained memory; nothing in this spec frees it after the fact.
+
+## Decisions
+
+- Fix each owner at its root. Do not bypass the safe-build 0xaa fill: it only makes the oversizing visible.
+- Do not change the allocator in this work. Replacing `init.gpa` does not move SQLite, which calls C `malloc`. Revisit only if the measurement gate still names small-class slabs as a top owner.
+- No compiled-format change, no config-key migration, no new deadline mechanism. Each of those was considered and rejected in review: the format change makes the upgrade depend on the network, packed query-log rings cost more complexity than sizing the queue, and a socket-shutdown deadline cannot bound `connect` (`std.Io.Threaded` has no connect timeout) or the pool admission wait.
+- Not `SQLITE_CONFIG_PAGECACHE`, not a database page-size migration.
+
+## Contract
+
+### 0. Make the budget measurable first
+
+The admission budget, the listener caps, the stack size and the queue size are chosen from the Pi's real peaks, so those peaks become measurements before anything is resized:
+
+- high-water of in-flight DNS queries: `nxdns_dns_in_flight_peak`, counted around `Handler.handle`, every listener together;
+- high-water of active stream connections, per listener (today `connections` counts accepts over time, not concurrency): `nxdns_tcp_server_connections_peak` (the larger of the two address families), `nxdns_dot_server_connections_peak`, `nxdns_doh_server_connections_peak`;
+- high-water of the `std.Io.Threaded` worker pool: the process thread count. `Threaded` spawns a worker only when every worker is busy and never retires one (`Threaded.zig:2110`), so the count is that high-water already and needs no code. It counts workers, not tasks: `async` work can run inline or wait in the run queue;
+- high-water of the query-log writer queue's occupancy (not arrivals per interval: a full batch flushes early, and a disk gate or a slow write lets backlog build past one interval): `nxdns_querylog_queue_peak`. `std.Io.Queue` exposes no length, so a count beside it is raised before each insert and lowered after each removal; it can overstate the peak by the entries in transit, never understate it;
+- worker call-stack use, read from `/proc/<pid>/smaps`: each worker stack is an anonymous mapping directly above its own guard page, all of one size, and its `Rss` is what the thread has touched and still holds resident. That finds the expensive paths; it is not a depth bound. Before item 3 lowers `stack_size`, each expensive path gets a measured stack high-water, and the size keeps headroom above the deepest one. The signal stack (`std_options.signal_stack_size`) is a separate allocation for signal handling and stack traces and keeps its stdlib default unless its own use is measured.
+
+The five gauges are in `/metrics` beside the existing per-reason drop counters. One release carrying only these measurements runs on the Pi before the budget values are fixed.
+
+First reading, static x86_64 musl build, one burst of 300 UDP queries: the in-flight peak reached 64 (the UDP slot pool), threads went from 14 to 205, and of 201 worker stacks 175 touched 32 kB or less while 26 touched 2 MiB each — the same 2 MiB with only forward-zone traffic and no DoT exchange, so the TLS client is not the owner. Item 3 identifies that owner before it lowers `stack_size`: a stack smaller than that path needs is a crash, not a saving.
+
+### 1. Store each blocklist name once in memory
+
+Within one source, as compiled entries, an exact `x` in `.list` together with `x` in `.wild` means exactly what `||x^` compiles to. The compiled files, their checksum and their counts stay as they are.
+
+- The snapshot builder merges one source's sorted `.list` and `.wild` bodies into one name set with two flags per name: `exact` and `subdomains`. A name in both bodies is stored once. Sources are never merged with each other, so group eligibility and the reported source do not change.
+- `.allow` stays a separate set, and level 7 (exceptions) still runs before both flag checks.
+- Level 8 tests the full name for `exact`; level 9 tests proper parents for `subdomains`. Sources still walk in ascending index order. The reported result stays what it is today: when the `x` entry wins, the apex reports `blocklist_domain` with matched `x` and a proper subdomain reports `blocklist_wildcard` with matched parent `x`. An exception, an exact entry for the queried name or a nearer matching parent still wins first.
+
+### 2. Lower the refresh and boot peak
+
+- Boot keeps one synchronous initial load before the listeners start (`src/app.zig:692`). The startup pass uses that result for its refresh decisions and reloads only after a source actually refreshed, instead of rebuilding unconditionally (`src/filter/manager.zig:1823`).
+- `Snapshot` gets a pure `Builder`: add one source's bodies, then free them before reading the next. The old snapshot is still freed only after the swap, so a reload holds at most old snapshot + new snapshot + one source's bodies. That is the reload bound, not the process peak: refresh preparation (download, compile) can run beside a reload and holds its own allocations, and the Pi peak measurement includes it.
+
+### 3. Bound concurrent DNS work
+
+- `main` takes `std.process.Init.Minimal` and owns its `std.Io.Threaded`, with `stack_size` set from the item-0 stack measurement and a `concurrent_limit` derived from the chosen query and connection caps, the tasks each can nest, and the fixed services. The measured task high-water already counts every caller, so it is the cross-check, not a term in the sum.
+- `ConcurrencyUnavailable` is counted at every boundary where it can surface. The spec work enumerates each `io.concurrent` and `Group.concurrent` call; today the logger turns the error into an early flush without counting it (`src/storage/logger.zig:748`) and the listener races fold it into a generic failure (`src/server/listener.zig:102`). Each gets its own counter or a reason on an existing one.
+- Two kinds of bound: one cap on active DNS queries, shared by every listener (UDP and TCP, both families, DoT/DoH when enabled), and a slot cap per stream listener on accepted connections, each from the item-0 high-waters. A query takes a permit only while it does work; a keep-alive connection releases its permit between requests.
+- UDP keeps today's counted drop when no permit is free (`dropped_no_slot`). The kernel buffer does not absorb overload invisibly.
+- The upstream exchange keeps its whole-operation `Select` deadline and its distinction between peer result, budget expiry and cancellation. The thread high-water falls because the query budget is smaller, not because the race changes.
+- UDP slots and TCP connection buffers are sized from these bounds, not 64 per listener.
+
+### 4. Size the query-log buffers by use
+
+- The writer queue default (`logging.query_log_buffer_max`) comes from the item-0 occupancy high-water, with headroom stated in the reference. Drop-oldest backpressure and its counter stay.
+- The SSE hub allocates a subscriber's ring on subscribe and frees it on unsubscribe; `max_subscribers` stays a cap, not a reservation. `subscribe` becomes fallible: an allocation failure is distinct from "all slots occupied", is counted, answers with its own error rather than "live stream is full" (`src/web/handlers/live.zig:75`), and leaves the slot reusable. Overflow keeps today's contract: the hub ends that subscriber's stream so `EventSource` reconnects (`src/web/sse.zig:8`).
+
+### 5. SQLite caches chosen per connection
+
+- An explicit runtime-connection initialization step sets `cache_size` from a constant per role (query-log writer, retention, readers, config). `Db.open` stays free of pragmas, because migration callers control when pragmas apply (`src/storage/db.zig:302`). Every runtime handle reads its value back.
+
+### 6. DNS cache bounded in bytes
+
+- `DnsCache` keeps its entry count and adds a budget on live response bytes, tracked separately from `memoryBytes` (which also counts slots and index). `put` evicts by CLOCK until the copy fits. A response larger than the whole budget is not cached and is counted. A replacement keeps the old entry if allocating the new copy fails. A failed copy allocation is counted; today `handler.zig:918` discards it with `catch {}` and `DnsCache.Stats` has no field for it. The answer already obtained is still sent. The budget, the live bytes and both counters appear in cache diagnostics.
+- New config key `cache.max_bytes`, through the config field checklist. Default from the Pi's measured live response bytes.
+
+## Propagation
+
+- Config: `cache.max_bytes`; the changed default of `logging.query_log_buffer_max`. Config field checklist for the new key: model key + round-trip drift guards, validation + reference, settings API view, openapi.yaml, admin types + settings control, contract samples regenerated, docs config reference, CHANGELOG.
+- Diagnostics: the item-0 counters, `ConcurrencyUnavailable`, oversized cache responses, cache live bytes and budget.
+- Docs: `performance-and-testing.md` states the measured RSS, refresh peak and thread count at the Pi's blocklist size, replacing the unmeasured target.
+
+## Acceptance
+
+- [ ] Matcher equivalence: a deterministic corpus (hosts, domains, ABP with `||x^`, `*.x` alone, `x` alone, `x` with `*.x`, `@@`, an exact entry for a subdomain of a wildcard, nested wildcards `*.x` and `*.y.x`, overlapping sources) gives the same `Decision` for every probe name before and after item 1.
+- [ ] Builder: a reload holds at most one source's bodies (tested through an allocator that records peak bytes).
+- [ ] Boot: one snapshot build when no source refreshes; listeners never start without the initial load having run.
+- [ ] Measurements: each of the five item-0 gauges rises under a scripted load and is visible in `/metrics`; the thread count and the worker stack residency are recorded from `/proc` beside them.
+- [ ] Bounds: with the query budget full, a further UDP query is dropped and counted; a stream listener at its slot cap refuses and counts; a keep-alive connection between requests holds no query permit; `ConcurrencyUnavailable` is counted at each enumerated boundary, including the logger wait and the listener races.
+- [ ] SSE: no ring is allocated without a subscriber; an allocation failure is counted, reported as its own error and leaves the slot reusable; overflow still ends the stream.
+- [ ] SQLite: each runtime handle reports its configured `cache_size`; migrations open without it.
+- [ ] DNS cache: puts beyond the byte budget evict; live bytes never exceed it; an oversized response is skipped and counted; a failed replacement keeps the old entry; a failed copy allocation is counted and the answer is still sent.
+- [ ] Suites: `zig build test` and `-Dintegration` 0 failed; admin typecheck/vitest/prettier clean; contract samples regenerated.
+- [ ] Measurement record, on the Pi with the same blocklists: steady VmRSS after 24 h, VmHWM across one scheduled refresh (including its concurrent download and compile), thread count, and a decoded heap dump per size class, each beside the baseline in the table above. The owner chose a record, not a pass threshold: each owner must be reduced as specified, and the numbers go into `performance-and-testing.md`. If small-class slabs remain a top owner, the allocator question reopens with that data.

specs/milestone-3.md

@@ -810,3 +810,39 @@ The implementation matches the spec with these review-driven refinements (three
 - `dot_client.zig`: handshake `ReadFailed`/`WriteFailed` unwrap the stream's stored cause through `transport.mapLocal` first, and certificate-bundle `OutOfMemory` is a local resource, not a peer fault.
 - `transport.zig`: `Endpoint.parse` rejects userinfo/query/fragment delimiters (`@`, `?`, `#`) in the authority, and `?`/`#` in a DoH path.
 - `dot_client.zig` (follow-up, tls_name commit): `DotClient.init` takes a `tls_name`; it is the SNI and certificate-verification name, while the dial target stays `endpoint.host`. Empty keeps the endpoint host, which is the behavior described above. The same follow-up fixed a send bug this file had from the start, invisible until a DoT handshake first succeeded: `tls.Client.flush` only encrypts into the socket writer's buffer and never flushes it, so the query never left the process and the peer eventually closed the connection (`ReceiveFailed`/`EndOfStream`). `TlsStream.flush` now does both flushes and `exchange` calls it; a hermetic loopback test in `tls_client_integration_test.zig` covers it.
+
+## Addendum (2026-09-12): an upstream episode follows health, and a peer fault carries its cause
+
+Observed on the Pi over three days (nxdns 0.0.17 to 0.0.19): 20 `upstream.exchange` warning episodes, 17 with one occurrence, 15 resolved within ten seconds; since the 0.0.20 restart 1229 successes, 0 failures, 401 silent stale-session redials. `Pool.recordFailure` reports an episode on every failed exchange and `recordSuccess` resolves it on the next success, while `health.State` trips backoff only at `failure_threshold` consecutive failures. Two rules over one failure stream, and the Diagnostics page shows the looser one. Second gap: the episode detail is `upstream 'tls://1.1.1.1:853' failed: SendFailed`; the DoT client unwraps the concrete cause into `Transact.Failure.cause` and then returns a bare `PeerFault` error to the pool, so the cause is lost before anything records it. Codex reviewed the design (thread 01a09648) and its eight findings are folded in below.
+
+### 1. Health owns "failing"; the episode is a projection of its transitions
+
+- `health.State.recordFailure(at, fault, cfg, rand)` and `recordSuccess(at, cfg)` return an `Effect`: `{ revision: u64, state: union(enum) { clear, tripped: Fault } }`. `revision` is a per-state counter incremented by every mutation. The effect is the complete desired state of the episode after the mutation, never a transition: `tripped` when `consecutive_failures >= cfg.failure_threshold` (the predicate line 142 already uses, exposed as `tripped(cfg)`; not `available()`, which turns true when a backoff expires before recovery is proven), `clear` otherwise. The fault in `tripped` is the effective last fault the state holds after the mutation, not the incoming one: a stale failure (case 1 at `recordFailure`) never displaces a newer cause, so the episode detail cannot regress to an older one. A tagged union, not an action enum with a payload field, so a report without a fault is unrepresentable.
+- The pool projects every effect onto the store: `tripped` reports, `clear` resolves. A resolve when nothing is open issues no SQL (`storage/events.zig`), so the steady state costs nothing. Because every effect carries the whole desired state, last-writer-wins by revision is correct: the pool applies effects per entry in revision order under a separate `diagnostics_mutex` with a per-entry `applied_revision`, and drops an effect whose revision is below the applied one. Codex's reordering case (a failure trips health, a newer success clears it and its resolve reaches the store first, then the delayed failure arrives) is dropped instead of opening an episode nothing will resolve; and the converse cases, where a `none` transition would have overtaken a required report or resolve, cannot occur because there is no `none`. Health mutates under `Pool.mutex` as today and the effect is computed there; the store call runs after that mutex is released. Lock order is pool mutex, then nothing; diagnostics mutex, then store mutex. No task holds the pool mutex while it takes either of the other two.
+- Projection also reconciles a latched store failure for what an entry owns: a `clear` that failed to write is retried by the next `clear` the entry projects, and a `tripped` by the next failure. What no entry owns is handled by the reconciliation points below.
+- A success that leaves the state tripped (a stale success behind a newer failure, health case 1) projects nothing: `recordSuccess` returns `?Effect`, null in that case. The card is already open from the failure that tripped it, a report on a success would count a successful exchange as an occurrence, and a no-op that advanced the revision would reintroduce the dropped-report hole. Such a success does not touch `applied_revision`.
+- Reconciliation at the two points revision order cannot reach. (1) At boot, once the first generation is built: `store.resolveExcept(.upstream_exchange, kept = the enabled urls of the pool)` closes persisted episodes for upstreams that are gone, disabled or failed to build, and `Pool.reconcile(io)` projects every entry's current effect, which on a fresh pool resolves the rest. A re-asserted `tripped` must not count as an occurrence: the store gains `ensureOpen`, which opens the episode with the detail when none is active and otherwise leaves `occurrences` and `last_seen` untouched; `reconcile` uses it, a recorded failure keeps using `report`. (2) At every retirement of a displaced generation, both the pinned path (`Owner.release` at `refs == 0`, the point after which no exchange of it can still project) and the idle path (`Owner.replace` handing a zero-ref generation back to the caller), the same two calls run against the current generation. One owner function does the retire-and-reconcile and both paths call it, so a third retirement site cannot forget it. A removed or disabled upstream's episode is closed at the next reconciliation point; if the store had latched a failure at that moment, the next reconciliation point retries it. Before this addendum such an episode was never closed at all. `resolveExcept` is the right call for this code: the pool is the only reporter of `upstream_exchange`, unlike `configuration.load`, whose scoped rule in owner.zig stays. The previous "one exchange of lag" claim is withdrawn; the retirement point is exact.
+- Occurrences are the count of applied reports. Under concurrent reordering an older report behind a newer one is dropped, so the count can undercount; the health counters on `/metrics` are exact. Stated, not fixed: exact occurrence counts would need the store to accept out-of-order increments, and nobody reads the count as a metric.
+- The store folds a repeated report into the open episode (`occurrences`, `last_seen`, detail), so failures during backoff raise counts on one card. A warning card now means exactly what the pool means: it stopped trusting this endpoint.
+- Boundary, stated on purpose: an endpoint failing every other exchange never trips, because every newest success clears the count, so it opens no episode and `/api/health` stays `ok`. The rolling success rate on `/metrics` shows it. Diagnostics is for episodes, not chronic rates; a second predicate for that is not added.
+- No new configuration. The threshold that exists is the threshold, and it is at least 1: `health.Config` is validated where it is constructed (a comptime check on the default; if it is user-configurable, the config loader refuses 0), because a tripped state with no recorded failure has no fault to report.
+
+### 2. A peer fault is a value between the leaf client and the pool
+
+- `transport.zig` gains `Fault = struct { kind: PeerFault, cause: anyerror }`, `Outcome = union(enum) { reply: []u8, fault: Fault }`, and a leaf interface `Leaf` with `exchangeFn(ptr, io, query, response_buf) (LocalResource || Cancellation)!Outcome`. `kind` is the taxonomy as today; `cause` is the concrete unwrapped error (`BrokenPipe`, `ConnectionResetByPeer`, `TlsAlert`, `HttpConnectionClosing`, ...). No phase field: the taxonomy already names it for every kind that has one, and `TlsFailed` cannot say where it failed. No HTTP status number for `HttpStatus`; the claim is limited to concrete I/O causes. No optional metadata bag.
+- `dot_client.zig` and `doh_client.zig` implement `Leaf`; a `Transact.Failure` becomes a returned `Fault` instead of a thrown error. The DoT stale-session redial is unchanged and still counted through `reuse_recoveries`, never as a fault. The retry list is not widened; with the cause recorded, a stale-session cause outside the four lifecycle errors shows in the next episode and the list grows on evidence.
+- `Pool` consumes `Leaf` for its slots and keeps implementing `transport.Client` toward the handler, the forward client, and the fakes that sit on that side. The outer error set, `transport.group`, and the handler are untouched; the pool returns `last_fault.kind` as the error it returns today. The race harness stays generic: the pool races the leaf through a function whose error set adds `Timeout`; a leaf never returns `error.Timeout` itself (its own timeouts are faults), so `error.Timeout` out of the race is the harness. With `race == .expired and !truncated` the pool synthesizes `Fault{ .kind = error.Timeout, .cause = error.Timeout }` and records it: an untruncated attempt expiry is peer evidence. With `truncated` it stays `error.BudgetExhausted`, unattributed, exactly as today.
+- Health stores the effective fault (kind and cause names, `error_name_capacity` sized for both). Every surface that printed the taxonomy prints one text: `<Kind> (cause <Cause>)`, e.g. `SendFailed (cause BrokenPipe)`. Those surfaces are the episode detail, `upstream 'tls://1.1.1.1:853' failed: SendFailed (cause BrokenPipe)`, `Snapshot.last_error` and its one reader, the `nxdns check` FAIL line, and the pool's debug `AttemptFailure` line. `/api/health`, `/api/upstreams` and `/metrics` carry no fault text today and gain none here.
+- `transport.raceUntilTagged` becomes generic over the raced function's own error set: it returns `RacedError(f) || error{ Timeout, SystemResources, Canceled }`, so the pool's attempt wrapper returns `LeafError || error{Timeout}` with no `@errorCast` and no `unreachable`; `error.Timeout` out of the race is the harness by type, which sets `race = .expired` before returning it; the loop's catch asserts that and handles it in the expiry branch only, so a regression of the harness contract traps in ReleaseSafe instead of blaming an endpoint. The compiler enforces at the race boundary that a leaf cannot throw a `PeerFault` or `BudgetExhausted`. A leaf's own timeout is a returned `Fault{ .kind = error.Timeout, .cause = <leaf cause> }` with `race == .completed`, and a pool test proves it is recorded with the leaf's cause and never confused with the harness expiry.
+- The blocklist fetcher's `last_failure` side field stays as it is; same shape, other subsystem, its own addendum.
+
+### Tests
+
+- health: one failure returns `clear`; the second returns `tripped`; a success on a tripped state returns `clear`; a stale success behind a newer failure projects nothing; a stale failure returns the newer effective fault; revisions strictly increase.
+- pool: a `tripped` effect delivered after a newer `clear` effect is dropped and no episode is open afterwards; a `clear` delivered after a newer `tripped` is dropped and the episode stays open; an episode open in the store before the pool exists is resolved by boot reconciliation, one for a url the pool does not have and one for a url it has; a retired generation's late `tripped` is corrected by the reconciliation at its last release, and the idle-replace path reconciles too; a reconcile of a tripped entry with an open episode moves neither `occurrences` nor `last_seen`; a stale success while tripped projects nothing and the occurrence count does not move; one failed exchange opens no episode and the second opens one that the next success resolves; a truncated expiry records nothing and returns `BudgetExhausted`; an untruncated expiry records `Timeout (cause Timeout)`; a leaf fault of kind `Timeout` is recorded with the leaf's cause.
+- clients: the DoT integration tests assert the returned `Fault` with kind and cause, not the kind alone; a DoH integration test drives `DohClient.exchange` against a loopback port that is bound but never listens and stays bound for the test's duration, so the connect is refused deterministically with no port reuse race, and asserts the cause survives to the returned `Fault`; the stub-connection helper tests keep their causes.
+- surfaces: the `nxdns check` test asserts the `<Kind> (cause <Cause>)` text.
+
+### Out of scope
+
+An idle timer on the DoT session, a chronic-rate predicate, the fetcher migration, and any change to the DoT retry list.

specs/milestone-31.md

@@ -199,3 +199,11 @@ Deviations the build kept, judged defensible in review:
 - `Certificate.Bundle` has no in-memory PEM entry point in 0.16.0; the loopback test mirrors `addCertsFromFile`'s decode+parse calls to preload the fixture cert.
 - The S2.4 probe-close criterion is pinned as far as the repo can observe it: the failed-probe path runs the per-iteration deferred `close` (cli test, honestly named), and close-after-failure/double-close safety is pinned in the DoT integration tests. Close after a *successful* probe is unreachable in-repo (the probe verifies against the system trust store, and the only in-repo DoT peer is self-signed); no production surface was added to force it.
 - The metrics S3.3 "fixture pool" test drives a real `Pool` through the real `snapshot()` → `upstreams()` → render path with distinct per-field values.
+
+## Addendum (2026-09-08): overlap test synchronizes on entry
+
+The test `"overlapping exchanges each report the entry that answered that call"` failed once on a loaded CI runner and passed on rerun. It started two `io.concurrent` exchanges back to back and relied on the first entry's failing 50 ms stall to keep the first task in flight until the second task arrived. Nothing checked that the two calls were ever in flight together, and the schedule that produced two equal identities was not observed: every ordering traced by hand still ends the calls on different entries. The one thing known is that the test asserted an overlap it never proved.
+
+The test now builds the schedule instead of timing it, and contains no sleep at all. Two new `Fake.Behavior` variants, `hold` and `hold_fail`, wait on a `std.Io.Semaphore` the test owns and then reply or fail; the wait propagates cancellation exactly as the existing `slow` sleep does. The first entry holds its first call on one gate and its second call on the other, and the second entry replies immediately. The test starts the first task, waits with `awaitInFlight(io, &first_entry, 1)`, starts the second task, waits with `awaitInFlight(io, &first_entry, 2)`, and only then posts the first gate. Reaching a count of two means both calls are inside the first entry at that moment, so `peak_in_flight == 2` holds by construction, and the first task's failover to the second entry provably runs while the second call is still held inside the first entry. Posting the second gate afterwards releases it. Every earlier assertion is kept, including the per-entry call counts and health counts. Each gate's deferred post is registered right after its task's deferred await, so it runs before that await and every early return (a failed wait, a skipped second task, a failed assertion) releases the held call instead of deadlocking. The fake draws its behaviour before it raises `in_flight`, so a count of one also fixes which call holds which gate; without that order the second call could draw the failing behaviour and the first await would wait on a gate posted only after it.
+
+No pool bug was found, and the failing schedule was never observed. The original failure did not reproduce in 15 runs of the test binary pinned to two cores under six CPU hogs, with a diagnostic print on the assertion; that diagnostic was removed. `failover`'s attribution was not changed. After the change, 10 loaded two-core runs pass with the test reported `OK`, and each of those runs reports `1860 passed; 177 skipped; 0 failed.`. `zig build test` and `zig build test -Dintegration` both exit 0; the build runner prints no per-test summary of its own, only the known `failed command:` label described in AGENTS.md.

specs/milestone-40.md

@@ -0,0 +1,93 @@
+# Milestone 40: Nix flake with tag-pinned hashes, one commit per cut
+
+nxdns publishes a `flake.nix` whose package derivations fetch the release tarballs and carry their SRI hashes. A consumer pins `git+https://git.mial.net/mokhtar/nxdns.git?ref=refs/tags/vX.Y.Z` and Renovate bumps the tag. The hashes for a release are known before the release exists because the cut tool builds the same bytes locally that CI builds later, and CI verifies that equality before it uploads anything.
+
+Owner rulings (2026-09-08): the consumer pins a tag, not a branch. A cut stays at two commits and two CI runs (the bump commit runs ci.yml; the tag runs release.yml). No follow-up commit, no extra run, no post-release hash edit. Design agreed with Codex (thread 2026-09-08) and its findings are folded in below.
+
+## Why the hashes can be known in advance
+
+The tarball bytes depend on: the Zig compiler version, the source tree at the bump commit, the admin bundle, the archive format, and nothing else. Today two things break that: the binary embeds the git commit sha (which the bump commit cannot know about itself) and the archive is produced by the runner's `tar` and `gzip`. This milestone removes both. Reproducibility is then a property the repo enforces on every CI run, not a hope.
+
+## Session A: version identity without a commit sha
+
+The release binary reports its version only. The git commit is gone from every surface; it is not replaced by a tag name or by a sentinel.
+
+- `build.zig`: delete the `git-commit` option and the `git_commit` build option. Nothing else in `build.zig` changes in this session (Session B owns the rest of the file).
+- `src/version.zig` and `src/cli.zig` `runVersion`: print `nxdns {version}\nzig {zig_version}\n`.
+- `src/web/handlers/version.zig`: the `Body` loses `git_commit`. `admin/src/lib/types.ts`, `admin/src/lib/contractSamples.gen.ts` (regenerate with `zig build test -Dintegration -Dcontract-samples-out=<path>`, then copy), `admin/src/shell/AppShell.tsx` footer shows `nxdns v{version}`, and `AppShell.test.tsx` follow.
+- `tools/verify_dist.zig`: drop the `--git-commit` argument and the commit check; the `version` check stays.
+- `.gitea/workflows/gates.yml` package job and `.gitea/workflows/release.yml` publish job: drop `-Dgit-commit=...` from every `zig build dist` and `zig build verify-dist` line.
+- Docs: `docs/reference/cli.md`, `docs/how-to/verify-a-release.md`, `docs/how-to/upgrade.md`, `docs/how-to/install-with-docker.md` show the new `nxdns version` output. `verify-a-release.md` replaces the commit-matching step with the reproduction check from Session D (rebuild at the tag with the same toolchain, compare `SHA256SUMS` and `flake.nix`).
+- Tests: every test that asserted the commit in the CLI output, the API body, or the footer asserts the new shape.
+
+## Session B: Zig-owned archive and pin check
+
+`tools/dist_stage.zig` gains two modes and `build.zig` stops calling system `tar` and `gzip`.
+
+- `archive --root <stage dir> --payload <dir name> --out <file.tar.gz>`: walks the payload directory, sorts entries by full path (bytes), writes a GNU tar stream with `std.tar.Writer` (`writeDir` for the payload directory, `writeFile` for regular files, mode 0755 for the directory and the `nxdns` binary, 0644 for every other file, mtime 0, uid 0, gid 0, empty user and group names), finishes with `finishPedantically`, and compresses with `std.compress.flate.Compress` in the `.gzip` container at a fixed level. The output bytes must not depend on the absolute path of the stage directory, the umask, the clock, the locale, or the host's tar/gzip.
+- `pin-check --sums <SHA256SUMS> --flake <flake.nix> --version <x.y.z>`: parses the generated block in `flake.nix` (see Session C), converts each `sha256` SRI value to hex, and fails with a per-target message when the tarball entry in `SHA256SUMS` differs or the block's version differs. Only tarball entries are compared.
+- `pin --sums <SHA256SUMS> --flake <flake.nix> --version <x.y.z>`: rewrites the generated block from the sums file. Used by the cut tool (Session D).
+- `build.zig`: the cross-targets loop replaces `tar_run` and `gzip_run` with one `dist_stage archive` run. A separate `verify-pins` step runs `dist_stage pin-check` against `flake.nix` and `zig-out/dist/SHA256SUMS`. It is not part of `verify-dist`: an ordinary commit between two cuts builds the `build.zig.zon` version from a tree that differs from the released one, so its bytes never match the pins and must not be checked against them. Correction (2026-09-08): Session B first put the check inside `verify-dist`; Session D moves it out.
+- Reproducibility test (`zig build test`): stage the same fixture tree under two different absolute directories with different mtimes and file order on disk, archive both, assert byte equality, then read the archive back with `std.tar` and assert names, modes, and sizes.
+- `.gitea/workflows/gates.yml`: add `NPM_VERSION` to the top-level `env` next to `NODE_VERSION`; the frontend job asserts `node --version` and `npm --version` equal the pinned values before `npm ci`. The frontend job runs `npm run build` with `umask 022`, `LC_ALL=C`, `LANG=C`, `TZ=UTC`, `SOURCE_DATE_EPOCH=0`. `admin/vite.config.ts` reads no other environment (verified: only `VITEST`).
+- `docs/how-to/verify-a-release.md` describes the archive layout (fixed modes, zero timestamps, gzip without a name or mtime) so a reader can reproduce it.
+
+Deviation (Session B): the reproducibility test stages its two trees under two `std.testing.tmpDir` directories rather than two absolute paths. Zig 0.16.0's std exposes no way to read the current working directory, so an absolute path would need a raw `getcwd` syscall. The two roots still differ in path text, file creation order and mtimes, which is what the assertion is about.
+
+## Session C: flake.nix
+
+- `flake.nix` at the repo root with one input, `nixpkgs`, and `packages.{aarch64-linux,x86_64-linux}.default` built from the derivation that `rpi.mial.net` carries in `nixos/pkgs/nxdns.nix` today: `fetchurl` of `https://git.mial.net/mokhtar/nxdns/releases/download/v${version}/nxdns-${version}-${triple}.tar.gz`, `dontPatchELF`, `dontStrip`, install `nxdns`, `LICENSE`, `THIRD-PARTY-NOTICES`, and an `installCheckPhase` that asserts no `INTERP` and no `NEEDED` with `readelf` and that `nxdns version` output starts with `nxdns ${version}`. `meta.license = eupl12`, `meta.mainProgram = "nxdns"`.
+- The version and the two hashes live in one delimited block that Session B's `pin` mode rewrites and that nothing else edits by hand:
+
+```nix
+      # BEGIN GENERATED BY zig build cut
+      version = "0.0.16";
+      hashes = {
+        "aarch64-linux" = "sha256-...";
+        "x86_64-linux" = "sha256-...";
+      };
+      # END GENERATED BY zig build cut
+```
+
+The tool finds the two delimiter lines by their text after leading whitespace, keeps the begin line's indentation, and writes the six inner lines at that indentation (the hash lines two spaces deeper). A file with zero or two begin lines is an error.
+
+- `flake.lock` is committed. The consumer sets `inputs.nxdns.inputs.nixpkgs.follows = "nixpkgs"`.
+- `nix flake check --no-build` passes locally against the committed file. Evaluation does not fetch the tarball.
+- `docs/how-to/install-with-nix.md` documents the consumer side: the flake input with a tag ref, the `follows` line, and the Renovate `nix` manager. It states the window between the tag push and the asset upload during which a fresh pin fetches a 404, and that Renovate only proposes tags that already exist.
+- `flake.nix` is not a build input of the tarballs; the pins do not feed back into the bytes they describe.
+
+## Session D: the cut tool pins before it commits
+
+`tools/cut.zig` gains a `pin` stage between the changelog gates and the bump commit. The bump commit's exact diff becomes `build.zig.zon` plus `flake.nix`.
+
+1. Toolchain parity: read `NODE_VERSION`, `NPM_VERSION`, and `ZIG_VERSION` from `.gitea/workflows/gates.yml` and fail unless `node --version`, `npm --version`, and `zig version` match exactly, and unless the host is x86_64 Linux with glibc (host-native bundler bindings, shipped per platform and libc). The check runs before the manifest write so a refusal leaves a clean tree.
+2. Admin bundle: in `admin/`, run `npm ci` (npm replaces `node_modules` itself) then `npm run build` with the same normalized environment as the CI frontend job (`umask 022`, `LC_ALL=C`, `LANG=C`, `TZ=UTC`, `SOURCE_DATE_EPOCH=0`, `CI=true`, `npm_config_userconfig=/nonexistent/npmrc-user`, `npm_config_globalconfig=/nonexistent/npmrc-global`, `PATH` and `HOME` passed through, nothing else). Fail on a dirty `admin/dist` that the build did not produce.
+3. Dist: run `zig build dist -Dversion-string=<x.y.z> -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe` with the same normalized environment and a private `--cache-dir` under the scratch directory, so a stale local cache cannot leak into the bytes. The global cache stays shared: it is content-addressed, and a fresh one refetches every dependency and trips on zig 0.16.0's unzip, which expects `<global>/tmp` to exist.
+4. Pin: run `dist_stage pin` on `zig-out/dist/SHA256SUMS` and `flake.nix`, then `zig build verify-dist` and `zig build verify-pins` with the same flags, then `nix flake check --no-build`.
+5. Commit: the existing bump commit now includes `flake.nix`; the clean-tree gate accepts `admin/dist` and `zig-out` as ignored paths only.
+
+Where CI runs the pin check:
+
+- `.gitea/workflows/gates.yml` package job: after `verify-dist` and after the release payload is uploaded (so a mismatch still leaves the bytes downloadable), run `zig build verify-pins` when the pushed commit changed the declared `.version` against its first parent or changed `flake.nix` against it (the checkout needs depth 2). That covers the bump commit and a re-pin during a cut, the commits whose pins are otherwise unverified before the tag. Every other commit skips the step, and the skip is printed, not silent.
+- `.gitea/workflows/release.yml` publish job: after `verify-dist` and before the image push, the draft, and every upload, run `zig build verify-pins` unconditionally. The tag's tree is the bump commit's tree, and the flake block's version must equal the tag.
+
+The remaining stages (push, ci.yml wait, tag, release.yml wait) are unchanged. CI rebuilds the same bytes from the same inputs; `verify-pins` in the package job fails the run before the tag if the bytes differ, and the same step in the publish job fails before any image push, draft, or upload. `specs/release-cut.md` gains the pin stage and the parity requirement.
+
+Cut tool tests: the `.gitea` version parser, the environment builder (asserts the allowed keys and nothing else), and the pin stage on a fixture repo.
+
+Deviation (Session D): the pin stage is tested in pieces rather than on a fixture repository. There is no fixture-repo helper in `tools/cut.zig` to extend, and the stage's remaining content is four process spawns whose fixture would have to run `npm ci` and two cross-compiled release builds inside `zig build test`. What is tested instead is the parser (against a fixture and against the real `gates.yml`), the environment builder, and the `sh` wrapper — asserting it applies the umask, keeps the real command as the direct child, and reports its exit code. The spawns themselves follow the file's existing rule that process plumbing lives behind thin call sites and is not mocked. Two facts the spec left open: `umask(2)` is not in zig 0.16.0's `std.posix` (only `std.c.umask`, which these tools do not link), so the wrapper is the mechanism; and `build.zig` had no `pin-flake` step, so Session D added one beside `verify-pins`.
+
+## Out of scope
+
+Signing the flake outputs, a Hydra or cachix binary cache, Darwin packages, and a NixOS module. Renovate tag discovery on Gitea is a consumer-side acceptance test run once on `rpi.mial.net` after the first tagged release with a flake.
+
+Result of that test (2026-09-09, v0.0.18, Renovate 42.99.0): no pull request. Renovate's `nix` manager advances `flake.lock` along the ref an input already tracks and never moves a `refs/tags/vX.Y.Z` ref; it returned an empty release list for every flake input, GitHub-hosted ones included. The flake itself is correct and v0.0.17 deployed through it. Tag bumps need a regex custom manager with the `gitea-tags` datasource plus a lock refresh in the same pull request, which the consumer owns; `docs/how-to/install-with-nix.md` section 4 now says so instead of claiming the `nix` manager does it. With that manager in place, Renovate opened rpi.mial.net PR 5 the same day, bumping the input to v0.0.18 and refreshing `flake.lock`: the acceptance test passes.
+
+## Acceptance
+
+- `zig build test` green, including the two-path reproducibility test.
+- `nxdns version` prints two lines and no commit; `/api/version` has no `git_commit`; the admin footer shows `nxdns v<version>`.
+- `zig build dist` produces tarballs byte-identical across two clean checkouts on the same toolchain; `verify-pins` fails when `flake.nix` disagrees with `SHA256SUMS`; `verify-dist` passes on any tree.
+- `nix flake check --no-build` passes.
+- `zig build cut -- patch` on a fixture reaches the bump commit with `build.zig.zon` and `flake.nix` as its only diff.
+- CHANGELOG `## [Unreleased]` records the flake, the archive change, and the removal of the commit sha from the version surfaces.

specs/milestone-5.md

@@ -1377,3 +1377,26 @@ Deviations from the text above, recorded after the first six sessions verified.
 **S9 integration + fuzz.** Case 3 splits into the two real failure modes: a checksum-mismatched file marks the source `.load_failed` and the reload succeeds without it (generation advances); only a checksum-clean but malformed body fails `reload` and leaves the previous snapshot serving. Case 7 proves the cap from the response head: an explicit `content-length` of 100 MiB returns `error.BodyTooLarge` before any body streams. Case 8 back-dates `last_updated` through `updateSourceStats` and asserts inode and mtime of the compiled file are unchanged. Case 15 asserts `budget/2 <= elapsed < 2*budget` (the POSIX backend wakes ~0.8 ms early on a 200 ms deadline). The fuzz corpus is inline — `tests/fuzz/corpus.zig` imports the `dns` module, which the blocklist-fuzz module does not have. Fuzz targets assert properties, not only absence of crashes: `Line.text` windows the input (pointer containment), `covers_apex` only on `.wildcard`, `detectFormat`'s answer survives `parseLine` over the same bytes, and `matches` is exercised on rejected patterns.
 
 **Final wiring.** `build.zig` gained the `blocklist-fuzz` artifact (module import `parsers` → `src/filter/parsers.zig`, LLVM backend under `-Dfuzz`), hung off `test_step` beside the dns fuzz artifact. Evaluation: `zig build test`, `zig build test -Dintegration` and `zig build cross` all exit 0; both cross executables are statically linked.
+
+## Addendum (2026-09-12): a download failure names its cause
+
+Observed on the Pi (nxdns 0.0.17): four of eight sources fail on every refresh pass since 2026-09-11, the same four each time, and the log line for each is `download failed: TlsFailed` one pass and `download failed: ReceiveFailed` the next. The same binary loads all eight from another machine. The line cannot tell a TLS alert from a reset connection from a truncated chunk, because `fetcher.mapError` collapses the cause into the six-member taxonomy and `reportDownloadFailure` logs only the taxonomy name. The Diagnostics event carries the same text. A reader of either has nothing to act on. `upstream/doh_client.zig` already unwraps the concrete cause that `std.http.Client` stashes on the connection (`sendCause`, `headCause`, `bodyCause`, `readCause`); the fetcher does not.
+
+Change:
+
+- `fetcher.zig`: `Fetcher` gains `last_failure: ?Failure`, cleared at the top of `fetch` beside `last_status`, set on every error return. `Failure` is `{ phase: Phase, cause: anyerror, status: ?std.http.Status, bytes_read: u64 }`. `Phase` gains `receive_body`, distinct from the head. `cause` is the unwrapped concrete error: the three unwrap helpers move from `doh_client.zig` into `upstream/transport.zig` (or a sibling file both import; the coder picks the smaller diff), keep their tests, and both clients call them. The taxonomy `Error` and `mapError` are unchanged; a caller that ignores `last_failure` sees exactly what it saw before. `bytes_read` counts body bytes delivered to the writer before the failure, so a body that dies at byte 0 and one that dies at 5 MB read differently.
+- `manager.zig`: `fetchWithin` measures elapsed milliseconds on the awake clock. `reportDownloadFailure` takes the failure and elapsed time and logs one line: `blocklist <label>: download failed: <taxonomy> (<phase>, cause <CauseName>, http <status or none>, <bytes> bytes, <ms> ms)`. On the `Timeout` outcome of the expiry race the losing fetch is cancelled before the line is built, and it records itself on the way out, so the line names the phase it was in, `cause Canceled`, the status if a head arrived, and the bytes delivered so far: `Timeout (receive_body, cause Canceled, http 200, 5242880 bytes, 300000 ms)`. `download` clears `last_failure` and `last_status` before anything else runs, so a null record means no fetch reached the network for this source (a local file failure, or no concurrency to spawn the race); that prints as `<taxonomy> (no fetch, http none, - bytes, <ms> ms)`. Elapsed is captured when the race resolves, before the loser is cancelled, so a timeout's milliseconds are the time the transfer was given. `SourceStatus.fail` receives the same compact text, so the Diagnostics event detail shows it; `max_error_len` rises from 128 to 192 so the longest cause name and the numbers fit without truncation (check the longest `std.crypto.tls.Client.ReadError` and `std.http.Client` error names; `events.Store.max_detail_len` is 512 and is not touched).
+- Bound: this changes the content of an existing warning line, not its frequency. One line per failed source per pass, at most `sources × passes` per day; a pass runs once per `blocklist_update.interval_hours` or on a manual update. No per-chunk or per-retry logging is added. Nothing new is written at info or debug level.
+- Tests: `mapError` tests unchanged; a test that a head failure with a stashed `ConnectionResetByPeer` yields `last_failure.cause == error.ConnectionResetByPeer` and phase `receive` (the doh tests' stub connection pattern); a test that a body failure records `bytes_read` and `receive_body`; a `reportDownloadFailure` format test with the fixed text `blocklist source 3 'ads' 'https://lists.example': download failed: ReceiveFailed (receive_body, cause HttpChunkTruncated, http 200, 1048576 bytes, 812 ms)`; the existing secrecy assertions on the label stay.
+
+Out of scope: a TLS handshake failure stays `TlsInitializationFailed`, because `std.http.Client` collapses every handshake fault at `Client.zig:1470` before this code sees it; distinguishing an alert from a certificate failure would mean driving `std.crypto.tls.Client` by hand. Retries and a per-source backoff are not added.
+
+## Addendum (2026-09-12): a blocklist download never reuses a pooled connection
+
+The line above found the cause the same day nxdns 0.0.19 reached the Pi. A manual refresh at 14:28 failed the same four sources with one record each: `ReceiveFailed (receive, cause HttpConnectionClosing, http none, 0 bytes, 0 ms)`. Under one millisecond of elapsed time, and no response head byte after the request was sent, means the peer had already closed the socket. `std.http.Client` returns `HttpConnectionClosing` when a reused connection hits EOF before the first head byte (`std/http.zig:400`), and `std/http/test.zig:1331` pins that a client never retries a stale pooled connection. The startup pass at 13:03 had fetched `big.oisd.nl` successfully and the client parked that keep-alive connection in `fetch_http`'s pool; the server closed it long before 14:28, and the next request to the same host picked it up. The same shape explains every earlier observation: the first fetch to a host in a process succeeds, a later fetch to that host fails, and the daily pass reuses connections a day old. The `TlsFailed` variant of the older lines is the same dead socket failing inside the TLS layer instead of at the head.
+
+Change: `fetcher.fetch` requests with `.keep_alive = false`, and `fetch_http` in app.zig is created with `connection_pool.free_size = 0`, so `release` destroys every connection regardless of the request flag (`Client.zig:133`), including the one a failed send leaves in the `.ready` state that `Request.deinit` would otherwise pool, and no connection is ever taken from that pool. The flag alone is not enough: `Client.request` takes a pooled connection before it stores the flag (`Client.zig:1725`, `:1742`). The request then carries `connection: close`, the client marks the connection closing at the head, and `release` destroys it instead of pooling it (`Client.zig:133`, `:1167`). A blocklist download is one bulk transfer per source per day; there is nothing to gain from a pooled connection and a stale one costs a source for a day. `fetch_http` stays a separate client from `dns_http`, so the DoH pool is untouched.
+
+Tests: an integration test against `HttpFixture` where the server closes the socket after each response: two consecutive fetches to the same URL both succeed. Without the change the second fails with `HttpConnectionClosing`, which is the exact record the Pi produced. A unit test that the request header the fetcher sends carries `connection: close` if the fixture route is the cheaper path.
+
+Out of scope: a retry on `HttpConnectionClosing` for the DoH client, which keeps pooling by design and has its own health logic.

specs/nixos-module.md

@@ -0,0 +1,30 @@
+# NixOS module: `services.nxdns`
+
+Owner ruling (2026-10-20): ship `nixosModules.default` from the flake, with the options `enable`, `package`, `configFile` and `openFirewall`, file mode only, no `settings` attrset, and the shipped `nxdns.service` reused through `systemd.packages` plus a drop-in. The owner left Nix in CI, the VM test and a distinct exit code for `SchemaTooNew` to the implementer, within one constraint: the self-hosted Gitea runner (`../mial.net/manifests/gitea/`) is shared and must not be monopolized.
+
+## Why
+
+The flake already shipped a package and had one consumer, `rpi.mial.net`, which wrote its own module. Four parts of that module are not specific to the Pi, and two encode incidents: the build-time `nxdns import` validation, and `restartTriggers`, without which a configuration-only deploy restarted nothing (2026-08-16). A package with no service is half an install on NixOS.
+
+## What ships
+
+- `nix/module.nix`. `configFile` goes through `nxdns import --data-dir $TMPDIR/validate` from `package` in a `runCommand`, and the result is `/etc/nxdns/config.zon`. The `nxdns` system user and group. `systemd.packages = [ package ]`, and a drop-in that clears `ExecStart` and sets `run --config=/etc/nxdns/config.zon`, clears `ConfigurationDirectory` because `environment.etc` owns `/etc/nxdns`, adds `wantedBy` and `restartTriggers`. `openFirewall` opens 53/udp and 53/tcp and nothing else.
+- The package installs the tarball's `nxdns.service` to `lib/systemd/system/` with `ExecStart` pointed at its own binary. `--replace-fail` makes a changed `ExecStart` line in the unit a package build failure, not a silent mismatch.
+- Not shipped: database mode, a Nix-to-ZON renderer, and the Pi's choices about its own resolver, which stay in `rpi.mial.net`.
+
+## Decisions left to the implementer
+
+- **No Nix in CI.** No job installs Nix today. The checks need a nixpkgs closure and, for the VM test, KVM; downloading that on every push costs the shared runner disk and network, and the runner's cache already caused a disk-pressure eviction on 2026-08-23. The cut's existing `nix flake check --no-build` evaluates both checks at every release, which catches a module that no longer evaluates.
+- **The VM test runs on the developer's host.** `checks.x86_64-linux.nixos-module` and `checks.x86_64-linux.nixos-module-rejects-config` are built locally, with KVM, after any change to the module, the checks, the package or the unit. AGENTS.md says so. Whether the runner node exposes `/dev/kvm` was not checked, and nothing here depends on it.
+- **No new exit code.** `SchemaTooNew` is already in `config/faults.zig`, so `run` exits 2 for it and the unit's `RestartPreventExitStatus=2 64` stops instead of restart-looping (`src/app.zig` tests the mapping). A NixOS rollback onto a migrated database therefore stops the unit, and `docs/how-to/upgrade.md` describes the recovery. The exit-1 behaviour in the Pi module's notes dates from 0.0.2.
+
+## Acceptance
+
+- `nix flake check --no-build` passes.
+- `nixos-module`: a VM with the module and `openFirewall` answers `nas.lan` from a local record; `systemctl cat` shows the packaged unit and the drop-in; the service runs as `nxdns`; the effective `ConfigurationDirectory` is empty, `ReadOnlyPaths` still holds `/etc/nxdns`, and `/etc/nxdns` belongs to root; port 53 is open over UDP and TCP; `switch-to-configuration test` into a specialisation that changes only `configFile` gives a new `InvocationID` and the new answer. Without `restartTriggers` the test fails on the restart assertion, and without the `ConfigurationDirectory` clear it fails on that one (each checked once by removing the line).
+- `nixos-module-rejects-config`: a system build with an invalid regex rule fails, and its log carries `FAIL rules[0].pattern`.
+- `docs/how-to/install-with-nix.md` documents the module, the options, the store-readability of `configFile`, and rollback.
+
+## After the release
+
+`rpi.mial.net` replaces its module with `services.nxdns` and keeps its Pi-only parts, through the rpi-nixos-iac peer.

specs/release-cut.md

@@ -20,7 +20,7 @@ Recipes only — no variables, no embedded logic:
 
 Wired like the other host tools (`hostTool` + `addRunArtifact`, see build.zig ~230): `zig build cut -- {major|minor|patch}`. NOT installed to zig-out/bin. Its tests join `zig build test`.
 
-Constants: one repo API base `https://git.mial.net/api/v1/repos/mokhtar/nxdns` (the tool can only ever target this repo — no configurability). The runs API needs a token (verified: anonymous GET is 401); read it from `~/.config/tea/config.yml` (logins entry for git.mial.net); a missing token is a clear error naming the file.
+Constants: one repo API base `https://git.mial.net/api/v1/repos/mokhtar/nxdns` (the tool can only ever target this repo — no configurability); the endpoints under it are `/actions/runs`, `/commits/{sha}/status`, `/releases/tags/{tag}` and `/actions/runs/{id}/rerun`, the last being the only non-GET this program makes. The runs API needs a token (verified: anonymous GET is 401); read it from `~/.config/tea/config.yml` (logins entry for git.mial.net); a missing token is a clear error naming the file.
 
 ### Sequence
 
@@ -38,10 +38,12 @@ Constants: one repo API base `https://git.mial.net/api/v1/repos/mokhtar/nxdns` (
 A failed run must not strand the operator:
 - Bump pushed, then failure: rerun continues (preflight sees the version already bumped).
 - Local tag exists but never reached origin: verify it is an annotated tag by this tool's convention pointing at the current HEAD — adopt it; otherwise refuse with the exact `git tag -d` to run. Never delete a tag that exists on origin.
+- Release run failed, retryably: one automatic rerun (`POST {api_base}/actions/runs/{id}/rerun`, 201, then the wait targets that same run id — a rerun keeps it — and treats the run as restarted only once the forge reports a HIGHER `run_attempt`, so the concluded previous attempt is never read as the result and a rerun that finishes between two polls still is). Retryable only while the run is on its first attempt (`run_attempt` is 1; an absent attempt number is not read as 1), the conclusion is `failure` (never `cancelled`), at least one commit-status context is in a failure state, every context in a failure state is a gate (`Gates / …` or `Release / gates`, event suffix dropped), and the release object for the tag is absent or a draft; a published release is terminal, as `release.yml`'s guard already states. The bound is the forge's attempt count and not a counter in this process, so a run already rerun by hand or by an earlier invocation is never rerun again. The statuses are parsed STRICTLY for this decision — an entry missing a string `context`, `status` or `target_url` refuses the whole payload — because an unreadable entry is not counted as a failure and would leave a list of nothing but gates; the failing-job report keeps the tolerant parse. Anything the tool cannot read — the statuses, the release object, the attempt number — is terminal rather than retried.
+- Tag pushed, then failure: the tag on origin is no longer a reason to derive the next version. When origin's peeled tag object is the current HEAD and no release is published for it, the cut resumes at the release stage — no bump, no push, no CI wait, no tag, and no preflight, because everything the preflight guards has already happened — and reports it (`cut: resuming v0.0.16 at the release stage: the tag is on origin at HEAD and no release is published`). Peeling to HEAD is not on its own enough to resume on a tag: before the release wait, origin's tag object is verified the way the adopt path verifies a local one — annotated (a tag whose ref line and peeled line are one object is lightweight and refused), fetched when it is not here and compared against origin's object id when it is, carrying this tool's `v<version>` message, pointing at that commit, and signed under the fingerprint `release.yml` pins — so a lightweight or unsigned tag somebody pushed at HEAD is a refusal naming what is wrong, never a deletion or a move. A published release, or a tag pointing anywhere else, derives the next version as before. `planVersion` takes the manifest, the bump kind and that one three-state fact, and stays a pure table-tested function.
 
 ### Tests (in-file, join `zig build test`)
 
-Pure functions unit-tested: semver validation (accept/reject table incl. leading zeroes, `v` prefix), bump-kind parse, derivation table with the minor/major resets and overflow refusals, derive-vs-resume decision for all three kinds, zon `.version` parse + rewrite round-trip, changelog heading + non-empty body check, runs-JSON → decision (running / success / failure / no-run), tea-config token extraction. Process spawning and HTTP live behind thin call sites and are not mocked.
+Pure functions unit-tested: semver validation (accept/reject table incl. leading zeroes, `v` prefix), bump-kind parse, derivation table with the minor/major resets and overflow refusals, derive-vs-resume decision for all three kinds, zon `.version` parse + rewrite round-trip, changelog heading + non-empty body check, runs-JSON → decision (running / success / failure / no-run, the run-id narrowing a rerun needs, and whether an observed `run_attempt` has advanced past the one a rerun was asked for), failing-contexts JSON → retryable or terminal, release-object status and JSON → absent / draft / published, `ls-remote` peeling an annotated tag to its commit, tea-config token extraction. Process spawning and HTTP live behind thin call sites and are not mocked.
 
 ## Anti-requirements
 
@@ -71,3 +73,42 @@ Pure functions unit-tested: semver validation (accept/reject table incl. leading
 Every step that cannot answer — the `ls-remote`, the `git show`, the extraction, an unreadable CHANGELOG.md — is a soft FAIL naming the step. A gate that does not know whether the schema moved must never report that it did not.
 
 Fixing a FAIL is a sentence in the changelog, not a flag: there is no override, because the only thing the gate asks for is that the release notes be true.
+
+## Addendum: the pin stage (milestone 40)
+
+`flake.nix` carries the SHA256 of each release tarball, and a consumer pins the flake to a tag. The hashes therefore have to be written into the file that the tag points at, which means before the bump commit — the only commit the cut makes. The cut builds the release locally, pins what it built, and CI proves the pins describe the bytes it rebuilds.
+
+This amends step 3 of the sequence above. What was one write and one commit is now three moves, in this order and no other:
+
+1. **Toolchain parity.** Read `ZIG_VERSION`, `ZIG_TARBALL_SHA256`, `NODE_VERSION` and `NPM_VERSION` out of the top-level `env:` block of `.gitea/workflows/gates.yml` — a line parser, not a YAML library — and refuse unless `node --version` (less its leading `v`) and `npm --version` report those exact strings, and unless the host is x86_64 Linux with glibc (the admin bundle uses host-native Rolldown and Lightning CSS bindings, shipped per platform and libc, and CI is an x86_64 Ubuntu runner). Zig is not taken from `PATH` at all: the cut obtains the official ziglang.org tarball `https://ziglang.org/download/<ZIG_VERSION>/zig-x86_64-linux-<ZIG_VERSION>.tar.xz`, caches it under `$HOME/.cache/nxdns-cut/zig-<ZIG_VERSION>-<first 12 hex of ZIG_TARBALL_SHA256>/` (keyed by the digest too, so a changed pin never reuses an old extraction), and builds every release byte with that binary by absolute path. The first real cut pinned hashes CI could not reproduce because the Arch Linux 0.16.0 package is built against the system LLVM and emits different machine code than the tarball CI installs, and both print `0.16.0` — a version string cannot see the difference, so the bytes are pinned instead. When the cached binary is absent the tarball is downloaded with `curl -fsSL`, checked against `ZIG_TARBALL_SHA256` (setup-zig verifies the same bytes by minisign on the CI side), extracted with `tar -xJf`, and the extracted `zig version` is asserted; when it is present that last assertion still runs. There is no fall back to `PATH`. The `zig` on `PATH` still compiles the cut tool itself — that is `zig build cut`, whose bytes nobody hashes. The cut and CI must build with one toolchain, because the cut writes the hashes and CI recomputes them. A mismatch found here costs nothing; found in the release run it costs a public tag. The pins live in `gates.yml` and are read from there rather than copied, so the two can never drift; `release.yml` mirrors them and a test asserts the two files agree. Both halves run before the manifest is rewritten, so a refusal leaves the working tree clean.
+2. **Write `build.zig.zon`.** The manifest declares the new version, atomically, and is reparsed off disk. Nothing is committed yet.
+3. **Build the release.** In `admin/`, `npm ci` then `npm run build`; then `dist` through the official zig: `<cached zig> build dist -Dversion-string=<next> -Dadmin-dist=admin/dist -Doptimize=ReleaseSafe`, with `--cache-dir` under a scratch directory that is deleted and recreated first (the global cache stays shared: it is content-addressed, and a fresh one refetches every dependency and trips on zig 0.16.0's unzip, which expects `<global>/tmp` to exist). Every one of these runs under a constructed environment holding exactly nine variables — `PATH` and `HOME` from the parent, and `LC_ALL=C`, `LANG=C`, `TZ=UTC`, `SOURCE_DATE_EPOCH=0`, `CI=true`, `npm_config_userconfig=/nonexistent/npmrc-user`, `npm_config_globalconfig=/nonexistent/npmrc-global` (so neither `~/.npmrc` under the passed-through `HOME` nor the node install's `etc/npmrc` is read; the parity check refuses to run if either path exists, and CI asserts the same) — with `umask 022`. The umask arrives through an `sh -c 'umask 022 && exec "$@"'` wrapper because zig 0.16.0 exposes `umask(2)` only as a libc extern that these tools do not link, and `SpawnOptions` has no field for it. The wrapper's `exec` resolves the real command through the child's `PATH`, which is why `PATH` is a passthrough and not a pinned value.
+4. **Pin and verify.** Through the same official zig, `build pin-flake` rewrites the generated block of `flake.nix` from `zig-out/dist/SHA256SUMS`; then `build verify-dist` and `build verify-pins` with the same flags and cache directories, then `nix flake check --no-build` — evaluation only, because the tarballs the block now names do not exist until the release run uploads them.
+5. **Commit.** One `git commit -S`, taking `build.zig.zon` and `flake.nix`. The working-tree diff is asserted to be a subset of those two paths and to contain the manifest.
+
+The bump must precede the build because `verify-dist` refuses a build whose `-Dversion-string` disagrees with the manifest; the build must precede the commit because the pins belong to the commit. There is no ordering that satisfies both differently.
+
+On a resumed cut — the bump commit exists and its tag does not — the pin stage still runs in full, and the diff it leaves must be EMPTY. That emptiness is the check: the committed hashes reproduce on this machine today. A non-empty diff is a refusal, because the release CI is about to rebuild would not match the committed pins either.
+
+`admin/dist` and `zig-out` are ignored paths, so the preflight's clean-tree gate is unaffected by the trees this stage writes; the build caches live in the scratch directory and never touch the repository.
+
+### Where CI checks the pins
+
+`verify-pins` is a step of its own and deliberately not part of `verify-dist`. An ordinary commit between two cuts builds the same `build.zig.zon` version from a different tree, so its bytes legitimately differ from the pins, and checking them inside `verify-dist` would fail every such build.
+
+- `gates.yml`, package job: after `verify-dist`, run `verify-pins` only when `HEAD` changes `build.zig.zon` against its first parent. That commit is the bump commit, the one commit whose pins nothing has checked yet. The job's checkout takes `fetch-depth: 2` for the comparison. Every other commit prints why it skipped. A missing first parent is an error, not a skip: it means the checkout is shallower than declared and the question went unanswered.
+- `release.yml`, publish job: after `verify-dist` and before the image push, the draft and every upload, run `verify-pins` unconditionally. The tag's tree is the bump commit's tree, so the block must pin these bytes and name this version.
+
+### Tests
+
+The `gates.yml` env parser against a fixture and against the real file; the environment builder, asserting the nine keys and nothing else; and the `sh` wrapper, asserting it applies the umask, keeps the real command as the direct child, and reports its exit code. The stage's remaining steps are process spawns of `npm`, `zig` and `nix`, which are not mocked — the same rule the rest of this file follows.
+
+## Addendum: the compose file names its release (post-0.0.22)
+
+Owner question (2026-10-20), on the site's `NXDNS_VERSION=0.0.22 docker compose up -d`: "why do we need the NXDNS_VERSION to pull up a docker compose file? shouldnt the version be specified in the file already??" Until 0.0.22, `deploy/docker/compose.yaml` read `${NXDNS_VERSION:-latest}`, so the file fetched from a tag ran whatever `:latest` was that day, and every install and upgrade command had to carry the variable.
+
+The image default is now the release itself: `${NXDNS_IMAGE:-git.mial.net/mokhtar/nxdns:${NXDNS_VERSION:-<version>}}`. `NXDNS_VERSION` and `NXDNS_IMAGE` stay as overrides.
+
+- **The bump moves it.** This amends step 2 of the pin stage: the cut reads the compose file and computes its rewrite before anything is written, so a file without exactly one `${NXDNS_VERSION:-…}` default is a refusal on a clean tree. Then `build.zig.zon` and the compose file are both written atomically and read back. Step 5's commit takes `build.zig.zon`, `flake.nix` and `deploy/docker/compose.yaml`, and the working-tree diff is asserted to be a subset of those three paths.
+- **One guard, on every commit.** A cut-tool test reads the real `build.zig.zon` and `deploy/docker/compose.yaml` and asserts that the default equals the declared version. It runs in `zig build test`, so a hand edit of either file fails CI on that commit. The tag's tree is the bump commit's tree, which passed CI before the tag was made, so `verify-dist` gets no second copy of the check.
+- **The docs drop the variable from the plain flow.** README, install-with-docker and upgrade run `docker compose up -d`; the variables are documented as overrides, and the pages say that a compose file from `v0.0.22` or earlier still defaults to `:latest`.

src/app.zig

@@ -482,7 +482,19 @@ fn serve(r: cli.Runner, args: cli.RunArgs) !u8 {
     // Two HTTP clients on purpose. A blocklist download streams tens of
     // megabytes and holds its connection for the whole of it; DoH queries must
     // not queue behind that, and the two have nothing to share but a type.
-    var fetch_http: std.http.Client = .{ .allocator = gpa, .io = io };
+    // `free_size = 0` makes `release` destroy every connection and the pool
+    // hand none back (`Client.zig:133`). The fetcher's `.keep_alive = false` is
+    // what sends `connection: close`, but it cannot carry this alone: `request`
+    // takes a pooled connection before it stores the flag (`Client.zig:1725`,
+    // `:1742`), and a failed send leaves a `.ready` connection that
+    // `Request.deinit` would pool (`Client.zig:890`). A pass runs once a day,
+    // so any kept connection is closed at the peer by the next one, and the
+    // client never retries a stale one — it fails the source for the day.
+    var fetch_http: std.http.Client = .{
+        .allocator = gpa,
+        .io = io,
+        .connection_pool = .{ .free_size = 0 },
+    };
     defer fetch_http.deinit();
     var dns_http: std.http.Client = .{ .allocator = gpa, .io = io };
     defer dns_http.deinit();
@@ -545,6 +557,13 @@ fn serve(r: cli.Runner, args: cli.RunArgs) !u8 {
 
     var upstreams: upstream_owner.Owner = .init(upstream_generation);
     defer upstreams.deinit(io);
+    upstreams.diagnostics = event_store;
+    // The store outlived the process that wrote it, so every `upstream.exchange`
+    // episode in it describes a pool that no longer exists. This closes the ones
+    // no enabled upstream of this boot can justify, and projects the health of
+    // the ones that remain — a fresh pool is all clear, so a warning that
+    // survives this boot is one this process opened.
+    upstreams.reconcileDiagnostics(io, upstream_generation);
 
     // -----------------------------------------------------------------------
     // per-query state

src/cli.zig

@@ -453,9 +453,8 @@ pub fn runHelp(r: Runner) u8 {
 }
 
 pub fn runVersion(r: Runner) u8 {
-    r.out.print("nxdns {s} ({s})\nzig {s}\n", .{
+    r.out.print("nxdns {s}\nzig {s}\n", .{
         version.string,
-        version.git_commit,
         version.zig_version_string,
     }) catch return finish(r, exit_runtime);
     return finish(r, exit_ok);
@@ -979,14 +978,14 @@ fn probeUpstreams(r: Runner, cfg: model.Config) !usize {
         // what keeps the close off `dot` while it is still undefined.
         var dot_wired = false;
         defer if (dot_wired) dot.close(r.io);
-        const client: transport.Client = switch (endpoint.scheme) {
+        const client: transport.Leaf = switch (endpoint.scheme) {
             .doh => doh: {
                 doh = doh_client.DohClient.init(&http, endpoint, &request_buf, &transfer_buf) catch {
                     try r.out.print("FAIL upstreams[{d}] {f}: not a usable DoH url\n", .{ i, safe_url.redactQuoted(server.url) });
                     failures += 1;
                     continue;
                 };
-                break :doh doh.client();
+                break :doh doh.leaf();
             },
             .dot => dot: {
                 dot = dot_client.DotClient.init(endpoint, server.tls_name, r.gpa, &bundle, &bundle_lock, null, .{
@@ -996,7 +995,7 @@ fn probeUpstreams(r: Runner, cfg: model.Config) !usize {
                     .stream_write = tls_buffers[3 * chunk ..],
                 });
                 dot_wired = true;
-                break :dot dot.client();
+                break :dot dot.leaf();
             },
         };
 
@@ -1793,8 +1792,8 @@ test "a failed DoT probe reaches close through the per-iteration defer without a
 
     try testing.expectEqual(@as(usize, 2), try probeUpstreams(r, cfg));
     try testing.expectEqualStrings(
-        "FAIL upstreams[0] 'tls://dns.example:853': ConnectFailed\n" ++
-            "FAIL upstreams[1] 'tls://other.example:853': ConnectFailed\n",
+        "FAIL upstreams[0] 'tls://dns.example:853': ConnectFailed (cause ConnectFailed)\n" ++
+            "FAIL upstreams[1] 'tls://other.example:853': ConnectFailed (cause ConnectFailed)\n",
         captured.out.written(),
     );
 }

src/filter/fetcher.zig

@@ -1,16 +1,21 @@
 //! Blocklist download over HTTP/1.1.
 //!
-//! One `Fetcher` wraps a caller-owned `std.http.Client`, which owns the
-//! connection pool and the CA bundle, exactly as `upstream/doh_client.zig`
-//! does. This file knows nothing about parsing, files or the database: it GETs
-//! a URL and streams the bytes into a writer the caller supplies.
+//! One `Fetcher` wraps a caller-owned `std.http.Client`, which owns the CA
+//! bundle, as `upstream/doh_client.zig` does. Nothing here is pooled: every
+//! request asks for `connection: close`, and the caller is expected to give
+//! this file a client whose pool holds nothing (`free_size = 0`, set at the
+//! one construction site in `app.zig`). This file knows nothing about parsing,
+//! files or the database: it GETs a URL and streams the bytes into a writer
+//! the caller supplies.
 //!
 //! The body is never held whole. A blocklist can reach `max_body_bytes`, and
 //! the caller writes into a temporary file anyway, so nothing here allocates.
 //!
 //! There is no timeout parameter and no sleep. `std.http.Client` has no
 //! per-request deadline, so the caller runs `fetch` under `io.concurrent` and
-//! cancels the future; this file only propagates `error.Canceled`.
+//! cancels the future. A cancel during the body copy surfaces as
+//! `error.ReceiveFailed` with `Canceled` in `last_failure`; elsewhere it
+//! propagates as `error.Canceled`.
 
 const std = @import("std");
 const transport = @import("../upstream/transport.zig");
@@ -43,6 +48,30 @@ pub const Result = struct {
     status: std.http.Status,
 };
 
+/// The concrete fault behind an `Error`. `cause` is unwrapped from whatever
+/// `std.http.Client` stashed on the connection or the response, so it names a
+/// record-layer TLS fault or an HTTP framing fault rather than the collapsed
+/// `error.ReadFailed`.
+pub const Failure = struct {
+    phase: Phase,
+    cause: anyerror,
+    /// The response status if a head arrived before the failure.
+    status: ?std.http.Status,
+    /// Body bytes delivered to the caller's writer before the failure, and a
+    /// lower bound rather than an exact count: at least this many reached `w`.
+    /// A single `Reader.stream` call can hand bytes to `w` and then fail, and
+    /// that partial delivery is not counted. Zero on every phase before
+    /// `receive_body`.
+    bytes_read: u64,
+};
+
+/// Which call failed. The phase is what decides the classification, and only
+/// the call site knows it — guessing it from an error name would be wrong the
+/// first time two phases shared an error. `receive_body` is distinct from
+/// `receive`: the head arrived, so the fault is in the transfer, not the
+/// response.
+pub const Phase = enum { connect, send, receive, receive_body };
+
 pub const Fetcher = struct {
     /// Caller-owned; shared across sources, pools connections.
     http: *std.http.Client,
@@ -55,6 +84,12 @@ pub const Fetcher = struct {
     /// one. `error.HttpStatus` carries no `Result`, and the operator's message
     /// needs the number, so it is readable here after a failed `fetch`.
     last_status: ?std.http.Status = null,
+    /// What the most recent `fetch` failed on, or null if it succeeded or has
+    /// not run. The taxonomy `Error` a caller receives names six outcomes; this
+    /// names the one concrete fault behind the outcome, so an operator reading
+    /// the log can tell a TLS alert from a reset connection from a truncated
+    /// chunk.
+    last_failure: ?Failure = null,
 
     /// GETs `url` and streams the body into `w`.
     pub fn fetch(
@@ -71,37 +106,110 @@ pub const Fetcher = struct {
         std.debug.assert(self.transfer_buf.len >= min_transfer_buf);
         std.debug.assert(self.redirect_buf.len >= redirect_buffer_len);
 
-        const uri = try parseUrl(url);
-
         self.last_status = null;
+        self.last_failure = null;
+
+        const uri = parseUrl(url) catch |err| return self.record(err, .connect, err, null, 0);
 
         var req = self.http.request(.GET, uri, .{
-            .keep_alive = true,
+            // Sends `connection: close`, so the peer ends the connection and
+            // `release` destroys it rather than pooling it (`Client.zig:133`,
+            // `:1167`). A pass runs once a day: a kept connection is one the
+            // peer has already closed by the next pass, and `std.http.Client`
+            // never retries a reused connection that reaches EOF before the
+            // first head byte — it returns `error.HttpConnectionClosing` and
+            // the source fails for the day. This flag cannot carry that alone,
+            // because `request` takes a pooled connection before it reads the
+            // flag; `app.zig` empties the pool itself.
+            .keep_alive = false,
             .headers = .{
                 // Identity only: a compressed transfer encoding would need
                 // `Response.readerDecompressing`, a decompression buffer and a
                 // second failure surface, for a download that runs once a day.
                 .accept_encoding = .{ .override = "identity" },
             },
-        }) catch |err| return mapError(err, .connect);
+        }) catch |err| return self.record(mapError(err, .connect), .connect, err, null, 0);
         defer req.deinit();
 
-        req.sendBodiless() catch |err| return mapError(err, .send);
+        req.sendBodiless() catch |err|
+            return self.record(mapError(err, .send), .send, transport.sendCause(&req, err), null, 0);
 
-        var resp = req.receiveHead(self.redirect_buf) catch |err| return mapError(err, .receive);
+        var resp = req.receiveHead(self.redirect_buf) catch |err|
+            return self.record(mapError(err, .receive), .receive, transport.headCause(&req, err), null, 0);
 
         self.last_status = resp.head.status;
-        if (resp.head.status != .ok) return error.HttpStatus;
+        if (resp.head.status != .ok) {
+            return self.record(error.HttpStatus, .receive, error.HttpStatus, resp.head.status, 0);
+        }
 
         // `content-type` is deliberately not checked: blocklists are served as
         // text/plain, application/octet-stream and text/html alike, and the
         // compiler's invalid-line counters are the honest signal about content.
         if (resp.head.content_length) |declared| {
-            if (declared > max_body_bytes) return error.BodyTooLarge;
+            if (declared > max_body_bytes) {
+                return self.record(
+                    error.BodyTooLarge,
+                    .receive,
+                    error.BodyTooLarge,
+                    resp.head.status,
+                    0,
+                );
+            }
         }
 
         const body = resp.reader(self.transfer_buf);
-        return .{ .bytes_read = try pumpBody(body, w, max_body_bytes), .status = resp.head.status };
+        var pump: Pump = .{};
+        const bytes_read = pumpBody(body, w, max_body_bytes, &pump) catch |err| return self.record(
+            err,
+            .receive_body,
+            transport.bodyCause(&resp, pump.cause),
+            resp.head.status,
+            pump.delivered,
+        );
+        return .{ .bytes_read = bytes_read, .status = resp.head.status };
+    }
+
+    /// Stores the failure and hands back `mapped` unchanged.
+    ///
+    /// `mapped` is the taxonomy error the call site already decided, never one
+    /// this function derives. `mapError` answers for a raw std error, and the
+    /// call sites that raise a taxonomy member directly — a non-200 head, a
+    /// declared length over the cap — pass that member: feeding either back
+    /// through `mapError` would find no case for it and fall to the phase
+    /// default, turning `error.HttpStatus` into `error.ReceiveFailed`.
+    ///
+    /// `cause` never reaches the returned error. The unwrap is for the
+    /// operator's line, and a caller that ignores `last_failure` sees exactly
+    /// what it saw before the unwrap existed.
+    fn record(
+        self: *Fetcher,
+        mapped: Error,
+        phase: Phase,
+        cause: anyerror,
+        status: ?std.http.Status,
+        bytes_read: u64,
+    ) Error {
+        self.last_failure = .{
+            .phase = phase,
+            .cause = cause,
+            .status = status,
+            .bytes_read = bytes_read,
+        };
+        return mapped;
+    }
+};
+
+/// What `pumpBody` reports alongside its error: the reader error before
+/// `mapError` collapses it, and the bytes already handed to `w`. `pumpBody`
+/// knows nothing of `std.http`, so the unwrap of `cause` happens in `fetch`,
+/// which holds the response.
+const Pump = struct {
+    cause: anyerror = error.Unexpected,
+    delivered: u64 = 0,
+
+    fn fail(self: *Pump, cause: anyerror, mapped: Error) Error {
+        self.cause = cause;
+        return mapped;
     }
 };
 
@@ -116,17 +224,19 @@ pub const Fetcher = struct {
 /// `self.transfer_buf` — makes `@memcpy` copy the buffer onto itself
 /// (Reader.zig:677) and panics the process on the first read that finds bytes
 /// already buffered.
-fn pumpBody(body: *std.Io.Reader, w: *std.Io.Writer, cap: usize) Error!u64 {
+fn pumpBody(body: *std.Io.Reader, w: *std.Io.Writer, cap: usize, out: *Pump) Error!u64 {
     var total: usize = 0;
     while (total < cap) {
+        out.delivered = total;
         total += body.stream(w, .limited(cap - total)) catch |err| switch (err) {
             error.EndOfStream => return total,
             // The caller owns `w` and can read the concrete failure from its
             // own writer; this taxonomy has no member for a failing sink.
-            error.WriteFailed => return error.Unexpected,
-            else => |e| return mapError(e, .receive),
+            error.WriteFailed => return out.fail(err, error.Unexpected),
+            else => |e| return out.fail(e, mapError(e, .receive_body)),
         };
     }
+    out.delivered = total;
 
     // `cap` written exactly. One more byte separates a body that fits from one
     // that was cut off, and it must not reach `w`.
@@ -134,10 +244,10 @@ fn pumpBody(body: *std.Io.Reader, w: *std.Io.Writer, cap: usize) Error!u64 {
     var probe: std.Io.Writer.Discarding = .init(&probe_buf);
     const extra = body.stream(&probe.writer, .limited(1)) catch |err| switch (err) {
         error.EndOfStream => return total,
-        error.WriteFailed => return error.Unexpected,
-        else => |e| return mapError(e, .receive),
+        error.WriteFailed => return out.fail(err, error.Unexpected),
+        else => |e| return out.fail(e, mapError(e, .receive_body)),
     };
-    return if (extra == 0) total else error.BodyTooLarge;
+    return if (extra == 0) total else out.fail(error.BodyTooLarge, error.BodyTooLarge);
 }
 
 /// A scheme other than `http`/`https`, an unparseable URL and a URL with no
@@ -151,11 +261,6 @@ fn parseUrl(url: []const u8) Error!std.Uri {
     return uri;
 }
 
-/// Which call failed. The phase is what decides the classification, and only
-/// the call site knows it — guessing it from an error name would be wrong the
-/// first time two phases shared an error.
-const Phase = enum { connect, send, receive };
-
 // `error.X` in an expression names a member into existence rather than
 // referring to one, so the switch in `mapError` would keep compiling — and
 // silently stop matching — if std renamed either of these. This is what fails
@@ -179,9 +284,10 @@ fn errorSetHas(comptime Set: type, comptime name: []const u8) bool {
 /// `std.http.Client` collapses every handshake fault into
 /// `error.TlsInitializationFailed` (Client.zig:1470) and every bundle fault into
 /// `error.CertificateBundleLoadFailure`, and this file never unwraps a
-/// connection's stashed read cause — it maps the collapsed `error.ReadFailed` by
-/// phase — so the record-layer members of `std.crypto.tls.Client.ReadError`
-/// cannot arrive here. `doh_client.zig` does unwrap, and names them.
+/// connection's stashed read cause *for classification* — it maps the collapsed
+/// `error.ReadFailed` by phase — so the record-layer members of
+/// `std.crypto.tls.Client.ReadError` cannot arrive here. `fetch` does unwrap
+/// them, into `Failure.cause`, which no classification reads.
 fn mapError(err: anyerror, phase: Phase) Error {
     if (transport.mapLocal(err)) |local| return narrowLocal(local);
     switch (err) {
@@ -198,7 +304,7 @@ fn mapError(err: anyerror, phase: Phase) Error {
     return switch (phase) {
         .connect => error.ConnectFailed,
         .send => error.SendFailed,
-        .receive => error.ReceiveFailed,
+        .receive, .receive_body => error.ReceiveFailed,
     };
 }
 
@@ -230,7 +336,8 @@ test "pumpBody streams a fully buffered body without aliasing its source" {
     var out: [payload.len]u8 = undefined;
     var sink: std.Io.Writer = .fixed(&out);
 
-    const n = try pumpBody(&body, &sink, max_body_bytes);
+    var pump: Pump = .{};
+    const n = try pumpBody(&body, &sink, max_body_bytes, &pump);
     try testing.expectEqual(@as(u64, payload.len), n);
     try testing.expectEqualStrings(payload, out[0..payload.len]);
 }
@@ -241,7 +348,8 @@ test "pumpBody accepts a body of exactly the cap" {
     var out: [payload.len]u8 = undefined;
     var sink: std.Io.Writer = .fixed(&out);
 
-    const n = try pumpBody(&body, &sink, payload.len);
+    var pump: Pump = .{};
+    const n = try pumpBody(&body, &sink, payload.len, &pump);
     try testing.expectEqual(@as(u64, payload.len), n);
     try testing.expectEqualStrings(payload, out[0..payload.len]);
 }
@@ -252,10 +360,12 @@ test "pumpBody refuses a body one byte over the cap" {
     var out: [payload.len]u8 = undefined;
     var sink: std.Io.Writer = .fixed(&out);
 
+    var pump: Pump = .{};
     try testing.expectError(
         error.BodyTooLarge,
-        pumpBody(&body, &sink, payload.len - 1),
+        pumpBody(&body, &sink, payload.len - 1, &pump),
     );
+    try testing.expectEqual(error.BodyTooLarge, pump.cause);
 }
 
 test "pumpBody reports an empty body as zero bytes" {
@@ -263,7 +373,8 @@ test "pumpBody reports an empty body as zero bytes" {
     var sink_buf: [0]u8 = .{};
     var discarding: std.Io.Writer.Discarding = .init(&sink_buf);
 
-    try testing.expectEqual(@as(u64, 0), try pumpBody(&body, &discarding.writer, max_body_bytes));
+    var pump: Pump = .{};
+    try testing.expectEqual(@as(u64, 0), try pumpBody(&body, &discarding.writer, max_body_bytes, &pump));
 }
 
 fn undefinedFetcher(transfer_buf: []u8, redirect_buf: []u8) Fetcher {
@@ -359,3 +470,171 @@ test "caps are the values the memory budget was sized against" {
     try testing.expectEqual(@as(usize, 64 * 1024 * 1024), max_body_bytes);
     try testing.expectEqual(@as(usize, 8192), redirect_buffer_len);
 }
+
+/// Only the fields the unwrap helpers read are set; the rest of a `Connection`
+/// is two buffered streams, a host name and a pool node. `.plain` for the
+/// reason `doh_client.zig` gives: `getReadError` reaches a TLS connection's
+/// cause through `@fieldParentPtr`, which on a stub would read memory that was
+/// never a `Tls`.
+fn stubConnection(read_err: ?std.Io.net.Stream.Reader.Error) std.http.Client.Connection {
+    var connection: std.http.Client.Connection = undefined;
+    connection.protocol = .plain;
+    connection.stream_reader.err = read_err;
+    connection.stream_writer.err = null;
+    return connection;
+}
+
+test "a head failure records the stashed cause, not the collapsed read error" {
+    var connection = stubConnection(error.ConnectionResetByPeer);
+    var req: std.http.Client.Request = undefined;
+    req.connection = &connection;
+
+    var transfer_buf: [min_transfer_buf]u8 = undefined;
+    var redirect_buf: [redirect_buffer_len]u8 = undefined;
+    var f = undefinedFetcher(&transfer_buf, &redirect_buf);
+
+    const err = error.ReadFailed;
+    const mapped = f.record(mapError(err, .receive), .receive, transport.headCause(&req, err), null, 0);
+
+    // The taxonomy the caller sees is what it was before the unwrap existed.
+    try testing.expectEqual(error.ReceiveFailed, mapped);
+    const failure = f.last_failure.?;
+    try testing.expectEqual(Phase.receive, failure.phase);
+    try testing.expectEqual(error.ConnectionResetByPeer, failure.cause);
+    try testing.expectEqual(@as(?std.http.Status, null), failure.status);
+    try testing.expectEqual(@as(u64, 0), failure.bytes_read);
+}
+
+test "a body failure records the bytes delivered before it and the body phase" {
+    const payload = "0.0.0.0 ads.example.com\n";
+    var buffer: [payload.len]u8 = (payload ++ "").*;
+    // Buffered bytes reach `w` first; the vtable is only asked for more once
+    // the buffer is drained, which is the shape of a transfer cut off mid-body.
+    var body: std.Io.Reader = .{
+        .vtable = std.Io.Reader.failing.vtable,
+        .buffer = &buffer,
+        .seek = 0,
+        .end = buffer.len,
+    };
+    var sink_buf: [0]u8 = .{};
+    var discarding: std.Io.Writer.Discarding = .init(&sink_buf);
+
+    var pump: Pump = .{};
+    try testing.expectError(
+        error.ReceiveFailed,
+        pumpBody(&body, &discarding.writer, max_body_bytes, &pump),
+    );
+    try testing.expectEqual(@as(u64, payload.len), pump.delivered);
+
+    var connection = stubConnection(null);
+    var req: std.http.Client.Request = undefined;
+    req.connection = &connection;
+    req.reader.body_err = error.HttpChunkTruncated;
+    const resp: std.http.Client.Response = .{ .request = &req, .head = undefined };
+
+    var transfer_buf: [min_transfer_buf]u8 = undefined;
+    var redirect_buf: [redirect_buffer_len]u8 = undefined;
+    var f = undefinedFetcher(&transfer_buf, &redirect_buf);
+    const mapped = f.record(
+        mapError(error.ReadFailed, .receive_body),
+        .receive_body,
+        transport.bodyCause(&resp, pump.cause),
+        .ok,
+        pump.delivered,
+    );
+
+    try testing.expectEqual(error.ReceiveFailed, mapped);
+    const failure = f.last_failure.?;
+    try testing.expectEqual(Phase.receive_body, failure.phase);
+    try testing.expectEqual(error.HttpChunkTruncated, failure.cause);
+    try testing.expectEqual(@as(?std.http.Status, .ok), failure.status);
+    try testing.expectEqual(@as(u64, payload.len), failure.bytes_read);
+}
+
+test "a rejected url records the phase without claiming a connect failure" {
+    var transfer_buf: [min_transfer_buf]u8 = undefined;
+    var redirect_buf: [redirect_buffer_len]u8 = undefined;
+    var f = undefinedFetcher(&transfer_buf, &redirect_buf);
+    var sink_buf: [0]u8 = .{};
+    var discarding: std.Io.Writer.Discarding = .init(&sink_buf);
+
+    try testing.expectError(
+        error.BadUrl,
+        f.fetch(undefined, "ftp://example.com/list.txt", &discarding.writer),
+    );
+    try testing.expectEqual(error.BadUrl, f.last_failure.?.cause);
+}
+
+test "record returns the taxonomy member the call site raised, not a remapped one" {
+    // `error.HttpStatus` and `error.BodyTooLarge` are raised by `fetch` itself
+    // rather than by std, so `mapError` has no case for either and would fall
+    // to the phase default. `record` must not run them through it.
+    var transfer_buf: [min_transfer_buf]u8 = undefined;
+    var redirect_buf: [redirect_buffer_len]u8 = undefined;
+    var f = undefinedFetcher(&transfer_buf, &redirect_buf);
+
+    try testing.expectEqual(
+        error.HttpStatus,
+        f.record(error.HttpStatus, .receive, error.HttpStatus, .not_found, 0),
+    );
+    try testing.expectEqual(@as(?std.http.Status, .not_found), f.last_failure.?.status);
+    try testing.expectEqual(error.HttpStatus, f.last_failure.?.cause);
+
+    try testing.expectEqual(
+        error.BodyTooLarge,
+        f.record(error.BodyTooLarge, .receive, error.BodyTooLarge, .ok, 0),
+    );
+    try testing.expectEqual(error.BodyTooLarge, f.last_failure.?.cause);
+
+    // This is why: `mapError` is unchanged and does collapse both to the phase
+    // default. `fetch` must never route these two through it.
+    try testing.expectEqual(error.ReceiveFailed, mapError(error.HttpStatus, .receive));
+    try testing.expectEqual(error.ReceiveFailed, mapError(error.BodyTooLarge, .receive));
+}
+
+test "a cancelled body read records the cancellation and the progress so far" {
+    // This is the shape the expiry race leaves behind. `Select.cancelDiscard`
+    // cancels the fetch, the cancellation surfaces from the socket as a
+    // stashed `error.Canceled` under a collapsed `error.ReadFailed`, and the
+    // fetch records it on its way out. The manager then reports its own
+    // `error.Timeout` beside this record.
+    const payload = "0.0.0.0 ads.example.com\n";
+    var buffer: [payload.len]u8 = (payload ++ "").*;
+    var body: std.Io.Reader = .{
+        .vtable = std.Io.Reader.failing.vtable,
+        .buffer = &buffer,
+        .seek = 0,
+        .end = buffer.len,
+    };
+    var sink_buf: [0]u8 = .{};
+    var discarding: std.Io.Writer.Discarding = .init(&sink_buf);
+
+    var pump: Pump = .{};
+    try testing.expectError(
+        error.ReceiveFailed,
+        pumpBody(&body, &discarding.writer, max_body_bytes, &pump),
+    );
+
+    var connection = stubConnection(error.Canceled);
+    var req: std.http.Client.Request = undefined;
+    req.connection = &connection;
+    req.reader.body_err = null;
+    const resp: std.http.Client.Response = .{ .request = &req, .head = undefined };
+
+    var transfer_buf: [min_transfer_buf]u8 = undefined;
+    var redirect_buf: [redirect_buffer_len]u8 = undefined;
+    var f = undefinedFetcher(&transfer_buf, &redirect_buf);
+    // `pumpBody` maps the collapsed `error.ReadFailed` it was handed, not the
+    // unwrapped cause, so the taxonomy stays `ReceiveFailed` here. That is what
+    // this path returned before `Failure` existed, and the addendum keeps it:
+    // only the recorded cause is new. The manager reports `error.Timeout` from
+    // the expiry race anyway, so nothing reads this return value on this path.
+    const cause = transport.bodyCause(&resp, error.ReadFailed);
+    const mapped = f.record(error.ReceiveFailed, .receive_body, cause, .ok, pump.delivered);
+
+    try testing.expectEqual(error.ReceiveFailed, mapped);
+    try testing.expectEqual(Phase.receive_body, f.last_failure.?.phase);
+    try testing.expectEqual(error.Canceled, f.last_failure.?.cause);
+    try testing.expectEqual(@as(?std.http.Status, .ok), f.last_failure.?.status);
+    try testing.expectEqual(@as(u64, payload.len), f.last_failure.?.bytes_read);
+}

src/filter/filter_integration_test.zig

@@ -421,7 +421,7 @@ const Env = struct {
 // fixtures: the loopback http server
 // ---------------------------------------------------------------------------
 
-const Route = enum(u8) { body, redirect, not_found, oversize, chunked, stall, changed };
+const Route = enum(u8) { body, redirect, not_found, oversize, chunked, stall, changed, stale_keep_alive };
 
 /// How long the `stall` route holds a reply open when nothing releases it.
 ///
@@ -542,9 +542,10 @@ const HttpFixture = struct {
         }
     }
 
-    /// Every reply closes the connection. A keep-alive reply would leave the
-    /// fetcher holding the connection open while this server waits to accept a
-    /// second one that never comes (milestone-5 spec, S9 note from S8).
+    /// Every reply but `stale_keep_alive` closes the connection. A keep-alive
+    /// reply would leave the fetcher holding the connection open while this
+    /// server waits to accept a second one that never comes (milestone-5 spec,
+    /// S9 note from S8).
     fn respond(self: *HttpFixture, io: std.Io, request: *std.http.Server.Request) !void {
         switch (@as(Route, @enumFromInt(self.route.load(.acquire)))) {
             .body => try request.respond(self.body, .{ .keep_alive = false }),
@@ -566,6 +567,11 @@ const HttpFixture = struct {
                 .transfer_encoding = .none,
                 .extra_headers = &.{.{ .name = "content-length", .value = oversize_length }},
             }),
+            // Advertises keep-alive and then closes anyway, because `serve`
+            // takes one request per connection. That is the Pi's failure in
+            // miniature: a client that pools this connection reuses one the
+            // peer has already closed on its next request to the host.
+            .stale_keep_alive => try request.respond(self.body, .{ .keep_alive = true }),
             .chunked => try self.respondChunked(request),
             .stall => try self.respondStalled(io, request),
         }
@@ -1003,6 +1009,19 @@ test "5: a redirect is followed to the same result" {
     try testing.expect(decision.blocked);
 }
 
+/// The download failure line ends in numbers no test can predict — an elapsed
+/// time always, and a byte count where the failure is a cancelled transfer. The
+/// fixed part is compared whole; the tail only has to be digits, spaces and the
+/// two words those numbers carry.
+fn expectFailureText(expected_prefix: []const u8, actual: []const u8) !void {
+    try testing.expectEqualStrings(expected_prefix, actual[0..@min(expected_prefix.len, actual.len)]);
+    const tail = actual[expected_prefix.len..];
+    try testing.expect(std.mem.endsWith(u8, tail, " ms)"));
+    for (tail[0 .. tail.len - " ms)".len]) |c| {
+        try testing.expect(std.ascii.isDigit(c) or c == ' ' or c == ',' or std.ascii.isAlphabetic(c));
+    }
+}
+
 test "6: a 404 leaves the compiled files and the snapshot untouched" {
     if (!build_options.integration) return error.SkipZigTest;
 
@@ -1034,7 +1053,13 @@ test "6: a 404 leaves the compiled files and the snapshot untouched" {
 
     const failed = try env.status(id);
     try testing.expectEqual(manager.State.fetch_failed, failed.state);
-    try testing.expectEqualStrings("HttpStatus", failed.errorText());
+    // The whole line, not just the taxonomy: a 404 must stay `HttpStatus` and
+    // name the status it saw. Routing it back through `fetcher.mapError` would
+    // read `ReceiveFailed (receive, cause ReceiveFailed, ...)` here.
+    try expectFailureText(
+        "HttpStatus (receive, cause HttpStatus, http 404, 0 bytes, ",
+        failed.errorText(),
+    );
 
     var after = try Bodies.read(gpa, io, dir, "1");
     defer after.deinit(gpa);
@@ -1046,6 +1071,51 @@ test "6: a 404 leaves the compiled files and the snapshot untouched" {
     try testing.expect(decision.blocked);
 }
 
+test "6b: a local failure reports itself, not the previous source's network fault" {
+    if (!build_options.integration) return error.SkipZigTest;
+    // Mode bits do not apply to root, so the denial the test needs cannot happen.
+    if (std.c.geteuid() == 0) return error.SkipZigTest;
+
+    const gpa = testing.allocator;
+    const env = try Env.create(gpa);
+    defer env.destroy();
+    const io = env.io();
+
+    var fixture = try HttpFixture.init(io, http_body);
+    defer fixture.deinit(io);
+    fixture.setRoute(.not_found);
+    var group: std.Io.Group = .init;
+    defer group.cancel(io);
+    try group.concurrent(io, HttpFixture.serve, .{ &fixture, io });
+
+    var url_buf: [64]u8 = undefined;
+    const url = try fixture.url(&url_buf);
+    const id = try seedSource(&env.database, url);
+
+    // First a real network failure, so the fetcher is holding a record.
+    try testing.expect(!try refreshOnce(env, url));
+    try expectFailureText(
+        "HttpStatus (receive, cause HttpStatus, http 404, 0 bytes, ",
+        (try env.status(id)).errorText(),
+    );
+
+    // Then a failure that never reaches the network: the raw file cannot be
+    // created. Without the clear at the top of `download` this would report the
+    // 404 above as this refresh's cause.
+    var dir = try env.blocklistDir();
+    defer dir.close(io);
+    try dir.setPermissions(io, .fromMode(0o500));
+    defer dir.setPermissions(io, .fromMode(0o700)) catch {};
+
+    try testing.expect(!try refreshOnce(env, url));
+
+    const failed = try env.status(id);
+    try testing.expectEqual(manager.State.fetch_failed, failed.state);
+    try expectFailureText("AccessDenied (no fetch, http none, - bytes, ", failed.errorText());
+    try testing.expect(!std.mem.containsAtLeast(u8, failed.errorText(), 1, "HttpStatus"));
+    try testing.expect(!std.mem.containsAtLeast(u8, failed.errorText(), 1, "404"));
+}
+
 test "7: a body over the cap fails the refresh and leaves no temporary file" {
     if (!build_options.integration) return error.SkipZigTest;
 
@@ -1069,7 +1139,10 @@ test "7: a body over the cap fails the refresh and leaves no temporary file" {
 
     const failed = try env.status(id);
     try testing.expectEqual(manager.State.fetch_failed, failed.state);
-    try testing.expectEqualStrings("BodyTooLarge", failed.errorText());
+    try expectFailureText(
+        "BodyTooLarge (receive, cause BodyTooLarge, http 200, 0 bytes, ",
+        failed.errorText(),
+    );
 
     var dir = try env.blocklistDir();
     defer dir.close(io);
@@ -1187,6 +1260,44 @@ fn publishFixtureFiles(env: *Env, id: i64, list_body: []const u8, wild_body: []c
     });
 }
 
+test "8b: a second download to the same host never reuses a dead pooled connection" {
+    if (!build_options.integration) return error.SkipZigTest;
+
+    const gpa = testing.allocator;
+    const env = try Env.create(gpa);
+    defer env.destroy();
+    const io = env.io();
+
+    var fixture = try HttpFixture.init(io, http_body);
+    defer fixture.deinit(io);
+    // The server says keep-alive and then drops the socket, which is what the
+    // Pi's upstreams do between one daily pass and the next.
+    fixture.setRoute(.stale_keep_alive);
+    var group: std.Io.Group = .init;
+    defer group.cancel(io);
+    try group.concurrent(io, HttpFixture.serve, .{ &fixture, io });
+
+    var url_buf: [64]u8 = undefined;
+    const url = try fixture.url(&url_buf);
+
+    var sink_buf: [0]u8 = .{};
+    var first: std.Io.Writer.Discarding = .init(&sink_buf);
+    const one = try env.f.fetch(io, url, &first.writer);
+    try testing.expectEqual(@as(u64, http_body.len), one.bytes_read);
+
+    // The whole test is this second call. With a pooling client the request
+    // goes out over a connection the peer has already closed, no response head
+    // byte arrives, and `error.HttpConnectionClosing` comes back with no retry
+    // — the exact record the Pi produced at 0 bytes and under a millisecond.
+    var second: std.Io.Writer.Discarding = .init(&sink_buf);
+    const two = try env.f.fetch(io, url, &second.writer);
+    try testing.expectEqual(@as(u64, http_body.len), two.bytes_read);
+    try testing.expectEqual(@as(?fetcher.Failure, null), env.f.last_failure);
+
+    // Two connections, not one reused: the proof the first was not pooled.
+    try testing.expectEqual(@as(u32, 2), fixture.accepted.load(.monotonic));
+}
+
 test "9: a reload swaps under a held handle and the new generation follows the release" {
     if (!build_options.integration) return error.SkipZigTest;
 

src/filter/manager.zig

@@ -69,8 +69,13 @@ const log = std.log.scoped(.blocklist_manager);
 const Sha256 = std.crypto.hash.sha2.Sha256;
 
 /// `SourceStatus.last_error` is fixed-size so the failure path allocates
-/// nothing.
-pub const max_error_len: usize = 128;
+/// nothing. Sized so the longest `downloadFailureText` fits whole: the widest
+/// cause name the unwraps can produce is `DetectingNetworkConfigurationFailed`
+/// at 35 bytes, which with a 64 MiB byte count and an hour of milliseconds
+/// makes a 111-byte line. The test below recomputes that worst case from the
+/// std error sets, so a wider name std adds fails the build's test run rather
+/// than silently truncating an operator's only diagnostic.
+pub const max_error_len: usize = 192;
 
 /// `SourceStatus.url` is fixed-size so a copied status borrows nothing. A
 /// blocklist url longer than this is truncated in the status only; the row
@@ -131,6 +136,55 @@ const SourceLabel = struct {
     }
 };
 
+/// The one place the download failure text is formatted. `phase`, `cause` and
+/// the byte count come from the fetcher's record of the concrete fault.
+///
+/// A timeout carries a record like any other failure: `fetchWithin` cancels the
+/// fetch on its way out of the race, and the cancelled fetch records the phase
+/// it was in, the status if a head had arrived and the bytes delivered so far,
+/// all before this function reads it. So an expiry reads
+/// `Timeout (receive_body, cause Canceled, http 200, 5242880 bytes, 300000 ms)`.
+/// `no fetch` and `-` are for a failure that never reached the network at all:
+/// `download` clears the record before anything can fail, so a local fault —
+/// the temporary file, an allocation, a refused task — reads as its own
+/// taxonomy name with nothing borrowed from the source fetched before it.
+fn downloadFailureText(
+    buf: []u8,
+    err: anyerror,
+    failure: ?fetcher.Failure,
+    last_status: ?std.http.Status,
+    elapsed_ms: u64,
+) []const u8 {
+    var status_buf: [8]u8 = undefined;
+    const status_text = if (if (failure) |f| f.status else last_status) |code|
+        std.fmt.bufPrint(&status_buf, "{d}", .{@intFromEnum(code)}) catch "none"
+    else
+        "none";
+
+    var bytes_buf: [24]u8 = undefined;
+    const bytes_text = if (failure) |f|
+        std.fmt.bufPrint(&bytes_buf, "{d}", .{f.bytes_read}) catch "-"
+    else
+        "-";
+
+    if (failure) |f| {
+        return std.fmt.bufPrint(buf, "{s} ({s}, cause {s}, http {s}, {s} bytes, {d} ms)", .{
+            @errorName(err),
+            @tagName(f.phase),
+            @errorName(f.cause),
+            status_text,
+            bytes_text,
+            elapsed_ms,
+        }) catch @errorName(err);
+    }
+    return std.fmt.bufPrint(buf, "{s} (no fetch, http {s}, {s} bytes, {d} ms)", .{
+        @errorName(err),
+        status_text,
+        bytes_text,
+        elapsed_ms,
+    }) catch @errorName(err);
+}
+
 pub const Paths = struct {
     /// `<data_dir>`, owned by the caller and left open for the manager's life.
     dir: std.Io.Dir,
@@ -1169,11 +1223,12 @@ pub const Manager = struct {
         raw_name: []const u8,
         tmp: TempNames,
     ) Error!Prepared {
-        self.download(io, dir, raw_name, row) catch |err| switch (err) {
+        var elapsed_ms: u64 = 0;
+        self.download(io, dir, raw_name, row, &elapsed_ms) catch |err| switch (err) {
             error.OutOfMemory => return error.OutOfMemory,
             error.Canceled => return error.Canceled,
             else => {
-                self.reportFetchFailure(row, status, err);
+                self.reportDownloadFailure(row, status, err, elapsed_ms);
                 return .failed;
             },
         };
@@ -1297,7 +1352,18 @@ pub const Manager = struct {
         dir: std.Io.Dir,
         raw_name: []const u8,
         row: sources_repo.SourceRow,
+        /// Milliseconds the download itself took, set whether it succeeded or
+        /// failed, so the failure line can say how long the peer had.
+        elapsed_ms: *u64,
     ) !void {
+        // Ahead of everything that can fail. The record is the fetcher's, not
+        // this source's, and a local failure here — the create, the allocation,
+        // a refused task — would otherwise leave the PREVIOUS source's network
+        // cause in place for `reportDownloadFailure` to print as this one's.
+        // Cleared here, a null record means no fetch reached the network.
+        self.fetcher.last_failure = null;
+        self.fetcher.last_status = null;
+
         const file = try dir.createFile(io, raw_name, .{ .permissions = .fromMode(0o600) });
         defer file.close(io);
 
@@ -1305,16 +1371,14 @@ pub const Manager = struct {
         defer self.gpa.free(buffer);
 
         var fw = file.writer(io, buffer);
-        const result = self.fetchWithin(io, row.url, &fw.interface) catch |err| {
+        const result = self.fetchWithin(io, row.url, &fw.interface, elapsed_ms) catch |err| {
             // `fetcher.Error.Unexpected` is what a failing sink surfaces as;
             // the concrete cause is on this writer, which the fetcher does not
             // own.
             if (fw.err) |cause| return cause;
-            if (err == error.HttpStatus) {
-                if (self.fetcher.last_status) |status| {
-                    log.warn("blocklist {f}: http status {d}", .{ SourceLabel.of(row), @intFromEnum(status) });
-                }
-            }
+            // The status used to get a second warning of its own. It is a field
+            // of the one download-failure line now, so a second line would only
+            // repeat it.
             return err;
         };
         try fw.interface.flush();
@@ -1332,7 +1396,12 @@ pub const Manager = struct {
         io: std.Io,
         url: []const u8,
         w: *std.Io.Writer,
+        elapsed_ms: *u64,
     ) fetcher.Error!fetcher.Result {
+        // `awake` and not `real`: an operator reading "812 ms" wants the time
+        // the transfer was given, which a stepped wall clock would misreport.
+        const started = std.Io.Clock.awake.now(io);
+
         var outcomes: [2]Outcome = undefined;
         var race: std.Io.Select(Outcome) = .init(io, &outcomes);
         defer race.cancelDiscard();
@@ -1344,7 +1413,12 @@ pub const Manager = struct {
             error.ConcurrencyUnavailable => return error.SystemResources,
         };
 
-        switch (try race.await()) {
+        // Read before the deferred `cancelDiscard`, which tears the loser down:
+        // the number is the time the peer had, not that plus the teardown.
+        const outcome = race.await();
+        elapsed_ms.* = @intCast(@max(0, started.durationTo(std.Io.Clock.awake.now(io)).toMilliseconds()));
+
+        switch (try outcome) {
             .fetch => |result| return result,
             .expiry => |result| {
                 // A canceled sleep means this task is being torn down, not that
@@ -1514,15 +1588,21 @@ pub const Manager = struct {
         return compiledBodiesMatch(list_bytes, wild_bytes, allow_bytes, expected);
     }
 
-    fn reportFetchFailure(
+    /// One line per failed source per pass, and the only place the download
+    /// failure text is built. The Diagnostics event detail gets the same text,
+    /// so an operator reading either can tell a TLS alert from a reset
+    /// connection from a truncated chunk.
+    fn reportDownloadFailure(
         self: *Manager,
         row: sources_repo.SourceRow,
         status: *SourceStatus,
         err: anyerror,
+        elapsed_ms: u64,
     ) void {
-        _ = self;
-        log.warn("blocklist {f}: download failed: {s}", .{ SourceLabel.of(row), @errorName(err) });
-        status.fail(.fetch_failed, @errorName(err));
+        var buf: [max_error_len]u8 = undefined;
+        const text = downloadFailureText(&buf, err, self.fetcher.last_failure, self.fetcher.last_status, elapsed_ms);
+        log.warn("blocklist {f}: download failed: {s}", .{ SourceLabel.of(row), text });
+        status.fail(.fetch_failed, text);
     }
 
     fn reportCompileFailure(
@@ -3580,3 +3660,104 @@ test "setSchedule is what the live schedule readers see" {
     try testing.expectEqual(@as(u16, 6), live.interval_hours);
     try testing.expect(manager.schedule_event.isSet());
 }
+
+test "a download failure line names the concrete cause behind the taxonomy" {
+    var buf: [1024]u8 = undefined;
+    const row: sources_repo.SourceRow = .{
+        .id = 3,
+        .url = "https://lists.example/download/token/hunter2/hosts.txt?apikey=s3cr3t",
+        .name = "ads",
+        .enabled = true,
+        .last_updated = null,
+        .domain_count = 0,
+        .wildcard_count = 0,
+        .skipped_regex_count = 0,
+        .skipped_unsupported_count = 0,
+        .checksum = null,
+    };
+    var text_buf: [max_error_len]u8 = undefined;
+    const text = downloadFailureText(&text_buf, error.ReceiveFailed, .{
+        .phase = .receive_body,
+        .cause = error.HttpChunkTruncated,
+        .status = .ok,
+        .bytes_read = 1024 * 1024,
+    }, .ok, 812);
+
+    const printed = try std.fmt.bufPrint(&buf, "blocklist {f}: download failed: {s}", .{
+        SourceLabel.of(row),
+        text,
+    });
+    try testing.expectEqualStrings(
+        "blocklist source 3 'ads' 'https://lists.example': download failed:" ++
+            " ReceiveFailed (receive_body, cause HttpChunkTruncated, http 200, 1048576 bytes, 812 ms)",
+        printed,
+    );
+    try testing.expect(!std.mem.containsAtLeast(u8, printed, 1, "hunter2"));
+    try testing.expect(!std.mem.containsAtLeast(u8, printed, 1, "s3cr3t"));
+}
+
+test "an expiry names the phase and the progress the cancelled fetch had made" {
+    // `fetchWithin` cancels the fetch before it reports, so a timeout normally
+    // does have a record: the cancellation the fetch saw, under the manager's
+    // own `error.Timeout`.
+    var text_buf: [max_error_len]u8 = undefined;
+    try testing.expectEqualStrings(
+        "Timeout (receive_body, cause Canceled, http 200, 5242880 bytes, 300000 ms)",
+        downloadFailureText(&text_buf, error.Timeout, .{
+            .phase = .receive_body,
+            .cause = error.Canceled,
+            .status = .ok,
+            .bytes_read = 5 * 1024 * 1024,
+        }, .ok, 300000),
+    );
+}
+
+test "a failure that never reached the network says so and borrows nothing" {
+    // `download` clears the fetcher's record before anything can fail, so a
+    // local fault reads as itself. Printing a phase and a cause here would be
+    // printing the previous source's network fault against this source.
+    var text_buf: [max_error_len]u8 = undefined;
+    try testing.expectEqualStrings(
+        "SystemResources (no fetch, http none, - bytes, 0 ms)",
+        downloadFailureText(&text_buf, error.SystemResources, null, null, 0),
+    );
+    try testing.expectEqualStrings(
+        "AccessDenied (no fetch, http none, - bytes, 3 ms)",
+        downloadFailureText(&text_buf, error.AccessDenied, null, null, 3),
+    );
+}
+
+test "max_error_len holds the widest download failure line whole" {
+    // `@errorName` of the unwrapped cause is the only unbounded-looking part.
+    // The two sets below are every set the unwraps in `upstream/transport.zig`
+    // can return a member of.
+    const widest_cause = comptime blk: {
+        var widest: []const u8 = "";
+        for (@typeInfo(std.crypto.tls.Client.ReadError).error_set.?) |member| {
+            if (member.name.len > widest.len) widest = member.name;
+        }
+        for (@typeInfo(std.http.Client.RequestError).error_set.?) |member| {
+            if (member.name.len > widest.len) widest = member.name;
+        }
+        for (@typeInfo(std.http.Reader.BodyError).error_set.?) |member| {
+            if (member.name.len > widest.len) widest = member.name;
+        }
+        break :blk widest;
+    };
+
+    var buf: [max_error_len]u8 = undefined;
+    const text = std.fmt.bufPrint(
+        &buf,
+        "{s} ({s}, cause {s}, http {d}, {d} bytes, {d} ms)",
+        .{
+            "SystemResources",
+            @tagName(fetcher.Phase.receive_body),
+            widest_cause,
+            @as(u16, 599),
+            @as(u64, fetcher.max_body_bytes),
+            @as(u64, std.time.ms_per_hour),
+        },
+    ) catch unreachable;
+    try testing.expect(text.len <= max_error_len);
+    try testing.expectEqualStrings("DetectingNetworkConfigurationFailed", widest_cause);
+}

src/server/doh_server.zig

@@ -148,6 +148,10 @@ pub const DohServer = struct {
         return self.core.boundAddress();
     }
 
+    pub fn connectionsPeak(self: *const DohServer) u64 {
+        return self.core.connectionsPeak();
+    }
+
     pub fn snapshotStats(self: *const DohServer) Snapshot {
         const core = &self.core.stats;
         return .{

src/server/dot_server.zig

@@ -125,6 +125,10 @@ pub const DotServer = struct {
         self.* = undefined;
     }
 
+    pub fn connectionsPeak(self: *const DotServer) u64 {
+        return self.core.connectionsPeak();
+    }
+
     pub fn snapshotStats(self: *const DotServer) StatsSnapshot {
         const core = &self.core.stats;
         return .{

src/server/handler.zig

@@ -130,6 +130,11 @@ pub const Handler = struct {
     pause: ?*pause.Pause = null,
     tracker: ?*clients.Tracker = null,
     stats: Stats = .{},
+    /// Queries inside `handle` right now, across every listener, and the most
+    /// there have been at once (specs/memory-budget.md item 0). Gauges, so they
+    /// stay out of `Stats`, which `/metrics` exports field by field as counters.
+    in_flight: std.atomic.Value(u64) = .init(0),
+    in_flight_peak: std.atomic.Value(u64) = .init(0),
 
     pub const Stats = struct {
         /// Queries answered by the upstream pool.
@@ -229,6 +234,21 @@ pub const Handler = struct {
         query: []const u8,
         response_buf: []u8,
         scratch: *Scratch,
+    ) Outcome {
+        const now_in_flight = self.in_flight.fetchAdd(1, .monotonic) + 1;
+        _ = self.in_flight_peak.fetchMax(now_in_flight, .monotonic);
+        defer _ = self.in_flight.fetchSub(1, .monotonic);
+        return self.answer(io, which, from, query, response_buf, scratch);
+    }
+
+    fn answer(
+        self: *Handler,
+        io: std.Io,
+        which: Transport,
+        from: address.NetAddress,
+        query: []const u8,
+        response_buf: []u8,
+        scratch: *Scratch,
     ) Outcome {
         std.debug.assert(response_buf.len >= udp_limit_min);
         std.debug.assert(response_buf.len <= transport.max_message_len);
@@ -1459,6 +1479,24 @@ test "a response arriving on the listener port is dropped" {
     try testing.expectEqual(@as(usize, 0), fake.calls);
 }
 
+test "every query counts in flight for exactly its own handling" {
+    var t: TestIo = .init();
+    defer t.deinit();
+
+    var fake: FakeUpstream = .{ .reply = response_bytes };
+    var h_owner: upstream_owner.Borrowed = .{};
+    var h = bare(h_owner.client(fake.client()));
+    // Two queries other listeners are still handling.
+    h.in_flight.store(2, .monotonic);
+
+    var buf: [udp_limit_min]u8 = undefined;
+    try testing.expect(udp(&h, t.io(), query_bytes, &buf) == .reply);
+    try testing.expectEqual(Handler.Outcome.drop, udp(&h, t.io(), response_bytes, &buf));
+
+    try testing.expectEqual(@as(u64, 2), h.in_flight.load(.monotonic));
+    try testing.expectEqual(@as(u64, 3), h.in_flight_peak.load(.monotonic));
+}
+
 test "a query shorter than a header is dropped" {
     var t: TestIo = .init();
     defer t.deinit();

src/server/listener.zig

@@ -83,6 +83,10 @@ pub const CoreStats = struct {
     accept_errors: std.atomic.Value(u64) = .init(0),
     connection_errors: std.atomic.Value(u64) = .init(0),
     idle_timeouts: std.atomic.Value(u64) = .init(0),
+    /// The most slots that have been taken at once (specs/memory-budget.md
+    /// item 0). A gauge, so no listener's `Snapshot` carries it: those export
+    /// every field as a counter. Written only under `Core.mutex`.
+    connections_peak: std.atomic.Value(u64) = .init(0),
 };
 
 // ---------------------------------------------------------------------------
@@ -255,6 +259,9 @@ pub fn Core(comptime Cfg: type) type {
         /// that shuts the active connections down, so a stream that arrives
         /// after that scan can never claim a slot the scan will not visit again.
         shutdown_begun: bool,
+        /// Guarded by `mutex`. Slots that are not `.free`: a slot is taken from
+        /// `claim` until `finish` frees it, closing included.
+        taken: u64,
         stats: CoreStats,
         run_state: std.atomic.Value(State),
         stopped: std.Io.Event,
@@ -299,6 +306,7 @@ pub fn Core(comptime Cfg: type) type {
                 .conns = conns,
                 .mutex = .init,
                 .shutdown_begun = false,
+                .taken = 0,
                 .stats = .{},
                 .run_state = .init(.idle),
                 .stopped = .unset,
@@ -336,6 +344,10 @@ pub fn Core(comptime Cfg: type) type {
             return self.listener.socket.address;
         }
 
+        pub fn connectionsPeak(self: *const Self) u64 {
+            return self.stats.connections_peak.load(.monotonic);
+        }
+
         /// Accept loop. Returns when the task is canceled or `deinit` stops it.
         pub fn serve(self: *Self, io: std.Io) void {
             if (self.run_state.cmpxchgStrong(.idle, .serving, .acq_rel, .acquire) != null) return;
@@ -443,6 +455,10 @@ pub fn Core(comptime Cfg: type) type {
                     self.conns[index].stream = stream;
                     self.conns[index].peer = stream.socket.address;
                     self.conns[index].state = .active;
+                    self.taken += 1;
+                    if (self.taken > self.stats.connections_peak.load(.monotonic)) {
+                        self.stats.connections_peak.store(self.taken, .monotonic);
+                    }
                 },
                 .at_capacity, .shutting_down => {},
             }
@@ -464,6 +480,7 @@ pub fn Core(comptime Cfg: type) type {
 
             self.mutex.lockUncancelable(io);
             conn.state = .free;
+            self.taken -= 1;
             self.mutex.unlock(io);
         }
 

src/server/resolver_integration_test.zig

@@ -93,15 +93,21 @@ fn queryWithId(buf: *[query_bytes.len]u8, id: u16) []const u8 {
 /// Echoes the question and appends one A record. This is the smallest thing a
 /// real upstream could return that the handler forwards unchanged, so the
 /// assertions below check bytes that travelled the whole path.
-fn answerQuery(query: []const u8, response_buf: []u8) transport.ExchangeError![]u8 {
-    const request = packet.parse(query) catch return error.BadResponse;
-    const q = packet.firstQuestion(request) orelse return error.BadResponse;
+fn answerQuery(query: []const u8, response_buf: []u8) transport.Outcome {
+    const request = packet.parse(query) catch return peerFault(error.BadResponse);
+    const q = packet.firstQuestion(request) orelse return peerFault(error.BadResponse);
 
     var b = packet.ResponseBuilder.init(response_buf, request.header, q) catch
-        return error.ResponseTooLarge;
+        return peerFault(error.ResponseTooLarge);
     b.addAnswer(q.name, .a, .in, answer_ttl, &answer_rdata) catch
-        return error.ResponseTooLarge;
-    return b.finish();
+        return peerFault(error.ResponseTooLarge);
+    return .{ .reply = b.finish() };
+}
+
+/// A fault whose cause is its own classification: these fixtures fail on
+/// purpose and have no concrete cause behind the classification.
+fn peerFault(kind: transport.PeerFault) transport.Outcome {
+    return .{ .fault = .{ .kind = kind, .cause = kind } };
 }
 
 /// The healthy upstream. `calls` is atomic because the listener tasks run on
@@ -114,16 +120,14 @@ const GoodUpstream = struct {
         io: std.Io,
         query: []const u8,
         response_buf: []u8,
-        selected: *?[]const u8,
-    ) transport.ExchangeError![]u8 {
+    ) transport.LeafError!transport.Outcome {
         _ = io;
-        selected.* = "fake://good-upstream";
         const self: *GoodUpstream = @ptrCast(@alignCast(ptr));
         _ = self.calls.fetchAdd(1, .monotonic);
         return answerQuery(query, response_buf);
     }
 
-    fn client(self: *GoodUpstream) transport.Client {
+    fn leaf(self: *GoodUpstream) transport.Leaf {
         return .{ .ptr = self, .exchangeFn = exchangeFn };
     }
 };
@@ -140,17 +144,15 @@ const FaultyUpstream = struct {
         io: std.Io,
         query: []const u8,
         response_buf: []u8,
-        selected: *?[]const u8,
-    ) transport.ExchangeError![]u8 {
+    ) transport.LeafError!transport.Outcome {
         _ = io;
-        selected.* = "fake://faulty-upstream";
         const self: *FaultyUpstream = @ptrCast(@alignCast(ptr));
         const seen = self.calls.fetchAdd(1, .monotonic);
-        if (seen < self.fail_first) return self.fault;
+        if (seen < self.fail_first) return peerFault(self.fault);
         return answerQuery(query, response_buf);
     }
 
-    fn client(self: *FaultyUpstream) transport.Client {
+    fn leaf(self: *FaultyUpstream) transport.Leaf {
         return .{ .ptr = self, .exchangeFn = exchangeFn };
     }
 };
@@ -166,10 +168,10 @@ const EntryStorage = struct {
     fn entry(
         self: *EntryStorage,
         url: []const u8,
-        upstream_client: transport.Client,
+        upstream_leaf: transport.Leaf,
         priority: i32,
     ) pool.Entry {
-        self.slots[0] = .{ .client = upstream_client };
+        self.slots[0] = .{ .client = upstream_leaf };
         return .{
             .endpoint = transport.Endpoint.parse(url) catch unreachable,
             .slots = &self.slots,
@@ -270,8 +272,8 @@ test "the whole resolver answers over udp and tcp and fails over to a healthy up
     var bad_storage: EntryStorage = .{};
     var good_storage: EntryStorage = .{};
     var entries = [_]pool.Entry{
-        bad_storage.entry("https://bad.example/dns-query", bad.client(), 10),
-        good_storage.entry("tls://good.example", good.client(), 20),
+        bad_storage.entry("https://bad.example/dns-query", bad.leaf(), 10),
+        good_storage.entry("tls://good.example", good.leaf(), 20),
     };
     var upstreams: pool.Pool = .init(&entries, test_cfg, pool_timeouts, 1);
 

src/server/tcp_server.zig

@@ -99,6 +99,10 @@ pub const TcpServer = struct {
         return self.core.boundAddress();
     }
 
+    pub fn connectionsPeak(self: *const TcpServer) u64 {
+        return self.core.connectionsPeak();
+    }
+
     /// The counters, read one at a time. A scrape that lands mid-accept can see
     /// a connection counted before its outcome is; a lock would buy a
     /// consistency no consumer needs.

src/server/tcp_server_integration_test.zig

@@ -329,6 +329,52 @@ test "a canceled serve does not wait for a live connection" {
     try client_result;
 }
 
+test "the connections peak is the most slots held at once" {
+    if (!build_options.integration) return error.SkipZigTest;
+
+    const gpa = testing.allocator;
+    var threaded: std.Io.Threaded = .init(gpa, .{});
+    defer threaded.deinit();
+    const io = threaded.io();
+
+    var fake: FakeUpstream = .{ .reply = response_bytes };
+    var h_owner: upstream_owner.Borrowed = .{};
+    var h = bareHandler(h_owner.client(fake.client()));
+
+    const listen_address: net.IpAddress = try .parse("127.0.0.1", 0);
+    var server = try tcp_server.TcpServer.listen(gpa, io, listen_address, &h, .{
+        .max_connections = 3,
+        .idle_timeout = .{ .raw = .fromSeconds(600), .clock = .awake },
+    });
+    const server_address = server.boundAddress();
+
+    var serving: std.Io.Group = .init;
+    try serving.concurrent(io, tcp_server.TcpServer.serve, .{ &server, io });
+
+    var answered: [2]std.Io.Event = @splat(.unset);
+    var client_results: [2]anyerror!void = @splat({});
+    var clients_group: std.Io.Group = .init;
+    for (&answered, &client_results) |*event, *result| {
+        try clients_group.concurrent(io, holdConnection, .{ io, server_address, event, result });
+    }
+    for (&answered) |*event| event.waitUncancelable(io);
+
+    // Both replies prove both slots are claimed, and the listener has room for
+    // a third that never arrives.
+    const held_open = server.connectionsPeak();
+
+    server.deinit(io);
+    serving.await(io) catch |err| switch (err) {
+        error.Canceled => unreachable,
+    };
+    clients_group.await(io) catch |err| switch (err) {
+        error.Canceled => unreachable,
+    };
+
+    for (client_results) |result| try result;
+    try testing.expectEqual(@as(u64, 2), held_open);
+}
+
 /// The first slot the server would hand out, read after `serve` has returned so
 /// nothing can be writing it.
 fn firstFreeSlot(server: *const tcp_server.TcpServer) ?usize {

src/storage/events.zig

@@ -322,6 +322,74 @@ pub const Store = struct {
         if (!self.active.put(code, digest, id)) self.untracked_active_count += 1;
     }
 
+    /// Opens the episode of `subject_key` when none is open, and restates the
+    /// severity and the detail of the one that is.
+    ///
+    /// The projection counterpart of `report`. A reconciliation asserts the
+    /// state an endpoint is in now; it is not a new observation, so it must not
+    /// raise `occurrences` or move `last_seen`. It does own the text: a retired
+    /// generation's late report can leave a stale cause on a card the live
+    /// generation still holds open, and this is what restores the true one.
+    /// Only a recorded failure calls `report`.
+    ///
+    /// The open check is a statement rather than a mirror lookup: the mirror is
+    /// a hint that can point at a row that is gone or already closed, and
+    /// `report` recovers from that through the touch it was making anyway.
+    /// There is no write here to learn it from, so this asks. That costs one
+    /// SELECT per reconciled subject, on a path that runs at boot and at a
+    /// generation retirement.
+    pub fn ensureOpen(
+        self: *Store,
+        io: std.Io,
+        now_s: i64,
+        code: Code,
+        subject_key: []const u8,
+        subject_label: []const u8,
+        severity: Severity,
+        detail: []const u8,
+    ) void {
+        var key_buf: [max_subject_key_len]u8 = undefined;
+        const key = canonicalKey(subject_key, &key_buf);
+        const label = truncate(subject_label, max_subject_label_len);
+        const text = truncate(detail, max_detail_len);
+        const digest = digestOf(key);
+
+        self.mutex.lockUncancelable(io);
+        defer self.mutex.unlock(io);
+
+        self.count();
+        const existing = events_repo.selectActiveId(self.database, wire(code), key) catch |err|
+            return self.recordFailure(err);
+
+        // The read is not what clears the write latch: a `resolveExcept` that
+        // failed a moment ago is still the last word on whether this store can
+        // write, and only a write of our own can answer that.
+        if (existing) |id| {
+            self.count();
+            _ = events_repo.restateActive(self.database, id, severity.text(), text) catch |err|
+                return self.recordFailure(err);
+            return self.recordSuccess();
+        }
+
+        // Nothing is open, so a mirror entry claiming otherwise is stale and
+        // would make the insert below look like a collision.
+        if (self.active.find(code, digest)) |entry| self.active.remove(entry);
+
+        self.count();
+        const id = events_repo.insertActive(
+            self.database,
+            now_s,
+            wire(code),
+            key,
+            label,
+            severity.text(),
+            text,
+        ) catch |err| return self.recordFailure(err);
+        self.recordSuccess();
+
+        if (!self.active.put(code, digest, id)) self.untracked_active_count += 1;
+    }
+
     /// Records that `subject_key` is working again, closing its episode if one
     /// is open.
     ///
@@ -930,6 +998,38 @@ test "resolving a subject with nothing open executes no SQL at all" {
     try testing.expectEqual(after_resolve, store.statements);
 }
 
+test "ensureOpen opens a missing episode and restates an open one without counting it" {
+    var fx: Fixture = .{};
+    try fx.init(1000);
+    defer fx.deinit();
+    const store = &fx.store;
+
+    // The reconciliation path: it must be able to reassert a subject that is
+    // still failing without inventing an occurrence no exchange produced.
+    store.ensureOpen(fx.io, 1000, .upstream_exchange, "https://a.example", "a.example", .warning, "Timeout (cause Timeout)");
+    try testing.expectEqual(@as(i64, 1), try fx.count("SELECT count(*) FROM operational_events WHERE resolved_at IS NULL"));
+    try testing.expectEqual(@as(i64, 1), try fx.count("SELECT occurrences FROM operational_events"));
+    try testing.expectEqual(@as(i64, 1000), try fx.count("SELECT last_seen FROM operational_events"));
+
+    // The second call is a reconciliation of a card that is already open: the
+    // text and the severity are the reconciler's to state, and the counters
+    // belong to the exchanges that actually failed.
+    store.ensureOpen(fx.io, 1500, .upstream_exchange, "https://a.example", "a.example", .@"error", "SendFailed (cause BrokenPipe)");
+    try testing.expectEqual(@as(i64, 1), try fx.count("SELECT count(*) FROM operational_events"));
+    try testing.expectEqual(@as(i64, 1), try fx.count("SELECT occurrences FROM operational_events"));
+    try testing.expectEqual(@as(i64, 1000), try fx.count("SELECT first_seen FROM operational_events"));
+    try testing.expectEqual(@as(i64, 1000), try fx.count("SELECT last_seen FROM operational_events"));
+    try testing.expectEqualStrings("error", try fx.text("SELECT severity FROM operational_events"));
+    try testing.expectEqualStrings("SendFailed (cause BrokenPipe)", try fx.text("SELECT detail FROM operational_events"));
+
+    // And once the episode is resolved it opens a second one, like any other
+    // entry point.
+    store.resolve(fx.io, 1600, .upstream_exchange, "https://a.example");
+    store.ensureOpen(fx.io, 1700, .upstream_exchange, "https://a.example", "a.example", .warning, "Timeout (cause Timeout)");
+    try testing.expectEqual(@as(i64, 2), try fx.count("SELECT count(*) FROM operational_events"));
+    try testing.expectEqual(@as(i64, 1700), try fx.count("SELECT first_seen FROM operational_events WHERE id = 2"));
+}
+
 test "a one-shot event inserts already resolved and never enters the mirror" {
     var fx: Fixture = .{};
     try fx.init(1000);

src/storage/logger.zig

@@ -320,7 +320,68 @@ fn emptyAsNull(value: []const u8) ?[]const u8 {
     return if (value.len == 0) null else value;
 }
 
-const EntryQueue = std.Io.Queue(Entry);
+/// `std.Io.Queue` plus the occupancy high-water that sizes
+/// `logging.query_log_buffer_max` (specs/memory-budget.md item 0).
+///
+/// The queue keeps its length behind its own mutex with no accessor, so the
+/// count lives beside it. Raised before an insert and lowered after a removal,
+/// it never reads below the true occupancy; it overstates it by at most the
+/// producers inside `tryPut` plus the entries a getter has taken and not yet
+/// subtracted. An upper bound is the safe side for sizing a buffer.
+const EntryQueue = struct {
+    inner: std.Io.Queue(Entry),
+    held: std.atomic.Value(u64) = .init(0),
+    peak: std.atomic.Value(u64) = .init(0),
+
+    pub fn init(buffer: []Entry) EntryQueue {
+        return .{ .inner = .init(buffer) };
+    }
+
+    pub fn capacity(q: *const EntryQueue) usize {
+        return q.inner.capacity();
+    }
+
+    pub fn close(q: *EntryQueue, io: std.Io) void {
+        q.inner.close(io);
+    }
+
+    pub fn peakOccupancy(q: *const EntryQueue) u64 {
+        return q.peak.load(.monotonic);
+    }
+
+    /// Takes `entry` if there is room or a waiting getter, without blocking.
+    pub fn tryPut(q: *EntryQueue, io: std.Io, entry: Entry) (std.Io.QueueClosedError || std.Io.Cancelable)!bool {
+        const held = q.held.fetchAdd(1, .monotonic) + 1;
+        const put = q.inner.put(io, &.{entry}, 0) catch |err| {
+            _ = q.held.fetchSub(1, .monotonic);
+            return err;
+        };
+        if (put == 0) {
+            _ = q.held.fetchSub(1, .monotonic);
+            return false;
+        }
+        _ = q.peak.fetchMax(held, .monotonic);
+        return true;
+    }
+
+    pub fn get(q: *EntryQueue, io: std.Io, buffer: []Entry, min: usize) (std.Io.QueueClosedError || std.Io.Cancelable)!usize {
+        const n = try q.inner.get(io, buffer, min);
+        _ = q.held.fetchSub(n, .monotonic);
+        return n;
+    }
+
+    pub fn getUncancelable(q: *EntryQueue, io: std.Io, buffer: []Entry, min: usize) std.Io.QueueClosedError!usize {
+        const n = try q.inner.getUncancelable(io, buffer, min);
+        _ = q.held.fetchSub(n, .monotonic);
+        return n;
+    }
+
+    pub fn getOne(q: *EntryQueue, io: std.Io) (std.Io.QueueClosedError || std.Io.Cancelable)!Entry {
+        const entry = try q.inner.getOne(io);
+        _ = q.held.fetchSub(1, .monotonic);
+        return entry;
+    }
+};
 
 /// A database failure is not in here: a batch the database refuses is dropped,
 /// counted and reported where it happens, and the writer carries on.
@@ -525,8 +586,7 @@ pub const Logger = struct {
         while (true) {
             // A closed queue or a canceled task means shutdown is underway;
             // both leave this entry unwritten, which is what the counter says.
-            const put = self.queue.put(io, &.{entry}, 0) catch break;
-            if (put == 1) return;
+            if (self.queue.tryPut(io, entry) catch break) return;
 
             // A zero-capacity queue holds nothing to drop: the put above was
             // this entry's one chance at a waiting getter.
@@ -1442,6 +1502,34 @@ test "a zero-capacity queue drops every entry exactly once" {
     try testing.expectEqual(@as(u64, 5), logger.queries_dropped.load(.monotonic));
 }
 
+test "the queue peak is the most entries held at once, never the arrivals" {
+    var threaded: std.Io.Threaded = .init(testing.allocator, .{});
+    defer threaded.deinit();
+    const io = threaded.io();
+
+    var buf: [4]Entry = undefined;
+    var logger: Logger = .init(.{}, &buf);
+    try testing.expectEqual(@as(u64, 0), logger.queue.peakOccupancy());
+
+    logger.log(io, sampleEntry(1, "one.example"));
+    logger.log(io, sampleEntry(2, "two.example"));
+    logger.log(io, sampleEntry(3, "three.example"));
+    _ = try logger.queue.getOne(io);
+    _ = try logger.queue.getOne(io);
+    logger.log(io, sampleEntry(4, "four.example"));
+    try testing.expectEqual(@as(u64, 3), logger.queue.peakOccupancy());
+
+    // A full queue evicts to make room, so the peak stops at the capacity.
+    for (5..10) |i| logger.log(io, sampleEntry(@intCast(i), "more.example"));
+    try testing.expectEqual(@as(u64, 4), logger.queue.peakOccupancy());
+    try testing.expectEqual(@as(u64, 4), logger.queue.held.load(.monotonic));
+
+    var drained: [4]Entry = undefined;
+    try testing.expectEqual(@as(usize, 4), try logger.queue.get(io, &drained, 0));
+    try testing.expectEqual(@as(u64, 0), logger.queue.held.load(.monotonic));
+    try testing.expectEqual(@as(u64, 4), logger.queue.peakOccupancy());
+}
+
 test "log after shutdown drops instead of blocking" {
     var threaded: std.Io.Threaded = .init(testing.allocator, .{});
     defer threaded.deinit();

src/storage/logger_controller.zig

@@ -63,12 +63,14 @@ const Totals = struct {
     rows_written: u64 = 0,
     batches_gated: u64 = 0,
     last_drop_s: i64 = 0,
+    queue_peak: u64 = 0,
 
     fn fold(self: *Totals, lg: *const logger.Logger) void {
         self.queries_dropped += lg.queries_dropped.load(.monotonic);
         self.rows_written += lg.rows_written.load(.monotonic);
         self.batches_gated += lg.batches_gated.load(.monotonic);
         self.last_drop_s = @max(self.last_drop_s, lg.last_drop_s.load(.monotonic));
+        self.queue_peak = @max(self.queue_peak, lg.queue.peakOccupancy());
     }
 };
 
@@ -80,6 +82,8 @@ pub const Sample = struct {
     batches_gated: u64,
     /// Null while nothing has been dropped, exactly as `Logger.lastDropSeconds`.
     last_drop_s: ?i64,
+    /// The most entries any generation's queue has held at once.
+    queue_peak: u64,
     /// The LIVE writer's state. A retired writer's failures are in the counters.
     writer_failed: bool,
     /// The worst episode any outstanding generation is in. A retired writer
@@ -376,6 +380,7 @@ pub const Controller = struct {
             .rows_written = totals.rows_written,
             .batches_gated = totals.batches_gated,
             .last_drop_s = if (totals.last_drop_s == 0) null else totals.last_drop_s,
+            .queue_peak = totals.queue_peak,
             .writer_failed = self.live.logger.writer_failed.load(.acquire),
             .gate_episode = episode,
         };

src/storage/repositories/events_repo.zig

@@ -135,6 +135,35 @@ pub fn touchActive(
     return database.changes() != 0;
 }
 
+const restate_sql =
+    \\UPDATE operational_events
+    \\   SET detail = ?2,
+    \\       severity = ?3
+    \\ WHERE id = ?1 AND resolved_at IS NULL
+;
+
+/// Restates what an open episode says without claiming it happened again:
+/// `occurrences`, `first_seen` and `last_seen` keep the values the real
+/// failures wrote. The severity `CASE` of `touch_sql` is deliberately absent —
+/// a reconciliation asserts the current state of the subject, so it must be
+/// able to lower a severity a retired generation's late report raised.
+///
+/// False means the row was not there or was already resolved.
+pub fn restateActive(
+    database: *db.Db,
+    id: i64,
+    severity: []const u8,
+    detail: []const u8,
+) db.Error!bool {
+    var stmt = try database.prepare(restate_sql);
+    defer stmt.deinit();
+    try stmt.bindInt(1, id);
+    try stmt.bindText(2, detail);
+    try stmt.bindText(3, severity);
+    try stmt.exec();
+    return database.changes() != 0;
+}
+
 const resolve_by_id_sql =
     "UPDATE operational_events SET resolved_at = ?2 WHERE id = ?1 AND resolved_at IS NULL";
 

src/tests.zig

@@ -21,6 +21,7 @@ comptime {
     _ = @import("upstream/health.zig");
     _ = @import("upstream/doh_client.zig");
     _ = @import("upstream/doh_client_live_test.zig");
+    _ = @import("upstream/doh_client_integration_test.zig");
     _ = @import("upstream/pool.zig");
     _ = @import("upstream/owner.zig");
     _ = @import("upstream/dot_client.zig");

src/upstream/doh_client.zig

@@ -66,7 +66,7 @@ pub const DohClient = struct {
         };
     }
 
-    pub fn client(self: *DohClient) transport.Client {
+    pub fn leaf(self: *DohClient) transport.Leaf {
         return .{ .ptr = self, .exchangeFn = exchangeFn };
     }
 
@@ -75,12 +75,8 @@ pub const DohClient = struct {
         io: std.Io,
         query: []const u8,
         response_buf: []u8,
-        selected: *?[]const u8,
-    ) transport.ExchangeError![]u8 {
+    ) transport.LeafError!transport.Outcome {
         const self: *DohClient = @ptrCast(@alignCast(ptr));
-        // The endpoint outlives the client, so the borrow is safe for the whole
-        // query. Set before the attempt: a failure names this resolver too.
-        selected.* = self.endpoint.url;
         return self.exchange(io, query, response_buf);
     }
 
@@ -96,7 +92,7 @@ pub const DohClient = struct {
         io: std.Io,
         query: []const u8,
         response_buf: []u8,
-    ) transport.ExchangeError![]u8 {
+    ) transport.LeafError!transport.Outcome {
         // `std.http.Client` carries the `std.Io` it was constructed with and
         // takes none per request, so the interface's `io` is unused here. It
         // stays in the signature because DoT and the pool need it.
@@ -117,22 +113,26 @@ pub const DohClient = struct {
             // `Request.Headers` has no `accept` field, so this one goes in by
             // hand.
             .extra_headers = &.{.{ .name = "accept", .value = media_type }},
-        }) catch |err| return mapError(err, .connect);
+        }) catch |err| return fault(err, .connect);
         defer req.deinit();
 
         req.sendBodyComplete(self.request_buf[0..query.len]) catch |err|
-            return mapError(sendCause(&req, err), .send);
+            return fault(sendCause(&req, err), .send);
 
         // An empty redirect buffer is legal under `.not_allowed`: a redirect
         // is an error before the location is ever read.
-        var resp = req.receiveHead(&.{}) catch |err| return mapError(headCause(&req, err), .receive);
+        var resp = req.receiveHead(&.{}) catch |err| return fault(headCause(&req, err), .receive);
 
-        if (resp.head.status != .ok) return error.HttpStatus;
+        if (resp.head.status != .ok) return .{ .fault = .{
+            .kind = error.HttpStatus,
+            .cause = error.HttpStatus,
+            .http_status = resp.head.status,
+        } };
         // `head.content_type` points into memory that `resp.reader` invalidates,
         // so the check happens before the body stream starts.
-        if (!contentTypeOk(resp.head.content_type)) return error.HttpContentType;
+        if (!contentTypeOk(resp.head.content_type)) return peerFault(error.HttpContentType, error.HttpContentType);
         if (resp.head.content_length) |declared| {
-            if (declared > response_buf.len) return error.ResponseTooLarge;
+            if (declared > response_buf.len) return peerFault(error.ResponseTooLarge, error.ResponseTooLarge);
         }
 
         const body = resp.reader(self.transfer_buf);
@@ -140,7 +140,7 @@ pub const DohClient = struct {
         var ended = false;
         while (len < response_buf.len) {
             const n = body.readSliceShort(response_buf[len..]) catch |err|
-                return mapError(bodyCause(&resp, err), .receive);
+                return fault(bodyCause(&resp, err), .receive);
             len += n;
             if (n == 0) {
                 ended = true;
@@ -152,12 +152,13 @@ pub const DohClient = struct {
             // that fits from one that was cut off.
             var probe: [1]u8 = undefined;
             const n = body.readSliceShort(&probe) catch |err|
-                return mapError(bodyCause(&resp, err), .receive);
-            if (n != 0) return error.ResponseTooLarge;
+                return fault(bodyCause(&resp, err), .receive);
+            if (n != 0) return peerFault(error.ResponseTooLarge, error.ResponseTooLarge);
         }
 
-        try transport.validateResponse(query, response_buf[0..len]);
-        return response_buf[0..len];
+        transport.validateResponse(query, response_buf[0..len]) catch |err|
+            return peerFault(err, err);
+        return .{ .reply = response_buf[0..len] };
     }
 };
 
@@ -177,8 +178,30 @@ const Phase = enum { connect, send, receive };
 ///   `Connection.getReadError` (Client.zig:392), so its record-layer members
 ///   arrive here as themselves. Without them a decode error or a bad record MAC
 ///   would be reported as a plain receive failure.
-fn mapError(err: anyerror, phase: Phase) transport.ExchangeError {
-    if (transport.mapLocal(err)) |local| return local;
+fn fault(err: anyerror, phase: Phase) transport.LeafError!transport.Outcome {
+    // `.connect` is the whole of `http.request`: the name lookup, the TCP
+    // connect and the handshake. The handshake's only `error.Unexpected` is the
+    // errno the socket stream stored (std/http/Client.zig:1466; the TLS
+    // client's `InitError` has none), and a CA bundle scan fails as
+    // `CertificateBundleLoadFailure`. The lookup's resolver socket can fail
+    // locally, but that still leaves this upstream unreachable while a DoT
+    // upstream, always an IP literal, needs no lookup, so the fault belongs to
+    // this endpoint and the pool is right to move on.
+    const local = switch (phase) {
+        .connect => transport.mapLocalConnect(err),
+        .send, .receive => transport.mapLocal(err),
+    };
+    if (local) |claimed| return claimed;
+    return peerFault(kindOf(err, phase), err);
+}
+
+/// A peer fault as an `Outcome`. Written out rather than inlined at every call
+/// site so the classification and the cause cannot drift apart by a typo.
+fn peerFault(kind: transport.PeerFault, cause: anyerror) transport.Outcome {
+    return .{ .fault = .{ .kind = kind, .cause = cause } };
+}
+
+fn kindOf(err: anyerror, phase: Phase) transport.PeerFault {
     switch (err) {
         error.TlsInitializationFailed,
         error.CertificateBundleLoadFailure,
@@ -209,7 +232,7 @@ fn mapError(err: anyerror, phase: Phase) transport.ExchangeError {
 comptime {
     for (@typeInfo(std.crypto.tls.Client.ReadError).error_set.?) |member| {
         const value: anyerror = @field(std.crypto.tls.Client.ReadError, member.name);
-        if (mapError(value, .receive) != error.TlsFailed) {
+        if (kindOf(value, .receive) != error.TlsFailed) {
             @compileError("unclassified TLS read cause: " ++ member.name);
         }
     }
@@ -226,43 +249,12 @@ const Connection = std.http.Client.Connection;
 const Request = std.http.Client.Request;
 const Response = std.http.Client.Response;
 
-/// `std.Io.Writer` collapses every send failure to `error.WriteFailed` and
-/// stashes the cause on the connection's socket writer. Unwrapping it is what
-/// keeps `error.Canceled` and the local resource errors out of the peer fault
-/// group, exactly as `concreteWrite` does for DoT.
-fn sendCause(req: *const Request, err: anyerror) anyerror {
-    if (err != error.WriteFailed) return err;
-    const connection = req.connection orelse return err;
-    return connection.stream_writer.err orelse err;
-}
-
-/// `receiveHead` collapses a transport failure to `error.ReadFailed` and names
-/// `Connection.getReadError` as the accessor for the concrete cause.
-fn headCause(req: *const Request, err: anyerror) anyerror {
-    if (err != error.ReadFailed) return err;
-    const connection = req.connection orelse return err;
-    return readCause(connection, err);
-}
-
-/// A body read reports two different kinds of failure through the same
-/// `error.ReadFailed`. An HTTP framing fault lands on the response, and only a
-/// read that never reached the framing leaves the connection's cause, so the
-/// response is consulted first.
-fn bodyCause(resp: *const Response, err: anyerror) anyerror {
-    if (err != error.ReadFailed) return err;
-    if (resp.bodyErr()) |cause| return cause;
-    const connection = resp.request.connection orelse return err;
-    return readCause(connection, err);
-}
-
-/// `Connection.getReadError` reads the socket reader's stashed cause with `.?`.
-/// On a plain connection that is its only source, so calling it with nothing
-/// stashed would panic rather than return null; the guard keeps this unwrap
-/// total on the path this client can reach without TLS.
-fn readCause(connection: *const Connection, err: anyerror) anyerror {
-    if (connection.protocol == .plain and connection.stream_reader.err == null) return err;
-    return connection.getReadError() orelse err;
-}
+// The unwraps live in `transport.zig` because the blocklist fetcher needs the
+// same concrete causes. They are aliased rather than qualified so the call
+// sites and the tests below read as they did when they were local.
+const sendCause = transport.sendCause;
+const headCause = transport.headCause;
+const bodyCause = transport.bodyCause;
 
 /// RFC 8484 §6: the response media type is `application/dns-message`. The
 /// header may carry parameters (`; charset=…`) and the type is case-insensitive
@@ -299,7 +291,7 @@ test "init builds a uri from the endpoint url" {
     try testing.expectEqualStrings("dns.example", doh.endpoint.host);
 }
 
-test "DohClient satisfies the transport.Client interface" {
+test "DohClient satisfies the transport.Leaf interface" {
     var http: std.http.Client = undefined;
     var request_buf: [min_request_buf]u8 = undefined;
     var transfer_buf: [min_transfer_buf]u8 = undefined;
@@ -309,7 +301,7 @@ test "DohClient satisfies the transport.Client interface" {
     // Instantiation is the check: the vtable is built from `exchangeFn`, so a
     // signature drift is a compile error here. The `std.http.Client` above is
     // never driven, and no exchange runs.
-    const c: transport.Client = doh.client();
+    const c: transport.Leaf = doh.leaf();
     try testing.expectEqual(@as(*anyopaque, @ptrCast(&doh)), c.ptr);
     try testing.expectEqual(
         @as(@TypeOf(c.exchangeFn), DohClient.exchangeFn),
@@ -349,34 +341,52 @@ test "contentTypeOk rejects anything else" {
     try testing.expect(!contentTypeOk("application/dns-message-extra"));
 }
 
-test "mapError maps local errors before phase errors" {
-    try testing.expectEqual(error.OutOfMemory, mapError(error.OutOfMemory, .connect));
-    try testing.expectEqual(error.Canceled, mapError(error.Canceled, .receive));
-    try testing.expectEqual(error.Unexpected, mapError(error.Unexpected, .send));
+test "a local cause stays an error instead of becoming a fault" {
+    try testing.expectError(error.OutOfMemory, fault(error.OutOfMemory, .connect));
+    try testing.expectError(error.Canceled, fault(error.Canceled, .receive));
+    try testing.expectError(error.Unexpected, fault(error.Unexpected, .send));
 }
 
-test "mapError maps the collapsed tls errors regardless of phase" {
-    try testing.expectEqual(error.TlsFailed, mapError(error.TlsInitializationFailed, .connect));
-    try testing.expectEqual(error.TlsFailed, mapError(error.TlsInitializationFailed, .receive));
-    try testing.expectEqual(error.TlsFailed, mapError(error.CertificateBundleLoadFailure, .connect));
+test "an unnamed connect errno is a connect fault, so the pool fails over" {
+    const outcome = try fault(error.Unexpected, .connect);
+    try testing.expectEqual(transport.PeerFault.ConnectFailed, outcome.fault.kind);
+    try testing.expectEqual(error.Unexpected, outcome.fault.cause);
 }
 
-test "mapError maps every unwrapped record-layer cause to TlsFailed" {
+test "kindOf maps the collapsed tls errors regardless of phase" {
+    try testing.expectEqual(error.TlsFailed, kindOf(error.TlsInitializationFailed, .connect));
+    try testing.expectEqual(error.TlsFailed, kindOf(error.TlsInitializationFailed, .receive));
+    try testing.expectEqual(error.TlsFailed, kindOf(error.CertificateBundleLoadFailure, .connect));
+}
+
+test "kindOf maps every unwrapped record-layer cause to TlsFailed" {
     // The set is the one `Connection.getReadError` can hand back, so the loop
     // fails the day std adds a member the switch does not name.
     inline for (@typeInfo(std.crypto.tls.Client.ReadError).error_set.?) |member| {
         try testing.expectEqual(
-            transport.ExchangeError.TlsFailed,
-            mapError(@field(std.crypto.tls.Client.ReadError, member.name), .receive),
+            transport.PeerFault.TlsFailed,
+            kindOf(@field(std.crypto.tls.Client.ReadError, member.name), .receive),
         );
     }
 }
 
-test "mapError maps remaining errors by phase" {
-    try testing.expectEqual(error.ConnectFailed, mapError(error.ConnectionRefused, .connect));
-    try testing.expectEqual(error.SendFailed, mapError(error.WriteFailed, .send));
-    try testing.expectEqual(error.ReceiveFailed, mapError(error.ReadFailed, .receive));
-    try testing.expectEqual(error.ReceiveFailed, mapError(error.HttpHeadersInvalid, .receive));
+test "kindOf maps remaining errors by phase" {
+    try testing.expectEqual(error.ConnectFailed, kindOf(error.ConnectionRefused, .connect));
+    try testing.expectEqual(error.SendFailed, kindOf(error.WriteFailed, .send));
+    try testing.expectEqual(error.ReceiveFailed, kindOf(error.ReadFailed, .receive));
+    try testing.expectEqual(error.ReceiveFailed, kindOf(error.HttpHeadersInvalid, .receive));
+}
+
+test "a fault carries the classification and the concrete cause" {
+    const failed = try faultOf(error.ConnectionRefused, .connect);
+    try testing.expectEqual(transport.PeerFault.ConnectFailed, failed.kind);
+    try testing.expectEqual(@as(anyerror, error.ConnectionRefused), failed.cause);
+
+    var buf: [64]u8 = undefined;
+    try testing.expectEqualStrings(
+        "ConnectFailed (cause ConnectionRefused)",
+        try std.fmt.bufPrint(&buf, "{f}", .{failed}),
+    );
 }
 
 /// Only the fields the unwrap helpers read are set. The rest of a `Connection`
@@ -398,6 +408,15 @@ fn stubConnection(
     return connection;
 }
 
+/// The fault half of `fault`, for the unwrap tests. A local cause leaves this
+/// as an error, which is what those tests assert instead.
+fn faultOf(err: anyerror, phase: Phase) !transport.Fault {
+    return switch (try fault(err, phase)) {
+        .reply => error.TestExpectedFault,
+        .fault => |f| f,
+    };
+}
+
 fn stubRequest(connection: *Connection, body_err: ?std.http.Reader.BodyError) Request {
     var req: Request = undefined;
     req.connection = connection;
@@ -408,59 +427,46 @@ fn stubRequest(connection: *Connection, body_err: ?std.http.Reader.BodyError) Re
 test "the send unwrap keeps a cancelled write out of the peer fault group" {
     var connection = stubConnection(null, error.Canceled);
     var req = stubRequest(&connection, null);
-    const mapped = mapError(sendCause(&req, error.WriteFailed), .send);
-    try testing.expectEqual(transport.ExchangeError.Canceled, mapped);
-    try testing.expectEqual(transport.Group.cancellation, transport.group(mapped));
+    try testing.expectError(error.Canceled, fault(sendCause(&req, error.WriteFailed), .send));
 }
 
 test "the send unwrap keeps a local resource write failure out of the peer fault group" {
     var connection = stubConnection(null, error.SystemResources);
     var req = stubRequest(&connection, null);
-    const mapped = mapError(sendCause(&req, error.WriteFailed), .send);
-    try testing.expectEqual(transport.ExchangeError.SystemResources, mapped);
-    try testing.expectEqual(transport.Group.local_resource, transport.group(mapped));
+    try testing.expectError(error.SystemResources, fault(sendCause(&req, error.WriteFailed), .send));
 }
 
 test "the send unwrap reports a peer side cause as a send fault" {
     var connection = stubConnection(null, error.ConnectionResetByPeer);
     var req = stubRequest(&connection, null);
-    try testing.expectEqual(
-        transport.ExchangeError.SendFailed,
-        mapError(sendCause(&req, error.WriteFailed), .send),
-    );
+    const failed = try faultOf(sendCause(&req, error.WriteFailed), .send);
+    try testing.expectEqual(transport.PeerFault.SendFailed, failed.kind);
+    try testing.expectEqual(@as(anyerror, error.ConnectionResetByPeer), failed.cause);
 }
 
 test "the head unwrap keeps a local resource read failure out of the peer fault group" {
     var connection = stubConnection(error.SystemResources, null);
     var req = stubRequest(&connection, null);
-    const mapped = mapError(headCause(&req, error.ReadFailed), .receive);
-    try testing.expectEqual(transport.ExchangeError.SystemResources, mapped);
-    try testing.expectEqual(transport.Group.local_resource, transport.group(mapped));
+    try testing.expectError(error.SystemResources, fault(headCause(&req, error.ReadFailed), .receive));
 
     var canceled = stubConnection(error.Canceled, null);
     var canceled_req = stubRequest(&canceled, null);
-    try testing.expectEqual(
-        transport.ExchangeError.Canceled,
-        mapError(headCause(&canceled_req, error.ReadFailed), .receive),
-    );
+    try testing.expectError(error.Canceled, fault(headCause(&canceled_req, error.ReadFailed), .receive));
 }
 
 test "the head unwrap reports a peer side cause as a receive fault" {
     var connection = stubConnection(error.ConnectionResetByPeer, null);
     var req = stubRequest(&connection, null);
-    try testing.expectEqual(
-        transport.ExchangeError.ReceiveFailed,
-        mapError(headCause(&req, error.ReadFailed), .receive),
-    );
+    const failed = try faultOf(headCause(&req, error.ReadFailed), .receive);
+    try testing.expectEqual(transport.PeerFault.ReceiveFailed, failed.kind);
+    try testing.expectEqual(@as(anyerror, error.ConnectionResetByPeer), failed.cause);
 }
 
 test "the body unwrap keeps a cancelled read out of the peer fault group" {
     var connection = stubConnection(error.Canceled, null);
     var req = stubRequest(&connection, null);
     const resp: Response = .{ .request = &req, .head = undefined };
-    const mapped = mapError(bodyCause(&resp, error.ReadFailed), .receive);
-    try testing.expectEqual(transport.ExchangeError.Canceled, mapped);
-    try testing.expectEqual(transport.Group.cancellation, transport.group(mapped));
+    try testing.expectError(error.Canceled, fault(bodyCause(&resp, error.ReadFailed), .receive));
 }
 
 test "the body unwrap prefers an http framing fault over the connection" {
@@ -471,10 +477,9 @@ test "the body unwrap prefers an http framing fault over the connection" {
     var req = stubRequest(&connection, error.HttpChunkTruncated);
     const resp: Response = .{ .request = &req, .head = undefined };
     try testing.expectEqual(error.HttpChunkTruncated, bodyCause(&resp, error.ReadFailed));
-    try testing.expectEqual(
-        transport.ExchangeError.ReceiveFailed,
-        mapError(bodyCause(&resp, error.ReadFailed), .receive),
-    );
+    const failed = try faultOf(bodyCause(&resp, error.ReadFailed), .receive);
+    try testing.expectEqual(transport.PeerFault.ReceiveFailed, failed.kind);
+    try testing.expectEqual(@as(anyerror, error.HttpChunkTruncated), failed.cause);
 }
 
 test "the unwraps report the collapsed error when no cause was stored" {
@@ -486,14 +491,13 @@ test "the unwraps report the collapsed error when no cause was stored" {
     try testing.expectEqual(error.ReadFailed, headCause(&req, error.ReadFailed));
     try testing.expectEqual(error.ReadFailed, bodyCause(&resp, error.ReadFailed));
 
-    try testing.expectEqual(
-        transport.ExchangeError.SendFailed,
-        mapError(sendCause(&req, error.WriteFailed), .send),
-    );
-    try testing.expectEqual(
-        transport.ExchangeError.ReceiveFailed,
-        mapError(bodyCause(&resp, error.ReadFailed), .receive),
-    );
+    const sent = try faultOf(sendCause(&req, error.WriteFailed), .send);
+    try testing.expectEqual(transport.PeerFault.SendFailed, sent.kind);
+    try testing.expectEqual(@as(anyerror, error.WriteFailed), sent.cause);
+
+    const received = try faultOf(bodyCause(&resp, error.ReadFailed), .receive);
+    try testing.expectEqual(transport.PeerFault.ReceiveFailed, received.kind);
+    try testing.expectEqual(@as(anyerror, error.ReadFailed), received.cause);
 }
 
 test "the unwraps pass a non-collapsed error through untouched" {
@@ -506,8 +510,7 @@ test "the unwraps pass a non-collapsed error through untouched" {
     try testing.expectEqual(error.EndOfStream, sendCause(&req, error.EndOfStream));
     try testing.expectEqual(error.HttpHeadersInvalid, headCause(&req, error.HttpHeadersInvalid));
     try testing.expectEqual(error.EndOfStream, bodyCause(&resp, error.EndOfStream));
-    try testing.expectEqual(
-        transport.ExchangeError.ReceiveFailed,
-        mapError(headCause(&req, error.HttpHeadersInvalid), .receive),
-    );
+    const failed = try faultOf(headCause(&req, error.HttpHeadersInvalid), .receive);
+    try testing.expectEqual(transport.PeerFault.ReceiveFailed, failed.kind);
+    try testing.expectEqual(@as(anyerror, error.HttpHeadersInvalid), failed.cause);
 }

src/upstream/doh_client_integration_test.zig

@@ -0,0 +1,78 @@
+//! Hermetic loopback test for `doh_client.zig`.
+//!
+//! It lives in its own file because it needs `@import("build_options")`, which
+//! only exists when the compilation is driven by build.zig. `-Dintegration`
+//! gates it; nothing here leaves the machine and nothing here resolves a name.
+//!
+//! What it covers that the stub-connection tests in `doh_client.zig` cannot:
+//! those call the unwrap and classification helpers directly, so they prove the
+//! helpers and not the path. This drives the whole of `DohClient.exchange`
+//! against a peer that is provably not listening, and asserts that the concrete
+//! cause survives the classification and reaches the returned `Fault`. Without
+//! it, a future `exchange` that dropped the cause on the floor would still pass
+//! every other test in this tree.
+
+const std = @import("std");
+const build_options = @import("build_options");
+const net = std.Io.net;
+
+const doh_client = @import("doh_client.zig");
+const transport = @import("transport.zig");
+
+const testing = std.testing;
+
+/// A query for example.com A: id 0x1234, RD set, one question.
+const query_bytes =
+    "\x12\x34\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00" ++
+    "\x07example\x03com\x00\x00\x01\x00\x01";
+
+/// A loopback TCP port that is bound and never listening, held open for the
+/// whole test.
+///
+/// Bound, because an ephemeral port the kernel hands out is the only port a
+/// test can be sure of; a hardcoded one could belong to something. Held rather
+/// than closed, because a closed port is free for another process on this
+/// machine to take between the close and the connect, and then the refusal this
+/// test asserts would be a connection instead. Never listening, because a
+/// connect to a bound TCP port with no accept queue is refused, which is the
+/// deterministic peer failure the test needs.
+fn bindDeadPort(io: std.Io) !net.Socket {
+    return (net.IpAddress{ .ip4 = .loopback(0) }).bind(io, .{ .mode = .stream });
+}
+
+test "a refused connection reaches the caller as a ConnectFailed carrying its cause" {
+    if (!build_options.integration) return error.SkipZigTest;
+
+    const gpa = testing.allocator;
+    var threaded: std.Io.Threaded = .init(gpa, .{});
+    defer threaded.deinit();
+    const io = threaded.io();
+
+    var dead = try bindDeadPort(io);
+    defer dead.close(io);
+
+    var url_buf: [64]u8 = undefined;
+    const url = try std.fmt.bufPrint(&url_buf, "https://127.0.0.1:{d}/dns-query", .{dead.address.ip4.port});
+
+    var http: std.http.Client = .{ .allocator = gpa, .io = io };
+    defer http.deinit();
+
+    var request_buf: [doh_client.min_request_buf]u8 = undefined;
+    var transfer_buf: [doh_client.min_transfer_buf]u8 = undefined;
+    var doh = try doh_client.DohClient.init(&http, try .parse(url), &request_buf, &transfer_buf);
+
+    var response_buf: [512]u8 = undefined;
+    switch (try doh.exchange(io, query_bytes, &response_buf)) {
+        .reply => return error.TestExpectedFault,
+        .fault => |fault| {
+            try testing.expectEqual(transport.PeerFault.ConnectFailed, fault.kind);
+            try testing.expectEqual(@as(anyerror, error.ConnectionRefused), fault.cause);
+
+            var text: [64]u8 = undefined;
+            try testing.expectEqualStrings(
+                "ConnectFailed (cause ConnectionRefused)",
+                try std.fmt.bufPrint(&text, "{f}", .{fault}),
+            );
+        },
+    }
+}

src/upstream/doh_client_live_test.zig

@@ -44,10 +44,10 @@ fn runExchange(io: std.Io, params: Params) anyerror!usize {
     const endpoint = try transport.Endpoint.parse("https://cloudflare-dns.com/dns-query");
     var doh = try doh_client.DohClient.init(&http, endpoint, &request_buf, &transfer_buf);
 
-    var selected: ?[]const u8 = null;
-    const reply = try doh.client().exchange(io, query_bytes, params.response_buf, &selected);
-    std.debug.assert(std.mem.eql(u8, selected.?, endpoint.url));
-    return reply.len;
+    return switch (try doh.leaf().exchange(io, query_bytes, params.response_buf)) {
+        .reply => |reply| reply.len,
+        .fault => |failed| failed.kind,
+    };
 }
 
 fn expire(io: std.Io, duration: std.Io.Clock.Duration) std.Io.Cancelable!void {

src/upstream/dot_client.zig

@@ -186,7 +186,7 @@ pub const DotClient = struct {
         }
     }
 
-    pub fn client(self: *DotClient) transport.Client {
+    pub fn leaf(self: *DotClient) transport.Leaf {
         return .{ .ptr = self, .exchangeFn = exchangeFn };
     }
 
@@ -199,12 +199,8 @@ pub const DotClient = struct {
         io: std.Io,
         query: []const u8,
         response_buf: []u8,
-        selected: *?[]const u8,
-    ) transport.ExchangeError![]u8 {
+    ) transport.LeafError!transport.Outcome {
         const self: *DotClient = @ptrCast(@alignCast(ptr));
-        // The endpoint outlives the client, so the borrow is safe for the whole
-        // query. Set before the attempt: a failure names this resolver too.
-        selected.* = self.endpoint.url;
         return self.exchange(io, query, response_buf);
     }
 
@@ -222,24 +218,24 @@ pub const DotClient = struct {
         io: std.Io,
         query: []const u8,
         response_buf: []u8,
-    ) transport.ExchangeError![]u8 {
+    ) transport.LeafError!transport.Outcome {
         // The length prefix is 16-bit, so a longer query cannot be framed. No
         // listener in this process can produce one; a caller that does gets a
         // local error rather than a silently truncated frame.
         if (query.len > transport.max_message_len) return error.BufferTooSmall;
 
         const reused = self.session != null;
-        if (!reused) try self.dial(io);
+        if (!reused) if (try self.dial(io)) |dial_fault| return .{ .fault = dial_fault };
 
         const failure = switch (self.transact(query, response_buf)) {
-            .ok => |reply| return reply,
+            .ok => |reply| return .{ .reply = reply },
             .failed => |failure| failure,
         };
 
         switch (retryDecision(reused, failure.received_any, failure.cause)) {
             .final => {
                 self.close(io);
-                return transport.mapPhase(failure.cause, failure.phase);
+                return .{ .fault = try transport.faultOrLocal(failure.cause, failure.phase) };
             },
             .retry => {},
         }
@@ -249,38 +245,42 @@ pub const DotClient = struct {
         // `reuse_recoveries` is what makes the churn visible.
         log.debug("{f}", .{self.diagnose(.{ .stale_session = failure.cause })});
         self.close(io);
-        try self.dial(io);
+        if (try self.dial(io)) |dial_fault| return .{ .fault = dial_fault };
 
         switch (self.transact(query, response_buf)) {
             .ok => |reply| {
                 if (self.reuse_recoveries) |counter| _ = counter.fetchAdd(1, .monotonic);
-                return reply;
+                return .{ .reply = reply };
             },
             // The retry's outcome is the exchange's outcome: one redial, never
             // two.
             .failed => |retried| {
                 self.close(io);
-                return transport.mapPhase(retried.cause, retried.phase);
+                return .{ .fault = try transport.faultOrLocal(retried.cause, retried.phase) };
             },
         }
     }
 
     /// Opens a session and leaves it in `self.session`, or leaves `self.session`
-    /// null and returns the classified failure. No partially initialized
-    /// session ever survives this call.
-    fn dial(self: *DotClient, io: std.Io) transport.ExchangeError!void {
+    /// null and returns the classified fault. `null` means a session is open. No
+    /// partially initialized session ever survives this call.
+    fn dial(self: *DotClient, io: std.Io) transport.LeafError!?transport.Fault {
         std.debug.assert(self.session == null);
 
         const address = resolveAddress(self.endpoint) catch |err| {
+            // A host that is not an IP literal is a config error, and
+            // `resolveAddress` has already folded the parse failure into the
+            // classification, so the cause it carries is the classification.
             log.warn("{f}", .{self.diagnose(.not_an_ip_literal)});
-            return err;
+            return .{ .kind = err, .cause = err };
         };
 
-        try self.ensureBundle(io);
+        if (try self.ensureBundle(io)) |bundle_fault| return bundle_fault;
 
         const stream = address.connect(io, .{ .mode = .stream }) catch |err| {
             log.debug("{f}", .{self.diagnose(.{ .connect_failed = err })});
-            return transport.mapPhase(err, error.ConnectFailed);
+            if (transport.mapLocalConnect(err)) |local| return local;
+            return .{ .kind = error.ConnectFailed, .cause = err };
         };
 
         // Emplaced before the handshake, never built beside it and copied in:
@@ -314,8 +314,9 @@ pub const DotClient = struct {
                 .verify_name = self.verify_name,
                 .cause = cause,
             } })});
-            return transport.mapPhase(cause, error.TlsFailed);
+            return try transport.faultOrLocal(cause, error.TlsFailed);
         };
+        return null;
     }
 
     /// One query and one reply on the open session, with enough detail on
@@ -380,17 +381,17 @@ pub const DotClient = struct {
     /// cancellation into `error.CertificateBundleLoadFailure`. That name cannot
     /// tell an `error.OutOfMemory` from a corrupt PEM file, and the first is a
     /// local resource failure that must not count against the upstream's
-    /// health. Scanning here keeps the concrete error for `transport.mapPhase`.
-    fn ensureBundle(self: *DotClient, io: std.Io) transport.ExchangeError!void {
+    /// health. Scanning here keeps the concrete error for the fault.
+    fn ensureBundle(self: *DotClient, io: std.Io) transport.LeafError!?transport.Fault {
         {
             try self.bundle_lock.lockShared(io);
             defer self.bundle_lock.unlockShared(io);
-            if (self.bundle.map.count() != 0) return;
+            if (self.bundle.map.count() != 0) return null;
         }
 
         try self.bundle_lock.lock(io);
         defer self.bundle_lock.unlock(io);
-        if (self.bundle.map.count() != 0) return;
+        if (self.bundle.map.count() != 0) return null;
 
         // A partial scan leaves entries in `map`, which the check above would
         // read as "already loaded". Reset so the next exchange scans again.
@@ -398,8 +399,9 @@ pub const DotClient = struct {
             self.bundle.deinit(self.gpa);
             self.bundle.* = .empty;
             log.warn("{f}", .{self.diagnose(.{ .bundle_load_failed = err })});
-            return transport.mapPhase(err, error.TlsFailed);
+            return try transport.faultOrLocal(err, error.TlsFailed);
         };
+        return null;
     }
 };
 
@@ -642,40 +644,39 @@ fn stubStream(
 
 test "the handshake unwrap keeps a cancelled read out of the peer fault group" {
     var stream = stubStream(error.Canceled, null, null);
-    const mapped = transport.mapPhase(concreteHandshake(&stream, error.ReadFailed), error.TlsFailed);
-    try testing.expectEqual(transport.ExchangeError.Canceled, mapped);
-    try testing.expectEqual(transport.Group.cancellation, transport.group(mapped));
+    try testing.expectError(
+        error.Canceled,
+        transport.faultOrLocal(concreteHandshake(&stream, error.ReadFailed), error.TlsFailed),
+    );
 }
 
 test "the handshake unwrap keeps a local resource write failure out of the peer fault group" {
     var stream = stubStream(null, error.SystemResources, null);
-    const mapped = transport.mapPhase(concreteHandshake(&stream, error.WriteFailed), error.TlsFailed);
-    try testing.expectEqual(transport.ExchangeError.SystemResources, mapped);
-    try testing.expectEqual(transport.Group.local_resource, transport.group(mapped));
+    try testing.expectError(
+        error.SystemResources,
+        transport.faultOrLocal(concreteHandshake(&stream, error.WriteFailed), error.TlsFailed),
+    );
 }
 
 test "the handshake unwrap reports a peer side cause as a TLS fault" {
     var reset = stubStream(error.ConnectionResetByPeer, null, null);
-    try testing.expectEqual(
-        transport.ExchangeError.TlsFailed,
-        transport.mapPhase(concreteHandshake(&reset, error.ReadFailed), error.TlsFailed),
-    );
+    const read_failed = try transport.faultOrLocal(concreteHandshake(&reset, error.ReadFailed), error.TlsFailed);
+    try testing.expectEqual(transport.PeerFault.TlsFailed, read_failed.kind);
+    try testing.expectEqual(@as(anyerror, error.ConnectionResetByPeer), read_failed.cause);
 
     var refused = stubStream(null, error.ConnectionRefused, null);
-    try testing.expectEqual(
-        transport.ExchangeError.TlsFailed,
-        transport.mapPhase(concreteHandshake(&refused, error.WriteFailed), error.TlsFailed),
-    );
+    const write_failed = try transport.faultOrLocal(concreteHandshake(&refused, error.WriteFailed), error.TlsFailed);
+    try testing.expectEqual(transport.PeerFault.TlsFailed, write_failed.kind);
+    try testing.expectEqual(@as(anyerror, error.ConnectionRefused), write_failed.cause);
 }
 
 test "the handshake unwrap reports a TLS fault when no cause was stored" {
     var stream = stubStream(null, null, null);
     try testing.expectEqual(error.ReadFailed, concreteHandshake(&stream, error.ReadFailed));
     try testing.expectEqual(error.WriteFailed, concreteHandshake(&stream, error.WriteFailed));
-    try testing.expectEqual(
-        transport.ExchangeError.TlsFailed,
-        transport.mapPhase(concreteHandshake(&stream, error.ReadFailed), error.TlsFailed),
-    );
+    const failed = try transport.faultOrLocal(concreteHandshake(&stream, error.ReadFailed), error.TlsFailed);
+    try testing.expectEqual(transport.PeerFault.TlsFailed, failed.kind);
+    try testing.expectEqual(@as(anyerror, error.ReadFailed), failed.cause);
 }
 
 test "the handshake unwrap passes other errors through untouched" {
@@ -685,42 +686,52 @@ test "the handshake unwrap passes other errors through untouched" {
         concreteHandshake(&stream, error.CertificateExpired),
     );
     try testing.expectEqual(error.Canceled, concreteHandshake(&stream, error.Canceled));
-    try testing.expectEqual(
-        transport.ExchangeError.TlsFailed,
-        transport.mapPhase(concreteHandshake(&stream, error.CertificateExpired), error.TlsFailed),
-    );
-    try testing.expectEqual(
-        transport.ExchangeError.Canceled,
-        transport.mapPhase(concreteHandshake(&stream, error.Canceled), error.TlsFailed),
+    const expired = try transport.faultOrLocal(concreteHandshake(&stream, error.CertificateExpired), error.TlsFailed);
+    try testing.expectEqual(transport.PeerFault.TlsFailed, expired.kind);
+    try testing.expectEqual(@as(anyerror, error.CertificateExpired), expired.cause);
+    try testing.expectError(
+        error.Canceled,
+        transport.faultOrLocal(concreteHandshake(&stream, error.Canceled), error.TlsFailed),
     );
 }
 
-/// What `exchange` would return for a failure `transact` reported.
-fn mappedFailure(outcome: Transact) transport.ExchangeError {
-    return transport.mapPhase(outcome.failed.cause, outcome.failed.phase);
+/// The fault `exchange` returns for a failure `transact` reported. A local cause leaves this as an
+/// error, which is what the tests of those causes assert instead.
+fn mappedFailure(outcome: Transact) transport.LeafError!transport.Fault {
+    return transport.faultOrLocal(outcome.failed.cause, outcome.failed.phase);
 }
 
 test "the send and receive unwraps prefer the stored cause" {
     var send = stubStream(null, error.Canceled, null);
-    try testing.expectEqual(
-        transport.ExchangeError.Canceled,
-        mappedFailure(sendFailed(&send, error.WriteFailed)),
-    );
+    try testing.expectError(error.Canceled, mappedFailure(sendFailed(&send, error.WriteFailed)));
 
     // The TLS client's own error wins over the socket reader's.
     var receive = stubStream(error.ConnectionResetByPeer, null, error.TlsAlert);
-    try testing.expectEqual(
-        transport.ExchangeError.ReceiveFailed,
-        mappedFailure(receiveFailed(&receive, error.ReadFailed, false)),
-    );
+    const received = try mappedFailure(receiveFailed(&receive, error.ReadFailed, false));
+    try testing.expectEqual(transport.PeerFault.ReceiveFailed, received.kind);
+    try testing.expectEqual(@as(anyerror, error.TlsAlert), received.cause);
 
     var socket = stubStream(error.SystemResources, null, null);
-    try testing.expectEqual(
-        transport.ExchangeError.SystemResources,
+    try testing.expectError(
+        error.SystemResources,
         mappedFailure(receiveFailed(&socket, error.ReadFailed, true)),
     );
 }
 
+test "a transact failure becomes a fault carrying its concrete cause" {
+    var stream = stubStream(null, error.ConnectionResetByPeer, null);
+
+    const sent = try mappedFailure(sendFailed(&stream, error.WriteFailed));
+    try testing.expectEqual(transport.PeerFault.SendFailed, sent.kind);
+    try testing.expectEqual(@as(anyerror, error.ConnectionResetByPeer), sent.cause);
+
+    var text: [64]u8 = undefined;
+    try testing.expectEqualStrings(
+        "SendFailed (cause ConnectionResetByPeer)",
+        try std.fmt.bufPrint(&text, "{f}", .{sent}),
+    );
+}
+
 test "a send failure is always pre-first-byte, and a receive failure reports what it read" {
     // The retry rule reads `received_any`, so where it comes from is part of the
     // contract rather than an incidental field: nothing is read before the query
@@ -804,14 +815,13 @@ test "a validation failure is final and its phase survives the mapping" {
     };
     for (outcomes) |outcome| {
         try testing.expectEqual(RetryDecision.final, retryDecision(true, true, outcome.cause));
-        try testing.expectEqual(
-            @as(transport.ExchangeError, outcome.phase),
-            mappedFailure(.{ .failed = .{
+        const failed = try mappedFailure(.{ .failed = .{
             .cause = outcome.cause,
             .phase = outcome.phase,
             .received_any = true,
-            } }),
-        );
+        } });
+        try testing.expectEqual(outcome.phase, failed.kind);
+        try testing.expectEqual(outcome.cause, failed.cause);
     }
 }
 
@@ -830,26 +840,21 @@ test "a CA bundle scan failure keeps local resource errors out of the peer fault
             transport.Group.local_resource,
             transport.group(transport.mapPhase(err, error.TlsFailed)),
         );
+        try testing.expectError(err, transport.faultOrLocal(err, error.TlsFailed));
     }
 
-    try testing.expectEqual(
-        transport.ExchangeError.Canceled,
-        transport.mapPhase(error.Canceled, error.TlsFailed),
-    );
+    try testing.expectError(error.Canceled, transport.faultOrLocal(error.Canceled, error.TlsFailed));
 
     // A missing or corrupt bundle is not this process running out of anything,
-    // so it stays a TLS fault.
-    try testing.expectEqual(
-        transport.ExchangeError.TlsFailed,
-        transport.mapPhase(error.FileNotFound, error.TlsFailed),
-    );
-    try testing.expectEqual(
-        transport.ExchangeError.TlsFailed,
-        transport.mapPhase(error.MissingEndCertificateMarker, error.TlsFailed),
-    );
+    // so it stays a TLS fault, and the cause names which of the two it was.
+    for ([_]anyerror{ error.FileNotFound, error.MissingEndCertificateMarker }) |err| {
+        const failed = try transport.faultOrLocal(err, error.TlsFailed);
+        try testing.expectEqual(transport.PeerFault.TlsFailed, failed.kind);
+        try testing.expectEqual(err, failed.cause);
+    }
 }
 
-test "DotClient satisfies the Client interface" {
+test "DotClient satisfies the Leaf interface" {
     const gpa = testing.allocator;
 
     const buffer = try gpa.alloc(u8, 4 * tls.Client.min_buffer_len);
@@ -878,7 +883,7 @@ test "DotClient satisfies the Client interface" {
     dot.close(undefined);
     try testing.expect(dot.session == null);
 
-    const iface: transport.Client = dot.client();
+    const iface: transport.Leaf = dot.leaf();
     try testing.expectEqual(@as(*anyopaque, @ptrCast(&dot)), iface.ptr);
 }